mcp

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

{
  "type": "object",
  "properties": {
    "image_base64": {
      "description": "The document image as base64 (a data: URL is also accepted).",
      "type": "string"
    },
    "image_url": {
      "description": "https: URL of an image on a public internet address, which the server fetches (25 MB maximum).",
      "type": "string"
    },
    "expect_country": {
      "description": "ISO 3166-1 alpha-3 country you expect, or omit for any.",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "return_portrait": {
      "description": "Whether to include the holder photograph crop, images.main_photo (default true).",
      "type": "boolean"
    },
    "retain_hours": {
      "description": "Hours the result stays readable via GET /v1/scans/{id} (0 = store nothing). Omit it to use the account's own history-retention setting.",
      "type": "integer",
      "minimum": 0,
      "maximum": 8760
    },
    "reference": {
      "description": "Your own correlation string, echoed back in the result.",
      "type": "string",
      "maxLength": 128
    },
    "idempotency_key": {
      "description": "Makes a retried scan return the first result instead of charging again.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "meta": {
      "$ref": "#/definitions/ScanMeta"
    },
    "document": {
      "anyOf": [
        {
          "$ref": "#/definitions/ScanDocument"
        },
        {
          "type": "null"
        }
      ]
    },
    "holder": {
      "anyOf": [
        {
          "$ref": "#/definitions/ScanHolder"
        },
        {
          "type": "null"
        }
      ]
    },
    "fields": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ScanField"
      },
      "description": "Every field the engine extracted off the printed document, re-keyed to our vocabulary – the open set. Always present; empty when nothing was extracted. A field read in more than one language appears once per language, so `name` repeats and only `id` is unique."
    },
    "mrz": {
      "$ref": "#/definitions/ScanMrz"
    },
    "images": {
      "$ref": "#/definitions/ScanImages"
    },
    "quality": {
      "$ref": "#/definitions/ScanQuality"
    },
    "authenticity": {
      "$ref": "#/definitions/ScanAuthenticity"
    }
  },
  "required": [
    "meta",
    "document",
    "holder",
    "fields",
    "mrz",
    "images",
    "quality",
    "authenticity"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "definitions": {
    "ScanMeta": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "const": "1.0",
          "description": "The version of this body, always `1.0`. A consumer that pins this value checks that the body is the one it was written against."
        },
        "id": {
          "$ref": "#/definitions/ScanId"
        },
        "status": {
          "$ref": "#/definitions/ScanStatus"
        },
        "billed": {
          "type": "boolean",
          "description": "Whether this scan was charged to the balance."
        },
        "confidence": {
          "description": "How strongly the recognition backs this reading as a whole. Each entry of `fields` carries its own band as well, and they can differ from this one.",
          "allOf": [
            {
              "$ref": "#/definitions/ConfidenceBand"
            }
          ]
        },
        "timing": {
          "anyOf": [
            {
              "$ref": "#/definitions/ScanTiming"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
          "description": "Timestamp, ISO-8601 in UTC (`YYYY-MM-DDTHH:MM:SSZ`)."
        },
        "reference": {
          "description": "The request's `reference`, echoed back.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "schema_version",
        "id",
        "status",
        "billed",
        "confidence",
        "timing",
        "created_at",
        "reference"
      ],
      "additionalProperties": false
    },
    "ScanId": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Scan identifier: a UUID version 7 (RFC 9562), canonical lower-case `8-4-4-4-12`. Its leading 48 bits are the millisecond the scan was made, so ids sort in the order the scans happened – but treat the value as opaque: nothing else about it is part of the contract.",
      "example": "01a0af18-cd8d-7a61-9f2d-4c7b8e105da3"
    },
    "ScanStatus": {
      "type": "string",
      "enum": [
        "recognized",
        "no_document_found",
        "unreadable",
        "unsupported_document",
        "rejected"
      ],
      "description": "Outcome of a scan. Exactly these five string values; there are no numeric codes."
    },
    "ConfidenceBand": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "description": "How strongly the recognition backs this value: `high`, `medium` or `low`. An unknown or missing probability reads as `low`."
    },
    "ScanTiming": {
      "type": "object",
      "properties": {
        "upload_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "From the request's headers reaching the server to its body being received and validated, with your key resolved and its rate limit checked. The allowance, idempotency and credit gates are claimed after this number is taken, so they are not in it. Dominated by your own connection and by how large the image is – this is the half you can shrink, by sending a smaller picture from closer by."
        },
        "processing_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "The recognition itself – the server-side engine call."
        },
        "total_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "From the request arriving to the result being complete. At least `upload_ms + processing_ms`; the remainder is the gates that run after `upload_ms` is taken – the allowance, the idempotency check and the credit hold – plus preparing the result images and mapping the engine's output into this body. It stops there: writing the history row and serializing the response happen after the number is fixed, so the same figure is stored and returned."
        }
      },
      "required": [
        "upload_ms",
        "processing_ms",
        "total_ms"
      ],
      "additionalProperties": false,
      "description": "The split of the request's time. Null on a scan made before the split existed and read back out of storage: only the engine call was timed then, and the two halves cannot be recovered from it."
    },
    "ScanDocument": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "minLength": 1,
          "description": "Document type, e.g. `passport`."
        },
        "country": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 3166-1 alpha-3 country code.",
              "example": "GRC"
            },
            {
              "type": "null"
            }
          ],
          "description": "The state that issued the document, ISO 3166-1 alpha-3. The same reading as `issuing_state` under the name most callers filter on; null when nothing was read."
        },
        "country_name": {
          "description": "The issuing state's name, as read from the document.",
          "example": "Greece",
          "type": [
            "string",
            "null"
          ]
        },
        "issuing_state": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 3166-1 alpha-3 country code.",
              "example": "GRC"
            },
            {
              "type": "null"
            }
          ],
          "description": "The issuing state, ISO 3166-1 alpha-3 – the same reading as `country`, under the name the machine-readable zone gives it."
        },
        "type_name": {
          "description": "The document type under its full name. Null on a scan read back from storage, which keeps no engine output.",
          "example": "Greece - Passport",
          "type": [
            "string",
            "null"
          ]
        },
        "type_confidence": {
          "description": "How strongly the document-type match is backed.",
          "allOf": [
            {
              "$ref": "#/definitions/ConfidenceBand"
            }
          ]
        },
        "number": {
          "description": "The document number, as printed. Null when none was read. A series the document prints separately is in `series`, never folded into this value.",
          "example": "AM7304518",
          "type": [
            "string",
            "null"
          ]
        },
        "series": {
          "description": "The document series, for a document that prints one as a field of its own. Null when the document carries none or none was read; it is never split out of `number`.",
          "type": [
            "string",
            "null"
          ]
        },
        "issue_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "description": "Calendar date, ISO-8601 (`YYYY-MM-DD`)."
            },
            {
              "type": "null"
            }
          ],
          "description": "The date the document was issued, ISO-8601 (`YYYY-MM-DD`). Null when none was read."
        },
        "expiry_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "description": "Calendar date, ISO-8601 (`YYYY-MM-DD`)."
            },
            {
              "type": "null"
            }
          ],
          "description": "The date the document expires, ISO-8601 (`YYYY-MM-DD`). Null when none was read; `is_expired` and `days_remaining` are computed from it."
        },
        "is_expired": {
          "description": "Whether the document had already expired when the scan was made. Null when no expiry date was read, which is a different answer from `false`.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "days_remaining": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "Days until expiry at the time of the scan; negative once expired."
        }
      },
      "required": [
        "kind",
        "country",
        "country_name",
        "issuing_state",
        "type_name",
        "type_confidence",
        "number",
        "series",
        "issue_date",
        "expiry_date",
        "is_expired",
        "days_remaining"
      ],
      "additionalProperties": false
    },
    "ScanHolder": {
      "type": "object",
      "properties": {
        "given_names": {
          "description": "The holder's given names, as printed. Null when none was read.",
          "type": [
            "string",
            "null"
          ]
        },
        "surname": {
          "description": "The holder's surname, as printed. Null when none was read.",
          "type": [
            "string",
            "null"
          ]
        },
        "full_name": {
          "description": "The holder's name as the document prints it in one combined field. Null when the document carries no such field – it is not composed from the two above.",
          "type": [
            "string",
            "null"
          ]
        },
        "birth_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "description": "Calendar date, ISO-8601 (`YYYY-MM-DD`)."
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's date of birth, ISO-8601 (`YYYY-MM-DD`). Null when none was read."
        },
        "sex": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "M",
                "F",
                "X"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "The sex the document states: `M`, `F`, or `X` for unspecified. Null when none was read."
        },
        "nationality": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 3166-1 alpha-3 country code.",
              "example": "GRC"
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's nationality, ISO 3166-1 alpha-3. Null when none was read; it is not assumed from the issuing state."
        }
      },
      "required": [
        "given_names",
        "surname",
        "full_name",
        "birth_date",
        "sex",
        "nationality"
      ],
      "additionalProperties": false
    },
    "ScanField": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Identity of this entry, unique across `fields`: the key and the language identifier the value was read as, plus an occurrence counter when the same pair is reported twice. `name` is the semantic key and repeats – a document that carries a field in two scripts yields one entry per language – so use `id`, not `name`, to address or key a single entry.",
          "example": "surname@1032"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Our stable snake_case key.",
          "example": "surname"
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "Our human label.",
          "example": "Surname"
        },
        "category": {
          "$ref": "#/definitions/FieldCategory"
        },
        "value": {
          "description": "The value of this reading: the national-script spelling on a national-script reading, the transliterated Latin value on the default reading (the one whose `id` carries the identifier `0`). Null when the field is empty.",
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "description": "The language this reading was made in, e.g. `Greek`. The default Latin-script reading – the document's own Latin page and the machine-readable zone, `id` suffix `@0` – is `English`. Null only on `days_to_expire`, a number computed from the expiry date rather than text read in any language.",
          "example": "Greek",
          "type": [
            "string",
            "null"
          ]
        },
        "confidence": {
          "$ref": "#/definitions/ConfidenceBand"
        }
      },
      "required": [
        "id",
        "name",
        "label",
        "category",
        "value",
        "language",
        "confidence"
      ],
      "additionalProperties": false
    },
    "FieldCategory": {
      "type": "string",
      "enum": [
        "identity",
        "document",
        "dates",
        "address",
        "visa",
        "other"
      ],
      "description": "Which group of the report a field belongs to."
    },
    "ScanMrz": {
      "type": "object",
      "properties": {
        "status": {
          "$ref": "#/definitions/MrzStatus"
        },
        "reason": {
          "description": "One plain sentence naming what did not check out, for `failed`; null otherwise.",
          "example": "Check digit failed for: document number, date of birth",
          "type": [
            "string",
            "null"
          ]
        },
        "lines": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "The zone's lines in order, exactly as read – two for a TD3 passport, three for a TD1 card. The zone's alphabet is `A-Z`, `0-9` and the filler `<`, so a line carries no whitespace. Null when the document carries none."
        },
        "text": {
          "description": "The same lines run together with nothing between them: one unbroken string, with no newlines and no spaces. Null when there are none.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "status",
        "reason",
        "lines",
        "text"
      ],
      "additionalProperties": false
    },
    "MrzStatus": {
      "type": "string",
      "enum": [
        "passed",
        "failed",
        "absent"
      ],
      "description": "Verdict on the machine-readable zone: `passed` (present, every check digit valid and nothing contradicting the printed page), `failed` (present but something did not check out) or `absent` (the document carries none)."
    },
    "ScanImages": {
      "type": "object",
      "properties": {
        "document_crop": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The document itself, cropped out of the uploaded picture and deskewed – the front side of a card, the data page of a booklet."
        },
        "rear": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The reverse side of the document, when the picture carried one and a crop of it was produced."
        },
        "main_photo": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's photograph as printed on the document."
        },
        "signature": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's signature as printed on the document."
        },
        "watermark_face": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The faint second copy of the holder's face printed into the page as a security feature – a different image from `main_photo`, and the one a verifier compares against it. Null when the document carries none."
        },
        "barcode": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The barcode area of the document, when it carries one."
        },
        "chip": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The chip area of the document, when it carries one."
        }
      },
      "required": [
        "document_crop",
        "rear",
        "main_photo",
        "signature",
        "watermark_face",
        "barcode",
        "chip"
      ],
      "additionalProperties": false,
      "description": "Image crops, returned in the recognition response only. Each is scaled down by height, proportionally and never upwards, to at most 250 px for `document_crop` and 100 px for every other crop, then re-encoded with every metadata block dropped."
    },
    "ScanQuality": {
      "type": "object",
      "properties": {
        "overall": {
          "type": "string",
          "enum": [
            "not_checked",
            "pass",
            "warn",
            "fail"
          ],
          "description": "Whether the uploaded picture was good enough to recognize from. `not_checked` when nothing measured it – a scan read back from storage, which keeps no engine output."
        }
      },
      "required": [
        "overall"
      ],
      "additionalProperties": false
    },
    "ScanAuthenticity": {
      "type": "object",
      "properties": {
        "overall": {
          "type": "string",
          "enum": [
            "not_checked",
            "pass",
            "warn",
            "fail"
          ],
          "description": "`not_checked` under the recognition-only scenario; populated by authenticity verification later."
        },
        "checks": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ScanCheck"
          },
          "description": "One entry per authenticity check that ran. Always present; empty under the recognition-only scenario, where nothing ran."
        }
      },
      "required": [
        "overall",
        "checks"
      ],
      "additionalProperties": false
    },
    "ScanCheck": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Our stable snake_case key for this check."
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "Our human label for this check."
        },
        "result": {
          "$ref": "#/definitions/CheckResult"
        },
        "detail": {
          "description": "One plain sentence about what this check saw, or null when it has nothing to add.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name",
        "label",
        "result",
        "detail"
      ],
      "additionalProperties": false
    },
    "CheckResult": {
      "type": "string",
      "enum": [
        "pass",
        "warn",
        "fail"
      ],
      "description": "Outcome of a single check."
    }
  }
}

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.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "balance_credits": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Credits currently available to the account: this month's free credits plus the paid credits; null for a key with no account (the public sandbox key)."
    },
    "period": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Bounds of the current usage period (UTC calendar month)."
    },
    "scans": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "billed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "by_status": {
          "type": "object",
          "properties": {
            "recognized": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "no_document_found": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "unreadable": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "unsupported_document": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "rejected": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            }
          },
          "required": [
            "recognized",
            "no_document_found",
            "unreadable",
            "unsupported_document",
            "rejected"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "total",
        "billed",
        "by_status"
      ],
      "additionalProperties": false
    },
    "credits_spent": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Credits charged within the period."
    },
    "free_allowance": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "monthly_credits": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "Free credits the account is set back to at the start of each UTC calendar month: 100 every month."
            },
            "remaining_credits": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "Free credits left this month."
            },
            "resets_at": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                },
                {
                  "type": "null"
                }
              ],
              "description": "When the free credits are next set back to the monthly amount (00:00 UTC on the first of the next month); null when there is no next monthly amount."
            }
          },
          "required": [
            "monthly_credits",
            "remaining_credits",
            "resets_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "This month's free credits, drawn before paid credits; null when the account may not draw free credits (its email address is not confirmed, or its free credits were withdrawn) and for a key with no account."
    },
    "paid_balance_credits": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "Paid credits: bought or granted to the account, drawn once this month's free credits are used up, and never reset; null only for a key with no account (the public sandbox key)."
    },
    "credits_spent_by_kind": {
      "type": "object",
      "properties": {
        "free": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "paid": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "free",
        "paid"
      ],
      "additionalProperties": false,
      "description": "Credits charged within the period, by the kind that paid."
    }
  },
  "required": [
    "balance_credits",
    "period",
    "scans",
    "credits_spent",
    "free_allowance",
    "paid_balance_credits",
    "credits_spent_by_kind"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "What to search the documentation for."
    },
    "limit": {
      "description": "Maximum number of results (default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Heading of the matching documentation section."
          },
          "page": {
            "type": "string",
            "description": "Path of the page the section is on; empty for the home page."
          },
          "link": {
            "type": "string",
            "description": "Address of the section on the documentation site."
          },
          "snippet": {
            "type": "string",
            "description": "The start of the section's text."
          },
          "score": {
            "type": "number",
            "description": "Relevance: heading matches count five times a body match."
          }
        },
        "required": [
          "title",
          "page",
          "link",
          "snippet",
          "score"
        ],
        "additionalProperties": false
      },
      "description": "Matching sections, best first; empty when nothing matched."
    }
  },
  "required": [
    "results"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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, 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 – the public one or an account's own sk_sandbox_ key – nothing is stored. 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.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Rows per page, 1 to 100 (default 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "next_cursor from the previous page; omit it for the first page.",
      "type": "string",
      "minLength": 1
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "scans": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ScanSummary"
      },
      "description": "The account's scans, most recent first."
    },
    "next_cursor": {
      "description": "Opaque cursor for the next page: send it back as `cursor` to continue after the last row of this one. Null on the last page.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "scans",
    "next_cursor"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "definitions": {
    "ScanSummary": {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/definitions/ScanId"
        },
        "status": {
          "$ref": "#/definitions/ScanStatus"
        },
        "billed": {
          "type": "boolean",
          "description": "Whether this scan was charged to the balance."
        },
        "duration_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "Server-side processing time of the scan in milliseconds."
        },
        "reference": {
          "description": "The request's `reference`, echoed back.",
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
          "description": "Timestamp, ISO-8601 in UTC (`YYYY-MM-DDTHH:MM:SSZ`)."
        }
      },
      "required": [
        "id",
        "status",
        "billed",
        "duration_ms",
        "reference",
        "created_at"
      ],
      "additionalProperties": false
    },
    "ScanId": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Scan identifier: a UUID version 7 (RFC 9562), canonical lower-case `8-4-4-4-12`. Its leading 48 bits are the millisecond the scan was made, so ids sort in the order the scans happened – but treat the value as opaque: nothing else about it is part of the contract.",
      "example": "01a0af18-cd8d-7a61-9f2d-4c7b8e105da3"
    },
    "ScanStatus": {
      "type": "string",
      "enum": [
        "recognized",
        "no_document_found",
        "unreadable",
        "unsupported_document",
        "rejected"
      ],
      "description": "Outcome of a scan. Exactly these five string values; there are no numeric codes."
    }
  }
}

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, 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 – the public one or an account's own sk_sandbox_ key – nothing is stored. 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.

