eScanX API Reference

Everything you need to integrate our intelligent document OCR API into your applications.

Authentication

Authenticate your API requests using the X-API-Key header. Get your API key from the dashboard after signing up.

Include your API key in every request:

# Sample: list async jobs (any authenticated endpoint works the same way)
curl https://api.escanx.com/api/v1/jobs \
  -H "X-API-Key: YOUR_API_KEY"

API Playground

Try the extraction endpoint live. Pick a document type, paste your API key, upload a file, and run a real request.

Document Extraction

Extract structured data from documents (receipts, invoices, etc.) via our intelligent OCR engine.

Request

Send a document image as multipart/form-data.

curl -X POST https://api.escanx.com/api/v1/extract/receipt \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@receipt.jpg"

Response

The extraction object is nested and document-type-specific — switch the document type above to see each shape.

{
  "success": true,
  "request_id": "req_abc123def456",
  "processing_time_ms": 1250,
  "document_type": "receipt",
  "extraction": {
    "merchant": {
      "name": "Helsinki Market",
      "address": {
        "city": "Helsinki",
        "country_code": "FI"
      },
      "business_id": "1234567-8"
    },
    "buyer": {
      "name": "Aurora Digital Oy",
      "business_id": "7788990-1"
    },
    "transaction": {
      "date": "2025-01-15",
      "time": "14:30",
      "receipt_number": "A-4471"
    },
    "items": [
      {
        "line_number": 1,
        "description": "Coffee 250g",
        "quantity": 1,
        "unit_price": 4.9,
        "item_total": 4.9
      }
    ],
    "financial": {
      "subtotal": 43.1,
      "tax": [
        {
          "rate": 25.5,
          "amount": 4.75
        }
      ],
      "tax_total": 4.75,
      "total": 47.85,
      "currency": "EUR"
    },
    "payments": [
      {
        "method": "card",
        "card_type": "Visa",
        "card_last4": "4242",
        "amount": 47.85
      }
    ],
    "loyalty": {
      "card_number": "9012345678",
      "points_earned": 12,
      "points_balance": 340
    },
    "metadata": {
      "sub_type": "grocery",
      "confidence": {
        "overall": 0.97
      }
    }
  },
  "error": null
}

Async Jobs

Submit documents for asynchronous extraction. Ideal for large files or batch workflows where you don't need immediate results.

Submit a Job

Submit a document for background processing. Returns a job ID you can poll for results.

curl -X POST https://api.escanx.com/api/v1/jobs/invoice \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Check Job Status

Poll the job status until it reaches a terminal state.

curl https://api.escanx.com/api/v1/jobs/JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

Webhooks

Instead of polling, provide a webhook_url when submitting a job. Your endpoint will receive a POST request when the job completes or fails. The response includes a webhook_secret for verifying request signatures.

# Submit job with webhook notification (webhook_url is a query parameter)
curl -X POST "https://api.escanx.com/api/v1/jobs/invoice?webhook_url=https://your-app.com/webhooks/escanx" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Store the webhook_secret returned in the job submission response. Use it to verify that incoming webhook requests are from eScanX.

List Jobs

List your extraction jobs with optional filters.

Cancel a Job

Cancel a job that is still in pending status.

Retry a Job

Retry a job that has failed.

Job Statistics

Get aggregate counts of your jobs and your current pending-job capacity.

curl https://api.escanx.com/api/v1/jobs/stats \
  -H "X-API-Key: YOUR_API_KEY"

Usage Statistics

Check your API usage, quota, and remaining calls for the current billing period.

curl "https://api.escanx.com/api/v1/usage?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Response

Health Checks

Monitor the API status with liveness and readiness endpoints. No authentication required.

Liveness Check

Returns OK if the API server is running.

curl https://api.escanx.com/health

Readiness Check

Returns OK if the API and all dependencies (database) are ready to serve requests.

curl https://api.escanx.com/health/ready

Error Handling

The API uses standard HTTP status codes. Error responses follow the RFC 7807 problem+json format with flat fields.

Error Response Format

Validation Errors (422)

Validation failures return a 422 with a detail array — one entry per invalid field, each with its location, message, and type.

HTTP Status Codes

Rate Limits

API requests are rate-limited per API key to ensure fair usage and platform stability.

How it works

Rate limits are applied per API key. When you exceed the limit, requests return HTTP 429.

Handling Rate Limits

Implement exponential backoff when you receive a 429 response.

async function extractWithRetry(file, documentType, maxRetries = 3) {
  const formData = new FormData()
  formData.append('file', file)

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(`https://api.escanx.com/api/v1/extract/${documentType}`, {
      method: 'POST',
      headers: { 'X-API-Key': 'YOUR_API_KEY' },
      body: formData
    })

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || '5'
      await new Promise(r => setTimeout(r, parseInt(retryAfter) * 1000))
      continue
    }

    return await response.json()
  }
  throw new Error('Max retries exceeded')
}

SDKs & Libraries

Official SDKs for popular programming languages are coming soon. For now, use our REST API directly with any HTTP client.

# Upload an invoice and extract structured data
curl -X POST https://api.escanx.com/api/v1/extract/invoice \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

# Check your API usage
curl https://api.escanx.com/api/v1/usage \
  -H "X-API-Key: YOUR_API_KEY"