Developer docs

Integrate document extraction into your app.

Reethal Cloud accepts a PDF or image and returns structured JSON in the same request. Files and extracted values are processed in memory and are not stored by Reethal Cloud.

Step 1

Create an API key

Open Dashboard settings, generate a live key, and store it server-side.

Step 2

Send a document

Post a PDF or image as multipart form data to the sync extraction endpoint.

Step 3

Use the JSON

Read the fields, confidence scores, validation state, and credit metadata.

Authentication

Use API keys only from your backend. Pass the key in the bearer token header. API keys start with sk_live_ and can be revoked or regenerated from the dashboard.

Authorization: Bearer sk_live_...

Never expose API keys in browser JavaScript, mobile app bundles, public repositories, or client-side environment variables.

Request examples

Send extraction requests from your backend using your preferred language.

curl -X POST "https://api.reethal.cloud/v1/extract/sync" \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@document.pdf" \
  -F "documentType=auto" \
  -F "schema=auto" \
  -F "pagesToScan=1"

Endpoint reference

Use API keys for extraction and credit balance checks. Keys are created and managed from the dashboard.

GET/v1/billing/balanceReturn remaining credits for AI scanning (1 credit = 1 page).

POST/v1/extract/syncExtract JSON from a PDF or image in one request.

Credit balance

Check how many pages your account can still scan before sending a document. The balance includes subscription, trial, and top-up credits. Business plan accounts return monthly page usage instead of a credit total.

{
  "plan": "trial",
  "creditBalance": 201,
  "subscriptionCreditsRemaining": 0,
  "trialCreditsRemaining": 50,
  "topUpCreditsRemaining": 151,
  "subscriptionCreditsExpireAt": null,
  "daysUntilReset": null,
  "pagesUsedThisCycle": null,
  "fairUseLimit": null,
  "isUnlimited": false
}

Request fields

fileRequired PDF or image file. Max size is 20 MB. PDFs can have up to 50 pages.

documentTypeUse auto, a built-in type, or custom.

schemaUse auto, a built-in schema id, or custom.

customSchemaOptional JSON schema when schema is custom.

pagesToScanNumber of pages to scan, from 1 to 50. One scanned page uses 1 credit.

webhookOptional URL for status notifications if your flow uses webhook mode.

Custom schema

Send a custom schema when you need fields outside the built-in document types. Keep field keys stable because they become the keys in the response JSON.

{
  "name": "Receipt",
  "fields": [
    {
      "key": "merchantName",
      "label": "Merchant Name",
      "type": "string",
      "required": true
    },
    {
      "key": "total",
      "label": "Total Amount",
      "type": "number",
      "required": true
    }
  ]
}

Response shape

Each field includes a value and confidence score. Metadata includes processing time, pages scanned, credits used, and the remaining credit balance when available.

{
  "documentId": "doc_sync",
  "documentType": "invoice_v1",
  "confidence": 96,
  "fields": {
    "invoiceNumber": {
      "value": "INV-1024",
      "confidence": 98
    },
    "total": {
      "value": 420.5,
      "confidence": 95
    }
  },
  "validationStatus": "passed",
  "validationErrors": [],
  "extractionMetadata": {
    "processingMs": 1240,
    "creditsUsed": 1,
    "remainingCredits": 49,
    "documentPages": 3,
    "pagesScanned": 1
  }
}

Credits and limits

1 scanned page uses 1 credit.
Credits are checked before extraction starts.
If the account has fewer credits than pages requested, extraction is rejected.
PDF uploads are limited to 50 pages per file.
Check remaining credits with GET /v1/billing/balance before large batch jobs.

Common errors

INSUFFICIENT_CREDITSThe account does not have enough credits for the selected pages.

PAGE_LIMIT_EXCEEDEDThe uploaded PDF has more than 50 pages.

INVALID_FILE_TYPEThe file is not a supported PDF or image.

INVALID_SCHEMAThe custom schema is not valid JSON.

UNAUTHORIZEDThe bearer token is missing, invalid, or revoked.

Ready to make a request?

Generate an API key from the dashboard, put it in your server environment variables, and send your first multipart request to the extraction endpoint.

Go to API keys