{
  "type": "object",
  "properties": {
    "scan_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "The scan's id: meta.id of the scan_document result, or id of a list_scans row (a lower-case UUID)."
    }
  },
  "required": [
    "scan_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "meta": {
      "$ref": "#/definitions/ScanMeta"
    },
    "document": {
      "anyOf": [
        {
          "$ref": "#/definitions/ScanDocument"
        },
        {
          "type": "null"
        }
      ]
    },
    "holder": {
      "anyOf": [
        {
          "$ref": "#/definitions/ScanHolder"
        },
        {
          "type": "null"
        }
      ]
    },
    "fields": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ScanField"
      },
      "description": "Every field the engine extracted off the printed document, re-keyed to our vocabulary – the open set. Always present; empty when nothing was extracted. A field read in more than one language appears once per language, so `name` repeats and only `id` is unique."
    },
    "mrz": {
      "$ref": "#/definitions/ScanMrz"
    },
    "images": {
      "$ref": "#/definitions/ScanImages"
    },
    "quality": {
      "$ref": "#/definitions/ScanQuality"
    },
    "authenticity": {
      "$ref": "#/definitions/ScanAuthenticity"
    }
  },
  "required": [
    "meta",
    "document",
    "holder",
    "fields",
    "mrz",
    "images",
    "quality",
    "authenticity"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "definitions": {
    "ScanMeta": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "const": "1.0",
          "description": "The version of this body, always `1.0`. A consumer that pins this value checks that the body is the one it was written against."
        },
        "id": {
          "$ref": "#/definitions/ScanId"
        },
        "status": {
          "$ref": "#/definitions/ScanStatus"
        },
        "billed": {
          "type": "boolean",
          "description": "Whether this scan was charged to the balance."
        },
        "confidence": {
          "description": "How strongly the recognition backs this reading as a whole. Each entry of `fields` carries its own band as well, and they can differ from this one.",
          "allOf": [
            {
              "$ref": "#/definitions/ConfidenceBand"
            }
          ]
        },
        "timing": {
          "anyOf": [
            {
              "$ref": "#/definitions/ScanTiming"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
          "description": "Timestamp, ISO-8601 in UTC (`YYYY-MM-DDTHH:MM:SSZ`)."
        },
        "reference": {
          "description": "The request's `reference`, echoed back.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "schema_version",
        "id",
        "status",
        "billed",
        "confidence",
        "timing",
        "created_at",
        "reference"
      ],
      "additionalProperties": false
    },
    "ScanId": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Scan identifier: a UUID version 7 (RFC 9562), canonical lower-case `8-4-4-4-12`. Its leading 48 bits are the millisecond the scan was made, so ids sort in the order the scans happened – but treat the value as opaque: nothing else about it is part of the contract.",
      "example": "01a0af18-cd8d-7a61-9f2d-4c7b8e105da3"
    },
    "ScanStatus": {
      "type": "string",
      "enum": [
        "recognized",
        "no_document_found",
        "unreadable",
        "unsupported_document",
        "rejected"
      ],
      "description": "Outcome of a scan. Exactly these five string values; there are no numeric codes."
    },
    "ConfidenceBand": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "description": "How strongly the recognition backs this value: `high`, `medium` or `low`. An unknown or missing probability reads as `low`."
    },
    "ScanTiming": {
      "type": "object",
      "properties": {
        "upload_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "From the request's headers reaching the server to its body being received and validated, with your key resolved and its rate limit checked. The allowance, idempotency and credit gates are claimed after this number is taken, so they are not in it. Dominated by your own connection and by how large the image is – this is the half you can shrink, by sending a smaller picture from closer by."
        },
        "processing_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "The recognition itself – the server-side engine call."
        },
        "total_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "From the request arriving to the result being complete. At least `upload_ms + processing_ms`; the remainder is the gates that run after `upload_ms` is taken – the allowance, the idempotency check and the credit hold – plus preparing the result images and mapping the engine's output into this body. It stops there: writing the history row and serializing the response happen after the number is fixed, so the same figure is stored and returned."
        }
      },
      "required": [
        "upload_ms",
        "processing_ms",
        "total_ms"
      ],
      "additionalProperties": false,
      "description": "The split of the request's time. Null on a scan made before the split existed and read back out of storage: only the engine call was timed then, and the two halves cannot be recovered from it."
    },
    "ScanDocument": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "minLength": 1,
          "description": "Document type, e.g. `passport`."
        },
        "country": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 3166-1 alpha-3 country code.",
              "example": "GRC"
            },
            {
              "type": "null"
            }
          ],
          "description": "The state that issued the document, ISO 3166-1 alpha-3. The same reading as `issuing_state` under the name most callers filter on; null when nothing was read."
        },
        "country_name": {
          "description": "The issuing state's name, as read from the document.",
          "example": "Greece",
          "type": [
            "string",
            "null"
          ]
        },
        "issuing_state": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 3166-1 alpha-3 country code.",
              "example": "GRC"
            },
            {
              "type": "null"
            }
          ],
          "description": "The issuing state, ISO 3166-1 alpha-3 – the same reading as `country`, under the name the machine-readable zone gives it."
        },
        "type_name": {
          "description": "The document type under its full name. Null on a scan read back from storage, which keeps no engine output.",
          "example": "Greece - Passport",
          "type": [
            "string",
            "null"
          ]
        },
        "type_confidence": {
          "description": "How strongly the document-type match is backed.",
          "allOf": [
            {
              "$ref": "#/definitions/ConfidenceBand"
            }
          ]
        },
        "number": {
          "description": "The document number, as printed. Null when none was read. A series the document prints separately is in `series`, never folded into this value.",
          "example": "AM7304518",
          "type": [
            "string",
            "null"
          ]
        },
        "series": {
          "description": "The document series, for a document that prints one as a field of its own. Null when the document carries none or none was read; it is never split out of `number`.",
          "type": [
            "string",
            "null"
          ]
        },
        "issue_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "description": "Calendar date, ISO-8601 (`YYYY-MM-DD`)."
            },
            {
              "type": "null"
            }
          ],
          "description": "The date the document was issued, ISO-8601 (`YYYY-MM-DD`). Null when none was read."
        },
        "expiry_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "description": "Calendar date, ISO-8601 (`YYYY-MM-DD`)."
            },
            {
              "type": "null"
            }
          ],
          "description": "The date the document expires, ISO-8601 (`YYYY-MM-DD`). Null when none was read; `is_expired` and `days_remaining` are computed from it."
        },
        "is_expired": {
          "description": "Whether the document had already expired when the scan was made. Null when no expiry date was read, which is a different answer from `false`.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "days_remaining": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "Days until expiry at the time of the scan; negative once expired."
        }
      },
      "required": [
        "kind",
        "country",
        "country_name",
        "issuing_state",
        "type_name",
        "type_confidence",
        "number",
        "series",
        "issue_date",
        "expiry_date",
        "is_expired",
        "days_remaining"
      ],
      "additionalProperties": false
    },
    "ScanHolder": {
      "type": "object",
      "properties": {
        "given_names": {
          "description": "The holder's given names, as printed. Null when none was read.",
          "type": [
            "string",
            "null"
          ]
        },
        "surname": {
          "description": "The holder's surname, as printed. Null when none was read.",
          "type": [
            "string",
            "null"
          ]
        },
        "full_name": {
          "description": "The holder's name as the document prints it in one combined field. Null when the document carries no such field – it is not composed from the two above.",
          "type": [
            "string",
            "null"
          ]
        },
        "birth_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "description": "Calendar date, ISO-8601 (`YYYY-MM-DD`)."
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's date of birth, ISO-8601 (`YYYY-MM-DD`). Null when none was read."
        },
        "sex": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "M",
                "F",
                "X"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "The sex the document states: `M`, `F`, or `X` for unspecified. Null when none was read."
        },
        "nationality": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 3166-1 alpha-3 country code.",
              "example": "GRC"
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's nationality, ISO 3166-1 alpha-3. Null when none was read; it is not assumed from the issuing state."
        }
      },
      "required": [
        "given_names",
        "surname",
        "full_name",
        "birth_date",
        "sex",
        "nationality"
      ],
      "additionalProperties": false
    },
    "ScanField": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Identity of this entry, unique across `fields`: the key and the language identifier the value was read as, plus an occurrence counter when the same pair is reported twice. `name` is the semantic key and repeats – a document that carries a field in two scripts yields one entry per language – so use `id`, not `name`, to address or key a single entry.",
          "example": "surname@1032"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Our stable snake_case key.",
          "example": "surname"
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "Our human label.",
          "example": "Surname"
        },
        "category": {
          "$ref": "#/definitions/FieldCategory"
        },
        "value": {
          "description": "The value of this reading: the national-script spelling on a national-script reading, the transliterated Latin value on the default reading (the one whose `id` carries the identifier `0`). Null when the field is empty.",
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "description": "The language this reading was made in, e.g. `Greek`. The default Latin-script reading – the document's own Latin page and the machine-readable zone, `id` suffix `@0` – is `English`. Null only on `days_to_expire`, a number computed from the expiry date rather than text read in any language.",
          "example": "Greek",
          "type": [
            "string",
            "null"
          ]
        },
        "confidence": {
          "$ref": "#/definitions/ConfidenceBand"
        }
      },
      "required": [
        "id",
        "name",
        "label",
        "category",
        "value",
        "language",
        "confidence"
      ],
      "additionalProperties": false
    },
    "FieldCategory": {
      "type": "string",
      "enum": [
        "identity",
        "document",
        "dates",
        "address",
        "visa",
        "other"
      ],
      "description": "Which group of the report a field belongs to."
    },
    "ScanMrz": {
      "type": "object",
      "properties": {
        "status": {
          "$ref": "#/definitions/MrzStatus"
        },
        "reason": {
          "description": "One plain sentence naming what did not check out, for `failed`; null otherwise.",
          "example": "Check digit failed for: document number, date of birth",
          "type": [
            "string",
            "null"
          ]
        },
        "lines": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "The zone's lines in order, exactly as read – two for a TD3 passport, three for a TD1 card. The zone's alphabet is `A-Z`, `0-9` and the filler `<`, so a line carries no whitespace. Null when the document carries none."
        },
        "text": {
          "description": "The same lines run together with nothing between them: one unbroken string, with no newlines and no spaces. Null when there are none.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "status",
        "reason",
        "lines",
        "text"
      ],
      "additionalProperties": false
    },
    "MrzStatus": {
      "type": "string",
      "enum": [
        "passed",
        "failed",
        "absent"
      ],
      "description": "Verdict on the machine-readable zone: `passed` (present, every check digit valid and nothing contradicting the printed page), `failed` (present but something did not check out) or `absent` (the document carries none)."
    },
    "ScanImages": {
      "type": "object",
      "properties": {
        "document_crop": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The document itself, cropped out of the uploaded picture and deskewed – the front side of a card, the data page of a booklet."
        },
        "rear": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The reverse side of the document, when the picture carried one and a crop of it was produced."
        },
        "main_photo": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's photograph as printed on the document."
        },
        "signature": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The holder's signature as printed on the document."
        },
        "watermark_face": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The faint second copy of the holder's face printed into the page as a security feature – a different image from `main_photo`, and the one a verifier compares against it. Null when the document carries none."
        },
        "barcode": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The barcode area of the document, when it carries one."
        },
        "chip": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^data:image\\/(jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$",
              "description": "Image as a `data:` URL with base64 payload."
            },
            {
              "type": "null"
            }
          ],
          "description": "The chip area of the document, when it carries one."
        }
      },
      "required": [
        "document_crop",
        "rear",
        "main_photo",
        "signature",
        "watermark_face",
        "barcode",
        "chip"
      ],
      "additionalProperties": false,
      "description": "Image crops, returned in the recognition response only. Each is scaled down by height, proportionally and never upwards, to at most 250 px for `document_crop` and 100 px for every other crop, then re-encoded with every metadata block dropped."
    },
    "ScanQuality": {
      "type": "object",
      "properties": {
        "overall": {
          "type": "string",
          "enum": [
            "not_checked",
            "pass",
            "warn",
            "fail"
          ],
          "description": "Whether the uploaded picture was good enough to recognize from. `not_checked` when nothing measured it – a scan read back from storage, which keeps no engine output."
        }
      },
      "required": [
        "overall"
      ],
      "additionalProperties": false
    },
    "ScanAuthenticity": {
      "type": "object",
      "properties": {
        "overall": {
          "type": "string",
          "enum": [
            "not_checked",
            "pass",
            "warn",
            "fail"
          ],
          "description": "`not_checked` under the recognition-only scenario; populated by authenticity verification later."
        },
        "checks": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ScanCheck"
          },
          "description": "One entry per authenticity check that ran. Always present; empty under the recognition-only scenario, where nothing ran."
        }
      },
      "required": [
        "overall",
        "checks"
      ],
      "additionalProperties": false
    },
    "ScanCheck": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Our stable snake_case key for this check."
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "Our human label for this check."
        },
        "result": {
          "$ref": "#/definitions/CheckResult"
        },
        "detail": {
          "description": "One plain sentence about what this check saw, or null when it has nothing to add.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name",
        "label",
        "result",
        "detail"
      ],
      "additionalProperties": false
    },
    "CheckResult": {
      "type": "string",
      "enum": [
        "pass",
        "warn",
        "fail"
      ],
      "description": "Outcome of a single check."
    }
  }
}

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, 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 – the public one or an account's own sk_sandbox_ key – nothing is stored. 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.

{
  "type": "object",
  "properties": {
    "scan_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "The scan's id: meta.id of the scan_document result, or id of a list_scans row (a lower-case UUID)."
    }
  },
  "required": [
    "scan_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/definitions/ScanId"
    },
    "deleted": {
      "type": "boolean",
      "const": true,
      "description": "Always true: the stored result is gone and cannot be read back."
    }
  },
  "required": [
    "id",
    "deleted"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "definitions": {
    "ScanId": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Scan identifier: a UUID version 7 (RFC 9562), canonical lower-case `8-4-4-4-12`. Its leading 48 bits are the millisecond the scan was made, so ids sort in the order the scans happened – but treat the value as opaque: nothing else about it is part of the contract.",
      "example": "01a0af18-cd8d-7a61-9f2d-4c7b8e105da3"
    }
  }
}