Endpoint Reference

All endpoints share the same base URLs and authentication model.

Base URLs:

• Sandbox: https://sandbox.blinkreceipt.com
• Production: https://scan.blinkreceipt.com

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

---

Configuration

POST /ereceipts/config

Sets global scraping configuration for your account.

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
day_cutoff	integer	No*	Days back to search
date_cutoff	integer	No*	UNIX timestamp cutoff
use_aggregation	boolean	No	Aggregate multi-email orders
return_eml	boolean	No	Include raw EML in results
retailers	array	No	Per-retailer cutoff configs

Response:

{ "success": true }

---

GET /ereceipts/config

Returns the currently active account configuration.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Response:

{
  "success": true,
  "results_endpoint": "https://your-server.com/webhooks/ereceipts",
  "day_cutoff": 14,
  "use_aggregation": false,
  "return_eml": false,
  "retailers": []
}

---

Retailers

GET /ereceipts/retailers

Returns all retailers currently saved to your account configuration.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Response:

{
  "success": true,
  "retailers": [
    {
      "email": "auto-confirm@amazon.com",
      "day_cutoff": 7
    },
    {
      "email": "noreply@ebay.com",
      "day_cutoff": 30
    }
  ]
}

Retailer Object Fields:

Field	Type	Description
email	string	Sender email address
day_cutoff	integer	Per-retailer day cutoff (if set)
date_cutoff	integer	Per-retailer UNIX timestamp cutoff (if set)

---

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 raw email for parsing. Returns a job_id that you can use to poll for status.

Headers:

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

Request Body (form-encoded):

Field	Type	Required	Description
eml_data	string	Yes	Raw EML content of the email
email_hash	string	Yes	SHA-256 hash of the user's email address
provider	string	No	Email provider name (e.g., gmail, outlook)
client_user_id	string	No	Your internal user identifier for tracking
override_endpoint	string	No	One-time override for the results webhook URL
country_code	string	No	ISO 3166-1 alpha-2 country code (e.g., US)

Example Request:

curl -X POST https://sandbox.blinkreceipt.com/ereceipts/create_job \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "eml_data@/path/to/receipt.eml" \
  --data-urlencode "email_hash=abc123..." \
  --data-urlencode "provider=gmail" \
  --data-urlencode "client_user_id=user_42"

Response:

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

---

POST /ereceipts/reprocess_job

Reprocesses previously ingested receipts. Useful for re-extracting data after a parser update or configuration change. You must supply either blink_receipt_ids or retailers — not both.

Headers:

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

Request Body:

Field	Type	Required	Description
blink_receipt_ids	array of strings	No*	Specific receipt IDs to reprocess
retailers	array	No*	Retailer configs to reprocess all matching receipts

Example — reprocess by IDs:

{
  "blink_receipt_ids": ["BR-AAAA-1111", "BR-BBBB-2222"]
}

Example — reprocess by retailers:

{
  "retailers": [
    { "email": "auto-confirm@amazon.com", "day_cutoff": 7 }
  ]
}

Response:

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

Errors specific to this endpoint:

Code	Description
112	Must specify either blink_receipt_ids or retailers
113	Cannot specify both blink_receipt_ids and retailers
114	One or more Blink Receipt IDs was not found

---

GET /ereceipts/status

Polls the processing status of a job created by create_job or reprocess_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 or reprocess_job

Example Request:

curl "https://sandbox.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.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Response:

{
  "status": "ok",
  "message": "E-receipt system is operational"
}

---

GET /ereceipts/simulate_results

Sends a sample results payload to your webhook or returns a sample payload locally. Use this to test your webhook integration without submitting real emails.

Headers:

Header	Required	Description
api-key	Yes	Your API key

Query Parameters:

Parameter	Type	Required	Default	Description
post_to_remote	boolean	No	true	When true, POSTs the sample payload to your configured results_endpoint. When false, returns the payload in the response body
results_endpoint	string	No	—	Override the destination URL for this test call only

Example — preview locally:

curl "https://sandbox.blinkreceipt.com/ereceipts/simulate_results?post_to_remote=false" \
  -H "api-key: YOUR_API_KEY"

Response when post_to_remote=false: An array of sample EReceipt objects (see response-structure.md).

Response when post_to_remote=true:

{ "success": true }

---

POST /ereceipts/clear_history

Removes stored user data. Intended for testing and development use.

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
clientUserId	string	No	The client user ID whose history should be cleared

Example Request:

{
  "emailAddress": "user@example.com",
  "clientUserId": "user_42"
}

Response:

{ "success": true }