# 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).

## 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, claim the free documents it comes with, 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 and search these docs from your editor.
## 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 would count as a breaking change to it.
- [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.
- [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.
- [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): The idempotency key was reused with a different request body. What raises it, and how to fix it.
- [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): The balance cannot cover the reservation this recognition needs. 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.
- [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 three tools over stdio: scan_document (recognize a passport or ID, $0.01 per recognized document), check_balance and search_docs. This card names the package, the transport and the environment variables; the how-to is at /docs/guides/use-the-mcp-server.md.