# Document Recognition API documentation

> Synchronous document recognition over HTTP.

Every example in these docs runs against the public sandbox with the key `sk_sandbox_public` (10 requests/hour/IP, real recognition, free). A registered account gets 100 free documents every month, used before paid credits; after that each recognized document costs one cent ($0.01), and a failed scan costs nothing.

## Home

- [Overview](/docs/index.md): Turn a photo of a passport or ID card into structured JSON with one HTTP call. Run the example here, then pick a guide or the reference.
## Get started

- [Overview](/docs/start.md): Three ways in: your first call with the public sandbox key, moving to a live key of your own, and recognizing a document without writing code.
- [Your first recognition](/docs/start/first-recognition.md): Send one image to the recognition API with the public sandbox key, read the extracted fields, and check what the call cost you.
- [From sandbox to live](/docs/start/from-sandbox-to-live.md): Register an account, use its 100 free documents every month, issue your own live key and point an existing integration at it.
- [Without writing code](/docs/start/recognize-without-code.md): Upload a document in the dashboard, read the extracted fields on screen, and decide whether the API fits before writing an integration.
## Guides

- [Overview](/docs/guides.md): Task-shaped instructions: recognizing each kind of document, handling errors and retries, controlling retention, managing keys, and tracking spend.
- [Recognize a passport](/docs/guides/recognize-a-passport.md): Send a passport photo to the recognition API, choose the options that matter, and read the machine-readable zone and the visual fields.
- [Recognize an ID card](/docs/guides/recognize-an-id-card.md): Send a national ID card to the recognition API, including the two-sided case, and read the identity fields that come back.
- [Recognize a driver licence](/docs/guides/recognize-a-driver-licence.md): Send a driver licence to the recognition API, read the vehicle categories and dates, and handle the layouts that vary by country.
- [Handle errors](/docs/guides/handle-errors.md): Branch on the error code rather than the status, decide what to retry, and turn the documentation link in every error body into a fix.
- [Retry safely](/docs/guides/retry-safely-with-idempotency.md): Send an idempotency key so a retried recognition returns the first result instead of running and charging a second time.
- [Control retention](/docs/guides/control-history-retention.md): Choose how long a result is kept: per request, per account, or not at all, and understand what disappears when the window ends.
- [Rotate API keys](/docs/guides/rotate-api-keys.md): Issue a second key, move traffic onto it and revoke the old one, without a window in which calls fail.
- [Check an MRZ](/docs/guides/check-an-mrz.md): Verify the check digits of a machine-readable zone, read what a failed digit means, and decide what to do with the document.
- [Result images](/docs/guides/work-with-result-images.md): Ask for the portrait and the cropped document image, read them out of the response, and know how long each stays available.
- [Non-Latin scripts](/docs/guides/handle-non-latin-scripts.md): Read documents printed in Greek, Arabic or Han script: which values are transliterated, which are not, and how to get both spellings.
- [Without webhooks](/docs/guides/get-results-without-webhooks.md): The API answers in the same response, so there is no callback to register. This is how to fit that into a queue or a background worker.
- [Top up with crypto](/docs/guides/top-up-with-crypto.md): Send USDT to the permanent deposit address of your account and watch the credits arrive, including what to do if they do not.
- [Track usage and spend](/docs/guides/track-usage-and-spend.md): Read the balance and the period counters from the API, and reconcile them against what the dashboard shows for the same period.
- [Use the MCP server](/docs/guides/use-the-mcp-server.md): Install the MCP server with npx so a coding assistant can recognize a passport or ID, check the balance, work with stored scans and search these docs.
- [Use the AI SDK](/docs/guides/use-the-ai-sdk.md): Give a model built with the AI SDK five tools that recognize a passport, ID card or driver licence and work with stored scans and the balance.
- [Ionic and Capacitor](/docs/guides/read-a-passport-in-an-ionic-app.md): Take a passport photo with the Capacitor Camera plugin, send it through your own small server, and show the holder and document fields in the app.
- [OpenCV preprocessing](/docs/guides/crop-with-opencv.md): Find a document's outline in a photo with OpenCV, straighten it, and send the cropped image to doc.cheap from Python.
## Reference

