ID Recognition API

The ID Recognition API (PR) reads identity documents from images and supported SDK input files. API version 2.0 adds grouped results and explicit scan modes. The reference below uses the Swagger 2.0 specification format; that is separate from the API response version. Availability depends on the deployed service and engine; check /pr22/capabilities on your endpoint before relying on an optional feature. SDK comparisons and automatic batch idle close are available only in deployments containing those changes.

Versions and scan modes​

The Cloud PR API preserves the 1.0-compatible default. To use the structured contract, send X-Api-Version: 2.0 and an explicit X-Scan-Mode. The standalone Carmen Worker defaults to 2.0; send the version explicitly for portable clients. Existing 1.0 consumers can continue using their existing response contract. On Cloud, omitting scan mode retains the legacy scan path. On Worker, the default response version remains 2.0. In either case, do not infer an explicit single-document response.

X-Scan-ModeUseResult
single-pageOne External image, no existing transaction, file input, cleanup or later pagesOne document, optionally person; completes in one request
single-documentMultiple pages or SDK files for one physical documentOne document, optionally person; close with PATCH
batchMultiple documents and people in one transactionvalues groups people or document groups and their documents; close with PATCH or idle close

Set the same mode, region, and X-Include-Field-Images option for every request in a transaction. On the cloud service, explicitly send X-Api-Version: 2.0 throughout. X-Enable-Low-Level-Fields is not supported by the explicit Cloud 2.0 scan path; use the grouped sources and observations instead.

Read and close a document​

Use the region endpoint when the document's region is known; /pr22/ also supports requests without a region hint. The first page is X-Page: 0; save the returned X-Transaction-Id and send the next page with X-Page: 1. Each new operation should have its own Idempotency-Key (8–128 characters: letters, digits, ., _, :, or -). Reuse the same key and identical request when retrying the same operation. Reusing a key with different input returns a conflict. A request without a key gets a generated key and cannot be safely retried by supplying that unknown key.

curl -X POST 'https://api.carmencloud.com/pr22/eur' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'X-Api-Version: 2.0' \
-H 'X-Scan-Mode: single-document' \
-H 'X-Page: 0' \
-H 'Idempotency-Key: example-document-page-0' \
-F 'image=@page-front.jpg;filename=External'

For later pages, add the returned X-Transaction-Id, increment X-Page, and use a new key. To replace the most recently committed page, send that same page number with X-Clean-Up-Last-Page: true and a new key. An out-of-order page is rejected. Handle an in-progress conflict by retrying the same operation with its original key; do not start a second operation until the first has resolved.

Close an open single-document or batch scan with PATCH /pr22/ and its X-Transaction-Id. On Cloud, include X-Api-Version: 2.0; include the original scan mode and image option when sending them. A closed scan cannot accept another page. single-page finishes automatically and cannot be continued.

For supported explicit batch deployments, an idle batch closes after 15 minutes from the last successfully committed or replaced page. A replay, validation failure, or failed processing does not reset the deadline. Older sessions without the idle metadata are not retroactively assigned a deadline. Manual close remains available. Idle close is asynchronous and may be observed after the deadline; a closed scan requires a new transaction.

Read the result​

In explicit single modes, document contains the document fields, sources, parts and per-field observations; person is optional and contains personal fields when a person can be identified. In batch mode, values contains grouped persons and document groups, each with documents. A document group is not necessarily a person. fields are selected values, fieldObservations retain source-level values where provided, and conflicts record disagreements. Batch per-field observations are projected when field images are requested. fieldComparisonValues may contain SDK-normalized text values; it is not a biometric score.

Sources can include Viz, Mrz, Barcode, ECard, or Preferred. Preferred is the SDK-selected value, not a separate physical source. Preserve unknown source and field codes. The optional sdkComparisons belongs to the specific document: document.sdkComparisons for explicit single modes and values[].documents[].sdkComparisons for batch. Older deployments may omit it. An unavailable or empty comparison is not a mismatch. When present, its optional items carry the SDK's raw integer confidence and its reported 0–1000 scale; it is not a percentage or a general identity verdict. Do not equate sdkPage with partIndex or X-Page. A truncated list is incomplete.

Example shape with fictional data (actual fields and available sources depend on the engine):

{
"version": "2.0",
"scanMode": "single-document",
"resultKind": "document",
"isFinal": false,
"person": {"id": "person-example", "kind": "person", "fields": {"Givenname": "EXAMPLE"}},
"document": {
"id": "document-example",
"fields": {"DocumentNumber": "X1234567"},
"sources": [{"partIndex": 0, "fieldSource": "Mrz", "fieldIndex": 0}],
"parts": [{"partIndex": 0, "fields": {"DocumentNumber": "X1234567"}, "sources": [{"partIndex": 0, "fieldSource": "Mrz", "fieldIndex": 0}]}],
"fieldObservations": [{"id": "observation-example", "fieldType": "DocumentNumber", "value": "X1234567", "chosen": true, "source": {"partIndex": 0, "fieldSource": "Mrz", "fieldIndex": 0}}],
"sdkComparisons": {"status": "unavailable", "items": []}
}
}

Field images and artifacts​

Field images are opt-in: send X-Include-Field-Images: true from the first request and keep it unchanged. The response may contain an inline base64 image or a private ZIP and manifest reference; availability and size limits apply. Portrait and signature crops are distinct from field images. Large responses may be compacted and point to a result JSON artifact; read that artifact for the full result. Use the returned signed download URL and, when it expires while retention is still valid, the authenticated GET /pr22/artifacts/{transactionId}/{sha256}/{name} route, using the transaction ID and the artifact reference’s sha256 and name, to obtain a new URL. An expired or deleted scan/artifact cannot be recovered by refreshing a URL.

Batch finality belongs to the close response and final event envelope. Earlier uploaded JSON or ZIP artifacts are immutable and are not rewritten at close; their own isFinal value may describe an earlier state. For Cloud Storage & Hooks, batch result events are emitted on final close, not for each intermediate page. Standalone Worker AMQP can also emit intermediate events; filter on isFinal for the final event. For standalone storage, private prefixes, expiry and optional RabbitMQ delivery, see Carmen Worker configuration.

Add NFC SDK files​

To add supported chip data to an open optical scan, use single-document or batch and POST repeated multipart parts named file in the same transaction. Each part's filename is the SDK file comment, not a display label; it is passed to the native engine. Use unique names and preserve the original SDK-exported binary bytes. A file-only request is supported; no dummy image is required. Do not rely on multipart order. For the tested SDK convention, examples include ffff:1000 for GeneralData and ffff:31 for SOD; use the actual SDK export and compatible engine for your document.

curl -X POST 'https://api.carmencloud.com/pr22/eur' \
-H 'x-api-key: YOUR_API_KEY' -H 'X-Api-Version: 2.0' \
-H 'X-Scan-Mode: single-document' -H 'X-Transaction-Id: TRANSACTION_ID' \
-H 'X-Page: 1' -H 'Idempotency-Key: example-document-chip-1' \
-F 'file=@general-data.bin;filename=ffff:1000;type=application/octet-stream' \
-F 'file=@sod.bin;filename=ffff:31;type=application/octet-stream'

A decoded JSON representation is not a substitute for the original SDK-compatible file bytes. File acceptance or an SDK comparison does not assert SOD signature validation, issuer trust, liveness, or a biometric verdict. A previously closed single-page result cannot be reopened to append files.

Loading API reference…