Receipt Processing API

Transform receipt images into structured JSON data in seconds. Our OCR-powered API extracts transaction details, account information, amounts, and timestamps from bank transfer receipts.

Getting Started: Create an account and generate your API token from your profile settings to start processing receipts.

Authentication

All API requests require a Bearer token in the Authorization header.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://readceipt.com/api/receipts

Get your API token: Navigate to your Profile page after signing up to generate tokens.

Base URL

https://readceipt.com/api

Process Receipt

Upload a receipt image and extract structured transaction data.

Request

POST /receipts
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN

Parameters:

  • receipt (file, required) - Image file up to 10MB
  • Supported formats: JPEG, PNG, PDF, WebP

Examples

curl -X POST "https://readceipt.com/api/receipts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "[email protected]"

Response

Success (200 OK):

{
  "status": "SUCCESS",
  "reference": "FT23120512345678",
  "transaction_datetime": "2023-12-05T14:30:25",
  "destination_bank_name": "Bank of Maldives",
  "amount": {
    "currency": "MVR",
    "amount": 1500.00
  },
  "from_account": {
    "account_name": "John Doe",
    "account_number": "7701234567890"
  },
  "to_account": {
    "account_name": "Jane Smith", 
    "account_number": "7709876543210"
  },
  "remarks": "Payment for services",
  "type": "bml",
  "verified": true,
  "parsed_at": "2023-12-05T14:30:47Z",
  "duration_ms": 847
}

With Warnings:

{
  "status": "SUCCESS",
  "reference": "FT23120512345678",
  "transaction_datetime": "2023-12-05T14:30:25",
  "destination_bank_name": "Bank of Maldives",
  "amount": {
    "currency": "MVR",
    "amount": 1500.00
  },
  "from_account": {
    "account_name": "John Doe",
    "account_number": "7701234567890"
  },
  "to_account": {
    "account_name": "Jane Smith", 
    "account_number": "7709876543210"
  },
  "remarks": "Payment for services",
  "type": "bml",
  "verified": false,
  "parsed_at": "2023-12-05T14:30:47Z",
  "duration_ms": 847,
  "warnings": [
    "Amount MVR 1500.0 not clearly found in OCR text"
  ]
}

Response Fields

FieldTypeDescription
statusstringTransaction status
referencestringUnique transaction reference
transaction_datetimestringDate and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
destination_bank_namestring?Name of destination bank
amount.currencystringCurrency code (MVR, USD, etc.)
amount.amountnumberTransaction amount
from_account.account_namestringSender name
from_account.account_numberstring?Sender account number
to_account.account_namestringRecipient name
to_account.account_numberstring?Recipient account number
remarksstring?Transaction remarks or notes
typestringBank type (bml, mib, or other)
verifiedbooleanWhether data passed all verification checks
parsed_atstringISO 8601 timestamp when parsing completed (UTC)
duration_msnumberProcessing time in milliseconds
warningsstring?Data quality warnings (null if verified is true)

New Fields: The response now includes verified, parsed_at, and warnings fields to help you assess data quality. Fields marked with ? are optional.

Data Quality: When verified is false, check the warnings array for specific issues. The extracted data is still likely correct, but you should review it before use.


Error Handling

All errors return JSON with descriptive messages:

{
  "message": "Error description here"
}

Status Codes

CodeErrorDescription
400Bad RequestInvalid file format or corrupted image
401UnauthorizedMissing or invalid API token
403ForbiddenRate limit or quota exceeded
413Payload Too LargeFile exceeds 10MB limit
422Unprocessable EntityCannot extract data from image
500Internal Server ErrorProcessing error occurred

Common Errors

{
  "message": "Invalid bearer token"
}

Rate Limits

Usage limits are based on your subscription plan:

PlanMonthly RequestsPer MinuteFile Size
Free1025MB
Starter1001010MB
Pro1,0006010MB
Enterprise10,000+12025MB

Rate Limit Headers: Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

View all pricing plans →


Best Practices

Image Quality

  • Use clear, well-lit images
  • Ensure text is readable and not blurred
  • Avoid shadows or reflections
  • Crop to focus on the receipt content

Data Quality & Warnings

The API now provides data quality indicators with each response:

const result = await response.json();

if (!result.verified) {
  console.warn('Data quality issues detected:', result.warnings);
  
  // Example warnings:
  // - "Reference partially matched in OCR (possible OCR error)"
  // - "Amount MVR 1500.0 not clearly found in OCR text"
  // - "Currency 'MVR' not found in OCR text"
  
  // Decide how to handle based on your use case:
  // - Show warnings to user for review
  // - Request manual verification
  // - Flag for quality assurance
}

// The data is still extracted, even with warnings
processReceipt(result);

Understanding Verification Status:

  • verified: true - All data fully validated against OCR text (high confidence)
  • verified: false - Some data couldn't be fully verified (check warnings array)

Common Warnings:

WarningMeaningAction
"Reference partially matched"OCR may have misread part of referenceUsually safe, OCR error
"Amount not clearly found"Amount value not detected in OCRVerify amount is correct
"Currency not found"Currency code missing from OCRCheck currency matches receipt
"Account name not found"Account name not in OCR textVerify account details

Error Handling

try {
  const response = await fetch('/receipts', options);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  const data = await response.json();
  
  // Handle warnings if present
  if (!data.verified && data.warnings) {
    console.warn('Receipt processed with warnings:', data.warnings);
    // Optionally prompt user to review
  }
  
  return data;
} catch (error) {
  console.error('Receipt processing failed:', error.message);
  // Handle error appropriately
}

Security

  • Store API tokens securely
  • Never expose tokens in client-side code
  • Use environment variables for tokens
  • Rotate tokens regularly

Working with DateTime

The API returns combined date and time in ISO 8601 format:

const result = await response.json();

// Parse the datetime
const transactionDate = new Date(result.transaction_datetime);

console.log(transactionDate.toLocaleDateString()); // "12/5/2023"
console.log(transactionDate.toLocaleTimeString()); // "2:30:25 PM"
console.log(transactionDate.toLocaleString());     // "12/5/2023, 2:30:25 PM"

// Format with date-fns or moment.js
import { format } from 'date-fns';
const formatted = format(transactionDate, 'PPpp'); // "Dec 5, 2023 at 2:30:25 PM"

Timezone Note: transaction_datetime is a naive datetime (no timezone) representing the local time shown on the receipt. parsed_at includes timezone (UTC) for server timestamp.


Quick Start

Get up and running in 3 steps:

Create Account

Sign up for a free account to get started.

Get API Token

Generate your API token from your profile settings.

Process Receipt

Upload your first receipt using any of the code examples above.


Support

Need help? We're here to assist you:

  • Email: [email protected]
  • Documentation: Browse our guides and examples
  • Community: Join our developer community

Ready to start? Create your account and process your first receipt today!

© 2026 Trava. All rights reserved.