API v1 · REST · JSON

Turn any document into clean JSON.

The DocuSense API reads invoices, tax slips, pay stubs and bank statements and returns named, typed fields — with a confidence score, automatic checks and signed webhooks.

Start in 5 minutes API reference

18endpoints
16languages
13document types
HMACsigned webhooks

terminal

$ 
201 Created · 1.3 s
{
  "documentType": "INVOICE",
  "classificationConfidence": 0.98,
  "extractedData": {
    "invoiceNumber": "INV-0425",
    "vendor": { "name": "Example Supplies Inc." },
    "total": 4280.52,
    "currency": "CAD"
  },
  "checkStatus": "ok"
}

Getting started

Authentication

Every request carries your API key in the X-API-Key header. Create keys in Dashboard → API keys; a key is shown once, then only its prefix.

Keep keys on your server. Never put an API key in a browser, a mobile app or a public repository. Read it from an environment variable (DOCUSENSE_API_KEY in every sample below). If a key leaks, revoke it in the dashboard: it stops working immediately.

All traffic is HTTPS. Requests without a valid key get 401 UNAUTHORIZED; requests the key's permissions do not allow get 403 INSUFFICIENT_PERMISSION.

The base URL is:

https://api.docusense.pro/api/v1

Getting started

Quickstart

Three calls take a PDF from your disk to structured data. Pick your language once — every sample on the page follows.

1
Send the document
Base64-encode the file and post it. documentType: "AUTO" recognises the type for you. Small files come back extracted in the same response (201).
2
Large files: go asynchronous
Add "async": true to get 202 at once, then poll the job — or better, receive the document.completed webhook.
3
Read the result
Retrieve the document: extracted fields, confidence, automatic checks and review state.

Getting started

Permissions

Give each key only what it needs — an ingestion server needs documents:write, a reporting job only documents:read.

documents:read

List, read and export documents, follow jobs and batches, search, reconciliation and tax folder.

documents:write

Upload documents and batches, correct fields, approve or reject reviews, run checks again.

documents:delete

Delete documents. Give it only to the keys that really need it.

Getting started

Document types

Send AUTO to let DocuSense detect the type, or a type below to skip detection. Each type is included from a plan; a type your plan does not include returns 403 PLAN_REQUIRED with the plan to choose.

documentType	Document	Plan
`INVOICE`	Invoices (lines, taxes, totals, vendor, buyer)	Basic
`EXTRACT`	Any document — custom fields you name	Basic
`BANK_STATEMENT`	Bank statements (balances, transactions)	Pro
`T4` · `ROE` · `PAYSTUB_CA`	Canadian slips, record of employment, pay stubs	Pro
`W2`	US W-2 forms	Pro
`P60` · `P45`	UK end-of-year and leaving certificates	Pro
`PAYSTUB_EU`	European payslips (send `country`)	Pro
`RL1`	Québec RL-1 slips	Ultra
`AVIS_IMPOSITION`	French tax notices	Ultra
`CONTRACT`	Contract analysis (parties, terms, risks)	Ultra

Accepted files: PDF, JPG, PNG, WEBP, DOCX, XLSX, CSV — 10 MB per file, 60 MB per batch. Every file is checked (format signature, active PDF content, antivirus) before it is processed.

Getting started

Errors

Errors always use the same shape: a stable code to branch on, and a message written for people. Never parse the message — it may change.

Status	code	What to do
400	`VALIDATION_ERROR`	Fix the request; `details` lists each field.
400	`FILE_TYPE_MISMATCH`	The bytes do not match `mimeType`.
401	`UNAUTHORIZED`	Missing, wrong or revoked key.
403	`INSUFFICIENT_PERMISSION`	Use a key with the right permission.
403	`PLAN_REQUIRED`	Upgrade to `requiredPlan`.
404	`NOT_FOUND`	Unknown id — or one that is not yours.
409	`NOT_READY` · `NOT_IN_REVIEW`	Wait for the extraction, or check the state first.
422	`PDF_ACTIVE_CONTENT` · `FILE_INFECTED`	The file was refused for security reasons.
422	`EXTRACTION_FAILED`	Try again or choose another `documentType`.
429	`RATE_LIMIT_EXCEEDED`	Wait for `Retry-After` seconds.
429	`USAGE_LIMIT_EXCEEDED`	Monthly pages used up: upgrade or wait for the next period.
503	`MAINTENANCE` · `ASYNC_UNAVAILABLE`	Temporary: retry with backoff.

