Skip to main content

Getting Started

This guide walks you through the minimum steps required to parse your first e-receipt using the BlinkReceipt E-Receipt API.

Prerequisites​

  • An active BlinkReceipt API key
  • A publicly reachable HTTPS endpoint to receive webhook results
  • A raw EML file from a supported retailer

Step 1: Configure Your Results Endpoint​

Before creating any jobs, tell the API where to deliver parsed results. You must configure at least a results_endpoint.

curl -X POST https://sandbox.blinkreceipt.com/ereceipts/config \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "results_endpoint": "https://your-server.com/webhooks/ereceipts",
    "day_cutoff": 14
  }'

Response:

{
  "success": true
}

See configuration.md for all available configuration fields.

Step 2: Add Retailers (Optional)​

If you want per-retailer cutoff windows that differ from your global setting, add them to your configuration.

curl -X POST https://sandbox.blinkreceipt.com/ereceipts/config \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "results_endpoint": "https://your-server.com/webhooks/ereceipts",
    "day_cutoff": 30,
    "retailers": [
      { "email": "auto-confirm@amazon.com", "day_cutoff": 7 },
      { "email": "noreply@ebay.com", "day_cutoff": 14 }
    ]
  }'

Step 3: Create a Job​

Submit an EML email for parsing. The eml_data field contains the raw EML content. The email_hash field is the SHA-256 hash of the user's email address.

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=abc123def456..." \
  --data-urlencode "provider=gmail" \
  --data-urlencode "client_user_id=user_789"

Response:

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

Save the job_id — you will use it to check the job status.

Step 4: Poll for Job Status​

Check whether the job has finished processing.

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": "abc123def456...",
    "client_user_id": "user_789",
    "status": "completed",
    "processing_time": 3.2,
    "created_at": "2024-08-01 10:00:00",
    "updated_at": "2024-08-01 10:00:03"
  }
}

The status field cycles through: queued → executing → completed (or error).

Step 5: Receive Results at Your Webhook​

Once the job status is completed, the API sends a POST request to your configured results_endpoint containing an array of parsed receipt objects.

[
  {
    "blinkReceiptId": "BR-XXXX-YYYY",
    "ereceiptEmailId": "msg-id-from-provider",
    "emailTimestamp": "2024-08-01 09:55",
    "merchantName": { "value": "Amazon", "confidence": 99 },
    "total": { "value": 59.99, "confidence": 95 },
    "products": [
      {
        "productName": "Wireless Mouse",
        "brand": "Logitech",
        "unitPrice": { "value": 59.99, "confidence": 95 },
        "quantity": { "value": 1, "confidence": 99 }
      }
    ]
  }
]

For the full receipt schema, see response-structure.md.

Testing Your Setup​

Use the simulate_results endpoint to send a sample payload to your webhook without creating a real job, or to preview the payload structure locally.

# Preview sample data without posting to your endpoint
curl "https://sandbox.blinkreceipt.com/ereceipts/simulate_results?post_to_remote=false" \
  -H "api-key: YOUR_API_KEY"

# Post a test payload to your configured results_endpoint
curl "https://sandbox.blinkreceipt.com/ereceipts/simulate_results?post_to_remote=true" \
  -H "api-key: YOUR_API_KEY"

See endpoints.md for the complete endpoint reference and error-handling.md for a full list of error codes.