Scan options¶

POST /v1/scans carries an optional options object beside the image. Five options exist, and every one of them has a default. A request that sends no options at all is a valid request.

{
  "image": "<base64>",
  "reference": "order-1042",
  "options": {
    "mode": "full",
    "expect_country": null,
    "date_format": "iso",
    "return_portrait": true,
    "retain_hours": 0
  }
}

The five options¶

options is a strict object. A key that is not one of these five is refused with validation_failed and a 422, and the message names the offending path. A misspelled option is never ignored.

mode¶

Selects the recognition mode. "full" is the only value the contract declares, and it is the default.

expect_country¶

The country the caller expects the document to have been issued by, as an ISO 3166-1 alpha-3 code such as GRC. It is a hint carried into recognition, not an assertion. A document from another country is still recognized, and document.country reports what was read rather than what was expected.

null, the default, expects nothing.

date_format¶

The format of every date in the response. "iso" is the only value the contract declares. Dates are YYYY-MM-DD and timestamps are YYYY-MM-DDTHH:MM:SSZ, in UTC.

return_portrait¶

Whether the holder's photograph is returned with the result. With false the crop is absent from the response and images.main_photo is null.

The setting does not change what is stored, because no crop is ever stored. It changes what one response carries.

retain_hours¶

How many hours the result stays readable through GET /v1/scans/{id}. The range is 0 to 8760, one year.

0 is not a short window. It writes no row at all, rather than a row that expires at once. Nothing exists in the interval that a read could find.

An explicit value always wins over the account's setting, 0 included. The setting applies only when the request names no value. An upload made from the dashboard is the case that names none.

The dashboard offers four windows for that setting: 24 hours, 7 days, 1 month and 1 year. A new account carries 1 year. The API accepts any integer in the range, so a value the dashboard does not offer is still a valid retain_hours.

reference is not an option¶

reference is a sibling of options, not a member of it. It is the caller's own correlation string, at most 128 characters, echoed back unchanged on the result and on every history row. Its default is null.

{ "image": "<base64>", "reference": "order-1042", "options": { "retain_hours": 0 } }

Putting reference inside options is refused with validation_failed, because options rejects a key it does not declare.

What an invalid value answers¶

Every refusal below is a 422 carrying validation_failed, with the offending path in the message. Nothing reaches the recognition engine, and nothing is charged.

Which options interact¶

Nothing an option sets changes what a scan costs. Billing is decided by the outcome alone, which is what a billed scan is.