403 Forbidden
{
  "success": false,
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "Document type T4 requires the PRO plan. Current plan: BASIC.",
    "requiredPlan": "PRO"
  }
}

Getting started

Rate limits

Limits protect every customer. Each response carries the standard RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers; a 429 also carries Retry-After.

30/minDocument uploads per key owner

20/hourBatch uploads

20/minSearches

200/minAll requests from one IP

Your monthly page quota depends on your plan (50 on Basic, then 1,000, 5,000 and 20,000). Check it with GET /documents/usage.

Getting started

Pagination

List endpoints take page (from 1) and limit (up to 100, 50 for batches) and return a pagination object. Stop when page reaches pages.

"pagination": {
  "page": 1,
  "limit": 20,
  "total": 128,
  "pages": 7
}

Events

Webhooks

Instead of polling, add a connection in Dashboard → Integrations: DocuSense posts an event to your URL as soon as something happens.

Event	When
`document.processing`	Extraction started
`document.completed`	Extraction finished — the event most integrations use
`document.failed`	Extraction failed (the page is refunded)
`document.review_required`	A human check is needed
`batch.processing` · `batch.completed` · `batch.partial` · `batch.failed`	Batch progress Pro
`rule.triggered`	One of your rules matched Pro

Verify every call

Each request carries X-DocuSense-Signature: t=<unix time>,v1=<hex>: an HMAC-SHA256 of t + "." + raw body with your connection's signing secret. Check it on the raw body, with a constant-time comparison, and refuse timestamps older than 5 minutes. Also sent: X-DocuSense-Event and X-DocuSense-Delivery (unique id, use it to ignore duplicates).

Delivery and retries

Answer any 2xx within 10 seconds, then do the work.
5xx, 408, 429 and timeouts are retried up to 6 times with exponential backoff (about 30 s → 30 min).
Redirects are not followed, and private or local addresses are refused.
extractedData is in the payload only when the connection has “Include extracted data” on; otherwise call GET /documents/{id}.

Verify the signature ·

Payload · document.completed

{
  "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
  "event": "document.completed",
  "created_at": "2026-10-08T14:02:20.000Z",
  "data": {
    "id": "8f3c2b1e-4a5d-4c6e-9f70-1a2b3c4d5e6f",
    "documentType": "INVOICE",
    "status": "COMPLETED",
    "reviewRequired": false,
    "tags": ["approval_required"],
    "extractedData": { "total": 4280.52, "currency": "CAD" }
  }
}

Best practices

Security checklist

Keys stay server-side

Environment variables or a secret manager — never a browser, an app or a repository. One key per system, so you can revoke one without stopping the others.

Least privilege

Give each key only the permissions it uses. documents:delete is rarely needed.

Verify webhooks

Check the HMAC signature and the timestamp on every call, and ignore deliveries you already processed.

Handle 429 politely

Respect Retry-After and back off exponentially. Do not re-upload a document blindly: list first to avoid paying twice.

Minimise data

Fetch the extracted data when you need it and delete documents you no longer need. Identifiers (SIN, account numbers) are already masked.

Report a problem

Found a vulnerability? Write to [email protected] — please do not test on other customers' data.

Stability

Versioning & changelog

The version is in the path (/api/v1). Within a version we only make additive changes: new endpoints, new optional fields, new events and error codes — write your code to ignore fields it does not know. A breaking change ships as /v2, announced at least 6 months before v1 is retired.

October 2026
v1.0 — Public API: documents (sync and async, AUTO detection), corrections, exports, batches, review, smart search, reconciliation, tax folder and signed webhooks.

Loading the API reference…