- [Overview](/docs/reference.md): The exact contract: endpoints, response shapes, the field catalogue, scan options, errors, limits, idempotency and versioning.
- [The response](/docs/reference/response.md): The recognition result, group by group – every key, its type, when it is null, and what each value is derived from.
- [Field catalogue](/docs/reference/fields.md): Every field key the result publishes, with its label and category, and the rules that decide what appears in the list and what does not.
- [Languages and scripts](/docs/reference/fields/languages.md): How a reading's language is reported, the three steps that resolve it, and the full table of assigned language identifiers.
- [MRZ reference](/docs/reference/mrz.md): The machine-readable zone as this API publishes it – the lines, the unbroken text, the three formats, and how the check digits are reported.
- [Result images](/docs/reference/images.md): The seven image crops a recognition returns, their height caps, and the rules the re-encode follows.
- [Scan options](/docs/reference/scan-options.md): Every option on a scan request: what it changes, its default, its allowed values, and the options that interact with each other.
- [Errors](/docs/reference/errors.md): Every error code the recognition API returns, the HTTP status it comes with, and the page that states its cause and its fix.
- [Limits](/docs/reference/limits.md): The limits a caller meets: request rate, image size, request body size, idempotency key length and the retention windows on offer.
- [HTTP status codes](/docs/reference/http-status-codes.md): Every HTTP status this API answers with, the error codes that share it, and what separates them.
- [Idempotency](/docs/reference/idempotency.md): What makes two scan requests the same request, how long a key is remembered, and the three codes that arbitrate a replay.
- [Versioning](/docs/reference/versioning.md): One response shape, one version, and what a consumer can rely on.
- [Service levels](/docs/reference/service-levels.md): What this service measures, what it targets for latency and uptime, how incidents are published, and where the live figures come from.
- [Glossary](/docs/reference/glossary.md): The words this documentation uses with a precise meaning, and what each one means here.
- [API reference](/docs/reference/api.md): The full OpenAPI contract of the doc.cheap recognition API, rendered in the browser, with a server-rendered page per endpoint beside it.
- [Create a scan](/docs/reference/endpoints/create-a-scan.md): Reference for POST /v1/scans: request fields, headers, every documented response status with its example body, and the error codes it can return.
- [Retrieve a scan](/docs/reference/endpoints/retrieve-a-scan.md): Reference for GET /v1/scans/{id}: the path parameter, every documented response status with its example body, and the error codes it can return.
- [List scans](/docs/reference/endpoints/list-scans.md): Reference for GET /v1/scans: the history rows it returns, which scans it lists and for how long, every documented response status and its error codes.
- [Delete a scan](/docs/reference/endpoints/delete-a-scan.md): Reference for DELETE /v1/scans/{id}: what deleting a stored scan removes, what it does not give back, every documented response status and its error codes.
- [Get usage](/docs/reference/endpoints/get-usage.md): Reference for GET /v1/usage: the balance and period counters it returns, every documented response status with its example body, and its error codes.
- [Create a client token](/docs/reference/endpoints/create-a-client-token.md): Reference for POST /v1/client-tokens: the short-lived token that lets an app send a scan without the secret key, its limits and its error codes.
- [client_token_expired](/docs/errors/client_token_expired.md): A client token was used after its expiry. What raises it, and how to fix it.
- [client_token_not_allowed](/docs/errors/client_token_not_allowed.md): A client token was sent to an endpoint other than POST /v1/scans, or a token was requested without an API key. What raises it, and how to fix it.
- [client_token_used_up](/docs/errors/client_token_used_up.md): A client token was used more times than it allows. What raises it, and how to fix it.
- [document_repeated](/docs/errors/document_repeated.md): The same document was sent again within the window that guards against a duplicate charge. What raises it, and how to fix it.
- [engine_unavailable](/docs/errors/engine_unavailable.md): The recognition engine did not answer within its timeout; nothing was charged. What raises it, and how to fix it.
- [idempotency_conflict](/docs/errors/idempotency_conflict.md): 409 idempotency_conflict: this Idempotency-Key was first sent with a different body. This call did not run and cost nothing. Send it under a new key.
- [idempotency_in_progress](/docs/errors/idempotency_in_progress.md): The first request carrying this idempotency key has not finished yet. What raises it, and how to fix it.
- [idempotency_replay_unavailable](/docs/errors/idempotency_replay_unavailable.md): The first result for this idempotency key can no longer be replayed. What raises it, and how to fix it.
- [impersonation_read_only](/docs/errors/impersonation_read_only.md): Raised only on an administrative surface: an impersonated session may not write. What raises it, and how to fix it.
- [insufficient_credits](/docs/errors/insufficient_credits.md): This month's free credits and the paid credits are both used up, so the recognition cannot be reserved. What raises it, and how to fix it.
- [internal_error](/docs/errors/internal_error.md): An unexpected failure; nothing was charged and the response carries an event id. What raises it, and how to fix it.
- [invalid_request](/docs/errors/invalid_request.md): The request was malformed or an argument was outside the range the endpoint accepts. What raises it, and how to fix it.
- [maintenance](/docs/errors/maintenance.md): The service is in a planned maintenance window and is refusing requests for its duration. What raises it, and how to fix it.
- [not_found](/docs/errors/not_found.md): No resource matched the request, or the one that did has passed its retention window. What raises it, and how to fix it.
- [payload_too_large](/docs/errors/payload_too_large.md): The request body is over the size the endpoint accepts. What raises it, and how to fix it.
- [payment_driver_unavailable](/docs/errors/payment_driver_unavailable.md): Raised only on an administrative surface when a payment driver is not configured. What raises it, and how to fix it.
- [rate_limited](/docs/errors/rate_limited.md): The caller is over the request rate its key allows; the response says when to retry. What raises it, and how to fix it.
- [rate_unavailable](/docs/errors/rate_unavailable.md): The exchange rate needed to price this top-up could not be read. What raises it, and how to fix it.
- [registration_required](/docs/errors/registration_required.md): The public sandbox allowance is spent; an account of your own is needed to continue. What raises it, and how to fix it.
- [service_unavailable](/docs/errors/service_unavailable.md): A store this service depends on is unreachable, so the request cannot be served now. What raises it, and how to fix it.
- [topup_in_progress](/docs/errors/topup_in_progress.md): A top-up for this account is already being processed. What raises it, and how to fix it.
- [unauthorized](/docs/errors/unauthorized.md): The API key was missing, malformed, revoked or not valid for this endpoint. What raises it, and how to fix it.
- [unsupported_media_type](/docs/errors/unsupported_media_type.md): The content type or the image format is not one this endpoint reads. What raises it, and how to fix it.
- [validation_failed](/docs/errors/validation_failed.md): The request parsed but a field failed validation; the body names the field. What raises it, and how to fix it.
## Concepts

