API Documentation

The ReceiptOCR API allows you to extract structured data from receipt images using a simple REST endpoint.

Base URL: https://api.receiptocr.co.za

Authentication

All API requests require an API key passed in the Authorization header as a Bearer token.

Sign up at receiptocr.co.za
Navigate to Dashboard > API Keys
Click “Create New Key” and copy the generated key

Include the key in your requests:

http

Authorization: Bearer sk_live_your_api_key

Keep your API keys secret. Do not share them in client-side code, public repositories, or anywhere publicly accessible. If a key is compromised, revoke it immediately from the dashboard.

Scan Endpoint

POST/api/v1/scan

Upload a receipt image and receive structured data as JSON. Supports JPEG, PNG, and PDF formats up to 10MB.

Each successful scan consumes 1 token from your balance. Failed scans do not consume tokens.

Request Format

Option 1: Multipart Form Data

Send the receipt image as a file upload using multipart/form-data.

Field	Type	Required	Description
`file`	File	Yes	The receipt image file (JPEG, PNG, or PDF)

bash

curl -X POST https://api.receiptocr.co.za/api/v1/scan \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "file=@receipt.jpg"

Option 2: JSON with Base64

Send the receipt image as a base64-encoded string in a JSON body.

Field	Type	Required	Description
`image`	String	Yes	Base64-encoded image with data URI prefix

bash

curl -X POST https://api.receiptocr.co.za/api/v1/scan \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

Response Format

Successful responses return a JSON object with the extracted receipt data and metadata.

json

{
  "success": true,
  "data": {
    "vendor": {
      "name": "Woolworths",
      "address": "123 Main Rd, Cape Town, 8001",
      "phone": "+27 21 555 0123",
      "vatNumber": "4210123456"
    },
    "date": "2025-01-15",
    "time": "14:32",
    "currency": "ZAR",
    "lineItems": [
      {
        "description": "Full Cream Milk 2L",
        "quantity": 1,
        "unitPrice": 32.99,
        "total": 32.99,
        "confidence": 0.98
      },
      {
        "description": "Whole Wheat Bread",
        "quantity": 2,
        "unitPrice": 18.49,
        "total": 36.98,
        "confidence": 0.96
      }
    ],
    "subtotal": 69.97,
    "tax": {
      "rate": 15,
      "amount": 9.13,
      "inclusive": true
    },
    "total": 69.97,
    "paymentMethod": "VISA **** 4521",
    "receiptNumber": "RC-2025-001234",
    "confidence": 0.97
  },
  "meta": {
    "processingTimeMs": 1842,
    "tokensUsed": 1,
    "tokensRemaining": 49
  }
}

Response Fields

Field	Type	Description
`vendor.name`	string	Name of the vendor/store
`vendor.address`	string	Vendor address if detected
`vendor.phone`	string	Vendor phone number if detected
`vendor.vatNumber`	string	VAT registration number if detected
`date`	string	Transaction date in YYYY-MM-DD format
`time`	string	Transaction time in HH:MM format
`currency`	string	ISO 4217 currency code (e.g., ZAR, USD)
`lineItems[]`	array	Array of line items with description, quantity, unitPrice, total, and confidence
`subtotal`	number	Subtotal before tax
`tax.rate`	number	Tax rate percentage
`tax.amount`	number	Tax amount
`tax.inclusive`	boolean	Whether tax is included in the total
`total`	number	Total amount
`paymentMethod`	string	Payment method if detected (e.g., VISA **** 4521)
`receiptNumber`	string	Receipt/transaction reference number
`confidence`	number	Overall confidence score (0-1)
`meta.processingTimeMs`	number	Processing time in milliseconds
`meta.tokensUsed`	number	Tokens consumed for this request
`meta.tokensRemaining`	number	Remaining token balance

Error Codes

Errors return a JSON object with success: false and an error object.

json

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_TOKENS",
    "message": "Not enough tokens. Balance: 0, required: 1.",
    "status": 402
  }
}

Status	Code	Description
400	`BAD_REQUEST`	Invalid request format or missing required fields.
401	`UNAUTHORIZED`	Missing or invalid API key.
402	`INSUFFICIENT_TOKENS`	Not enough tokens to process the request.
403	`FORBIDDEN`	API key has been revoked or account is suspended.
404	`NOT_FOUND`	The requested endpoint does not exist.
413	`FILE_TOO_LARGE`	Image exceeds the maximum file size of 10MB.
415	`UNSUPPORTED_TYPE`	File type not supported. Use JPEG, PNG, or PDF.
422	`PROCESSING_FAILED`	Could not extract data from the image.
429	`RATE_LIMITED`	Too many requests. Check rate limit headers.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

Code Examples

bash

curl -X POST https://api.receiptocr.co.za/api/v1/scan \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "file=@receipt.jpg"

Rate Limits

Rate limits are applied per API key and per user account to ensure fair usage.

Scope	Limit	Window
Per API Key	60 requests	1 minute
Per API Key	1,000 requests	1 hour
Per User Account	5,000 requests	24 hours

Rate limit information is included in response headers:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706012400