Endpoint Reference

All endpoints share the same base URL and authentication model.

Base URL: https://api.blinkreceipt.com

Authentication: Every request requires an api-key header containing your BlinkReceipt API key.

---

Configuration

POST /ereceipts/config

Replaces your account configuration. Any field you omit is reset to its default, except retailers, which is preserved when omitted.

See configuration.md for the full field reference and examples.

Headers:

Header	Required	Description
api-key	Yes	Your API key
Content-Type	Yes	application/json

Request Body (JSON):

Field	Type	Required	Description
results_endpoint	string	Yes	Webhook URL for results delivery. Must be a valid, publicly reachable HTTPS URL
day_cutoff	integer	No*	Days back to search
date_cutoff	integer	No*	Earliest email date, as a UNIX timestamp in seconds
return_eml	boolean	No	Include raw EML in results
enable_pii_scrubbing	boolean	No	Redact PII from ereceiptEmailSubject and ereceiptRawHTMLtext
use_only_retailer_emails	boolean	No	Search only your retailers list
default_retailer_country_list	array of strings	No	Country codes whose retailers are also searched: US, UK, CA, AU, FR, DE, ZA, BE, NL
retailers	array	No	Per-retailer cutoff configs

Response: the stored configuration. See configuration.md.

---

GET /ereceipts/config

Returns the currently active account configuration.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Response:

{
  "results_endpoint": "https://your-server.com/webhooks/ereceipts",
  "return_eml": false,
  "default_retailer_country_list": [],
  "enable_pii_scrubbing": false,
  "use_only_retailer_emails": false,
  "date_cutoff": null,
  "date_cutoff_iso": null,
  "day_cutoff": 14,
  "retailers": []
}

---

Retailers

GET /ereceipts/retailers

Returns all retailers currently saved to your account configuration, as a bare array.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Response:

[
  {
    "email": "auto-confirm@amazon.com",
    "day_cutoff": 7
  },
  {
    "email": "noreply@ebay.com",
    "date_cutoff": 1719792000
  }
]

Retailer Object Fields:

Field	Type	Description
email	string	Sender email address or domain
day_cutoff	integer	Per-retailer day cutoff, if set
date_cutoff	integer	Per-retailer cutoff as a UNIX timestamp in seconds, if set

Only one of day_cutoff / date_cutoff appears per entry. A retailer with neither returns email alone.

---

DELETE /ereceipts/retailers

Removes one or more retailers from your configuration.

Headers:

Header	Required	Description
api-key	Yes	Your API key
Content-Type	Yes	application/json

Request Body:

Field	Type	Required	Description
retailer_emails	array of strings	Yes	Email addresses to remove

Example Request:

{
  "retailer_emails": [
    "auto-confirm@amazon.com",
    "noreply@ebay.com"
  ]
}

Response:

{ "success": true }

---

Jobs

POST /ereceipts/create_job

Submits a mailbox or a raw email for parsing. Returns a job_id that you can use to poll for status.

There are two ways to supply the source. Pass eml_data to parse a single raw email, or pass credentials and provider to connect to a mailbox over IMAP or OAuth.

Headers:

Header	Required	Description
api-key	Yes	Your API key
Content-Type	Yes	application/json or application/x-www-form-urlencoded

Request Body:

Field	Type	Required	Description
email_hash	string	No*	SHA-256 hash of the user's email address. May be sent alongside client_user_id
client_user_id	string	No*	Your internal user identifier. May be sent alongside email_hash
eml_data	string	No**	Base64-encoded raw EML content of a single email. Alternative to credentials and provider
provider	string	No**	Mailbox provider. Required when credentials is used
credentials	string	No**	Encrypted mailbox credentials. Requires provider
country_code	string	No	ISO 3166-1 alpha-2 country code (e.g., US)
override_endpoint	string	No	One-time override for the results webhook URL
override_date	string	No	One-time override for the cutoff date

You must supply at least one of email_hash or client_user_id. Supplying neither returns error code 118. Both may be sent together.

You must also supply either eml_data, or both credentials and provider. If eml_data is present, credentials and provider are ignored.

Provider Values:

Value	Connection
gmail-imap	IMAP
yahoo-imap	IMAP
yahoo-imap-alt	IMAP
aol-imap	IMAP
aol-imap-alt	IMAP
gmail-oauth	OAuth
outlook-oauth	OAuth

For the IMAP providers, credentials decrypts to email@domain.com:AppPassword. For the OAuth providers, it decrypts to the access token.

Example Request:

curl -X POST https://api.blinkreceipt.com/ereceipts/create_job \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eml_data": "UmVjZWl2ZWQ6IGZyb20...",
    "email_hash": "abc123...",
    "client_user_id": "user_42"
  }'

Response:

{
  "success": true,
  "job_id": 98765
}

Only one job may be in flight per user. Submitting a second returns error code 13.

---

GET /ereceipts/status

Polls the processing status of a job created by create_job.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Query Parameters:

Parameter	Type	Required	Description
job_id	number	Yes	The job ID returned by create_job

Example Request:

curl "https://api.blinkreceipt.com/ereceipts/status?job_id=98765" \
  -H "api-key: YOUR_API_KEY"

Response:

{
  "success": true,
  "job_status": {
    "id": 98765,
    "email_hash": "abc123...",
    "client_user_id": "user_42",
    "status": "completed",
    "error_code": null,
    "error_message": null,
    "processing_time": 3.2,
    "created_at": "2024-08-01 10:00:00",
    "updated_at": "2024-08-01 10:00:03"
  }
}

Job Status Values:

Status	Description
queued	Job is waiting to be picked up
executing	Job is actively being processed
completed	Processing finished successfully; results sent to webhook
error	Processing failed; check error_code and error_message

---

System

GET /ereceipts/health_check

Verifies that the e-receipt processing system is operational. Does not require an API key.

Response:

{ "status": "ok" }

---

POST /ereceipts/clear_history

Removes stored user data.

Headers:

Header	Required	Description
api-key	Yes	Your API key
Content-Type	Yes	application/json

Request Body:

Field	Type	Required	Description
emailAddress	string	No*	The user's email address whose history should be cleared. Takes precedence over clientUserId
clientUserId	string	No*	The client user ID whose history should be cleared. Used only when emailAddress is absent

You must supply at least one of emailAddress or clientUserId. Supplying neither returns error code 121. If you supply both, emailAddress is used and clientUserId is ignored.

Example Request:

{
  "emailAddress": "user@example.com"
}

Response:

{ "success": true }