- [Overview](/docs/concepts.md): Why the API behaves as it does: what recognition actually does, what confidence means, what is billed, what is kept, and what fails.
- [How recognition works](/docs/concepts/how-recognition-works.md): What happens between sending an image and getting fields back: detection, classification, zone reading and the checks that follow.
- [Confidence and readings](/docs/concepts/confidence-and-readings.md): Why confidence is a band rather than a number, why one field can be read more than once, and what a verdict of not_checked is saying.
- [MRZ and visual zone](/docs/concepts/mrz-and-the-visual-zone.md): Why a document says the same thing twice, when the two zones disagree, and which one to believe in each of those cases.
- [What a billed scan is](/docs/concepts/what-a-billed-scan-is.md): One cent per document, and the rule that decides whether a call is charged at all: what makes a recognition billable, and what does not.
- [Retention and privacy](/docs/concepts/data-retention-and-privacy.md): What this service stores, for how long, what it never stores at all, and what zero retention means for a request and its result.
- [Keys and sessions](/docs/concepts/api-keys-and-sessions.md): The two ways a caller is identified – an API key and a dashboard session – what each may do, and why they are kept apart.
- [Crypto deposits](/docs/concepts/crypto-deposits.md): How a permanent deposit address is derived for an account, how a transfer becomes credits, and what the chain watcher does and does not promise.
- [Reliability](/docs/concepts/reliability.md): What this service promises when a dependency is away, what it charges in that case, and how a caller can tell a retry is worth making.
## Changelog

- [Changelog](/docs/changelog.md): Every change to the recognition API and to this documentation, dated, newest first, with an Atom feed and a page per month.
- [November 2026](/docs/changelog/2026-11.md): Changes to the doc.cheap document-recognition API and its documentation published in November 2026, dated and listed newest first.
- [October 2026](/docs/changelog/2026-10.md): Changes to the doc.cheap document-recognition API and its documentation published in October 2026, dated and listed newest first.
- [September 2026](/docs/changelog/2026-09.md): Changes to the doc.cheap document-recognition API and its documentation published in September 2026, dated and listed newest first.
## MCP server

- [doc.cheap MCP server](/.well-known/mcp/server-card.json): Install with `npx -y @doc-cheap/mcp` for six tools over stdio: scan_document (recognize a passport or ID, $0.01 per recognized document), check_balance, search_docs, and list_scans, get_scan and delete_scan for stored scans. This card names the package, the transport and the environment variables; the how-to is at /docs/guides/use-the-mcp-server.md.