Doc

Recognise a passport, national ID card or driver's licence from a photo or scan and return what is printed on it as structured JSON. Inputs: the image as image_base64 or image_url (https, on a public address); plus the optional expect_country, return_portrait, retain_hours, reference and idempotency_key. Output: a Scan object – meta (id, status, billed, confidence, timing), document (kind, issuing country, number, series, date of issue, date of expiry, whether it has expired and how many days are left), holder (given names, surname, date of birth, sex, nationality) – country codes are the document's own three-letter ICAO codes, each with a *_detail object giving the code as written, its ISO 3166-1 alpha-3 and alpha-2 and its category, fields (every field read off the printed page, each with its own confidence), mrz (whether the machine-readable zone checks out, why not when it does not, and its lines exactly as read), images, quality and authenticity – plus a one-line summary of the same result. Calls POST /v1/scans. Cost: it bills one credit ($0.01) only when a document is recognised; an unreadable image, an empty frame or an unsupported type costs nothing, and meta.billed says which happened. Without a key, the public sandbox key is used. It gives 10 free recognised documents per address in all, and at most 10 requests per address an hour, whatever their answer. Registering gives 100 free documents every month. Use test images only, never a real document. Use it whenever someone hands over an identity document and wants it read, transcribed, or checked against what they claim – a name, a document number, a date of birth or an expiry date.

Return how many credits are left on the account and what the current period has used: the balance, split into this month's free credits (100 every month, drawn first) and the paid credits, the credits spent, and the scan counters broken down by status (recognized, unreadable, no document found, unsupported document, rejected). Takes no arguments and calls GET /v1/usage; under the public sandbox key it answers without calling anything. One recognised document draws one credit, at $0.01; scans that recognised nothing are counted and never charged. Needs a real API key – under the public sandbox key there is no account behind the call, and the answer says so instead of reporting zeros that read like a balance. Use it before working through a batch of documents, or when a scan is refused for lack of credit.

Takes no parameters.

Full-text search over the doc.cheap API documentation – endpoints, request options, every response field, the error codes and what to do about each, MRZ rules, retention and pricing. Takes a query and an optional limit (1 to 20, default 5), and answers with the matching sections: title, a snippet, and a link to the page. It reads a copy of the documentation shipped beside this server, so it makes no network call and works offline. Use it before guessing at a field name, an error code or a scan option – what it returns is the published contract rather than a recollection of it.

List the account's stored scans, most recent first, one page at a time. Inputs: the optional limit (1 to 100 rows, default 20) and cursor (the next_cursor of the previous page; omit it for the first page). Output: scans – one row per scan with id, status (recognized, unreadable, no_document_found, unsupported_document or rejected), billed, duration_ms, reference (your own string from the scan) and created_at – and next_cursor, which is null on the last page. A row holds no extracted data; call get_scan with its id for the full result. Calls GET /v1/scans; it never charges a credit. Only scans made with a live key under a non-zero retention window are stored for the account, and only until that window ends (retain_hours on the scan, or the account's history-retention setting, one year by default); a scan made with retain_hours 0 was never stored. A key reaches its own account's scans and no other account's. Under a sandbox key nothing can be read back: an account's own sk_sandbox_ key stores nothing, and the public key keeps every scan for one year, with a reduced thumbnail and the address it came from, where that key cannot read, list or delete it. Under the public sandbox key the answer is an empty list, given without calling the API. Errors: a cursor this API did not issue is refused (validation_failed); a key the API does not know is refused (unauthorized). Use it to find a scan made earlier – by its reference or its time – before reading or deleting it.

Fetch the full result of one stored scan by its id, as it was returned when the document was recognised. Input: scan_id – meta.id of a scan_document result, or id of a list_scans row. Output: the same Scan object scan_document returns (meta, document, holder, fields, mrz and the rest) plus a one-line summary, with two differences: the image crops are never stored, so every images slot is null, and quality reads not_checked. Calls GET /v1/scans/{id}; it never re-runs recognition and never charges a credit. Only scans made with a live key under a non-zero retention window are stored for the account, and only until that window ends (retain_hours on the scan, or the account's history-retention setting, one year by default); a scan made with retain_hours 0 was never stored. A key reaches its own account's scans and no other account's. Under a sandbox key nothing can be read back: an account's own sk_sandbox_ key stores nothing, and the public key keeps every scan for one year, with a reduced thumbnail and the address it came from, where that key cannot read, list or delete it. Errors: an id that is unknown, belongs to another account, was made with retain_hours 0 or has passed its window is refused as not_found – the cases are not told apart. Use it to read back a document recognised earlier instead of scanning the image again.

Permanently delete one stored scan now, before its retention window would end. This cannot be undone: the stored result, its history row and its thumbnail are removed, and the scan can no longer be listed, fetched or replayed through its idempotency_key. The credit it drew is not refunded, and this period's usage counters still count it. Input: scan_id – meta.id of a scan_document result, or id of a list_scans row. Output: { id, deleted: true }. Calls DELETE /v1/scans/{id}. Only scans made with a live key under a non-zero retention window are stored for the account, and only until that window ends (retain_hours on the scan, or the account's history-retention setting, one year by default); a scan made with retain_hours 0 was never stored. A key reaches its own account's scans and no other account's. Under a sandbox key nothing can be read back: an account's own sk_sandbox_ key stores nothing, and the public key keeps every scan for one year, with a reduced thumbnail and the address it came from, where that key cannot read, list or delete it. Errors: an id that is unknown, belongs to another account, has passed its window or was already deleted is refused as not_found, and nothing is deleted. Use it when someone asks for a document's data to be removed; confirm the id with list_scans or get_scan first, because the deletion is final.