API documentation

Read documents from your code.

One endpoint takes the images of an identity document and returns its text fields, extracted images, verification checks and an optional face match — as clear, flat JSON.

Introduction

The readout API is a REST API. Requests are sent over HTTPS as multipart/form-data or JSON, and every response is JSON.

BASE URLhttps://readout.g4t.io/api
  • Every request needs an API key. See Authentication.
  • Missing values are returned as null; the keys of a response never change.
  • Dates are returned as YYYY-MM-DD, exactly as read from the document.

Quick start

  1. Create an account, or log in.
  2. Open API keys and create a key. It is shown once, so copy it.
  3. Send a document image with the key in the X-API-Key header:
cURL
curl -X POST 'https://readout.g4t.io/api/document/process' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'images[]=@passport.jpg'

No document at hand? Send sample=PASSPORT instead of a file, or try the live demo.

Authentication

Send your API key with every request, in either of these headers:

Headers
X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY
  • Keys start with rdo_ and are created in the dashboard.
  • A key is shown once. Only its hash is stored, so a lost key cannot be recovered — create a new one.
  • Revoking a key takes effect immediately: the next request with it gets 401.
  • Use one key per application, so you can revoke one without touching the others.
Keep it secretCall the API from your server. A key placed in a web page or mobile app can be copied by anyone.

Process a document

POST/api/document/process

Reads one document. Send its page images, or an image URL, or the name of a built-in sample.

Parameters

NameTypeDescription
images[]required*file[]1 to 4 files, one per page (front, back, …). JPG, PNG, WEBP, BMP, TIFF, JP2 or PDF, up to 15 MB each.
image_urlrequired*stringAn http or https URL of the document image, instead of images[]. It must be reachable from the internet.
samplerequired*stringName of a built-in sample, instead of your own document. See List samples.
scenariooptionalstringWhat to read. Defaults to FullProcess. See List scenarios.
portraitoptionalfileA selfie or other portrait (JPG, PNG, WEBP, up to 15 MB) to compare with the portrait on the document. See Face match.
include_imagesoptionalbooleanSend 0 to leave the base64 images out of the response. Defaults to 1.

* Send exactly one source: images[], image_url or sample. images[] and image_url cannot be combined.

Request

curl -X POST 'https://readout.g4t.io/api/document/process' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'images[]=@id-front.jpg' \
  -F 'images[]=@id-back.jpg' \
  -F 'portrait=@selfie.jpg' \
  -F 'scenario=FullProcess'

Response 200 OK

JSON
{
  "transaction_id": "a5b16374-35eb-4700-bba9-6d285c581b1c",
  "finished": true,
  "elapsed_ms": 394,
  "scenario": "FullProcess",
  "sample": null,
  "status": {
    "overall": 1,     "overall_text": "passed",
    "optical": 1,     "optical_text": "passed",
    "portrait": 1,    "portrait_text": "passed",
    "rfid": 2,        "rfid_text": "not_performed",
    "stop_list": 2,   "stop_list_text": "not_performed",
    "age": 2,         "age_text": "not_performed"
  },
  "face_match": { "status": 1, "status_text": "passed", "similarity": 99 },
  "document": {
    "name": "Utopia - ePassport (2022)",
    "type": "Passport",
    "country": "Utopia",
    "country_code": "UTO",
    "number": "X0000000",
    "date_of_issue": "2022-04-16",
    "date_of_expiry": "2032-04-15",
    "authority": "MINISTRY OF INTERIOR"
  },
  "holder": {
    "full_name": "SPECIMEN SAMPLE",
    "surname": "SPECIMEN",
    "given_names": "SAMPLE",
    "sex": "F",
    "date_of_birth": "1974-08-12",
    "age": "52",
    "nationality": "UTOPIAN",
    "nationality_code": "UTO",
    "place_of_birth": "ZENITH"
  },
  "fields": [
    { "key": "surname", "name": "Surname", "value": "SPECIMEN", "lcid": 0, "status": 1, "status_text": "passed" },
    { "key": "document_number", "name": "Document Number", "value": "X0000000", "lcid": 0, "status": 1, "status_text": "passed" }
  ],
  "images": [
    { "key": "portrait", "name": "Portrait", "mime_type": "image/jpeg", "base64": "/9j/4AAQSkZJRg..." },
    { "key": "document_front_side", "name": "Document front side", "mime_type": "image/jpeg", "base64": "/9j/4AAQSkZJRg..." }
  ]
}

List scenarios

GET/api/document/scenario

Returns every scenario you can pass as scenario. A scenario decides what is read from the document; FullProcess reads everything.

Response · 200 OK
{
  "data": [
    { "value": "Mrz", "description": "Obtains MRZ data.", "is_default": false },
    { "value": "FullProcess", "description": "Obtains all document data: text fields, images and checks.", "is_default": true }
  ]
}

Available scenarios

ValueWhat it does
MrzObtains MRZ data.
BarcodeObtains barcode data.
LocateDetects document boundaries.
OcrObtains visual zone OCR results.
DocTypeRecognises the document type.
MrzOrBarcodeObtains MRZ and/or barcode data.
MrzOrLocateDetects document boundaries and/or obtains MRZ data.
MrzAndLocateDetects document boundaries and obtains MRZ data.
BarcodeAndLocateDetects document boundaries and obtains barcode data.
MrzOrOcrObtains MRZ data or visual zone OCR results.
MrzOrBarcodeOrOcrObtains MRZ, barcode or visual zone OCR results.
LocateVisual_And_MrzOrOcrDetects document boundaries and obtains MRZ data or visual zone OCR results.
FullProcessdefaultObtains all document data: text fields, images and checks.
FullAuthObtains all document data and authenticates the document.
RusStampObtains data from registration stamps.
OcrFreeObtains OCR results of any image.
CreditCardObtains bank card data.
CaptureReturns the original image without any processing.
DTCProcesses Digital Travel Credentials (DTC-VC) data.
RFIDProcesses RFID chip data.
mDLProcesses mobile driving licence (mDL) data.

Which scenarios actually run depends on the licence of the document service behind your installation. A scenario that is not licensed is answered with 502.

List samples

GET/api/document/sample

Returns the built-in sample documents. Pass a sample's value as sample to process it without uploading anything — useful for testing your integration.

Response · 200 OK
{
  "data": [
    {
      "value": "PASSPORT",
      "title": "Passport",
      "description": "One cropped page.",
      "preview_url": "https://readout.g4t.io/demo/sample/PASSPORT/preview"
    }
  ]
}

Available samples

ValueTitleWhat is sent
PASSPORTPassportOne cropped page.
RESIDENCE_PERMITResidence PermitOne cropped page.
ID_CARDID Card, incl. RFID dataFront and back, RFID chip session, face match.
DRIVING_LICENSEDriving LicenseOne page plus an external portrait for face match.
ONE_SHOTOne-Shot IdentificationUncropped photo of a person holding the document.
cURL
curl -X POST 'https://readout.g4t.io/api/document/process' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"sample": "ID_CARD", "include_images": false}'

Reading the response

KeyTypeDescription
transaction_idstring · nullIdentifier of this processing run. Keep it if you need to ask about a specific request.
finishedbooleantrue when the document was processed completely.
elapsed_msinteger · nullTime the reading itself took, in milliseconds.
scenariostringThe scenario that was used.
samplestring · nullThe sample that was processed, or null for your own document.
statusobjectThe overall verdict and each group of checks. See the values below.
face_matchobject · nullnull unless a portrait was compared. See Face match.
documentobjectWhat kind of document it is, its number and dates.
holderobjectThe person the document belongs to.
fieldsarrayEvery text field that was read, in the order the service returned them.
imagesarrayExtracted images as base64. Absent when include_images=0.

Check values

Every status is returned twice: as a number, and as text under the same key with _text added.

NumberTextMeaning
1passedThe check ran and passed.
0failedThe check ran and failed.
2not_performedThe check did not run, for example RFID without chip data.
nullnullThe service reported nothing for this check.

Status groups

KeyWhat it covers
overallThe combined verdict of everything below.
opticalChecks on the images: document type, text validity, expiry, image quality, security features.
portraitComparison of portraits. Needs a portrait in the request, or a sample that includes one.
rfidChecks on chip data. Only samples carry chip data.
stop_listWhether the document is on a stop list, when the service has one configured.
ageAge checks on the holder.
Specimens failSample and specimen documents normally return overall: 0, because they are marked as specimens. That is expected.

Fields

Each entry of fields has a stable key (the field name in snake_case), the original name, the value, the language id lcid (0 for Latin) and its own status. A field can appear more than once when the document prints it in several scripts; pick the entry with the lcid you need.

document and holder are shortcuts to the most used fields, so you rarely need to search fields yourself.

Images

Each entry of images has a key such as portrait, signature or document_front_side, and the image as base64 with its mime_type. Responses with images are large (hundreds of kilobytes); send include_images=0 when you only need the data.

Face match

Send a portrait — a selfie or any photo of the person — together with the document, and the API compares it with the portrait printed on the document.

cURL
curl -X POST 'https://readout.g4t.io/api/document/process' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'images[]=@id-front.jpg' \
  -F 'portrait=@selfie.jpg' \
  -F 'include_images=0'
In the response
"face_match": { "status": 1, "status_text": "passed", "similarity": 99 }
KeyTypeDescription
statusinteger · null1 the same person, 0 not a match. Uses the check values.
status_textstring · nullpassed, failed or not_performed.
similarityinteger · nullHow alike the two faces are, from 0 to 100.
  • face_match is null when no portrait was sent, or when no face could be compared.
  • The same result is summarised in status.portrait.
  • Use a clear, front-facing photo with one face in it.

Files and limits

LimitValue
Document files per request1 to 4, one page per file
Document formatsJPG, PNG, WEBP, BMP, TIFF, JP2, PDF
Portrait formatsJPG, PNG, WEBP
Size per file15 MB
Image URLhttp or https, up to 2048 characters

Getting good results

  • Send the pages in order: front first, then back.
  • The whole document must be inside the picture, flat, sharp and without glare.
  • Leave a little background around the document; do not crop into its edges.
  • Never test with a real person's document. Use the samples.

Errors

Errors use standard HTTP status codes and always carry a message.

StatusWhenWhat to do
401The key is missing, wrong or revoked.Check the header and the key in the dashboard.
422The request is invalid: no source, bad file type, unknown scenario or sample.Read errors and fix the named fields.
429Too many requests. See Rate limits.Wait for the seconds given in Retry-After.
502The document service behind the API failed or could not be reached.Retry shortly. If it persists, contact support.
{
  "message": "A valid API key is required. Send it in the X-API-Key header."
}

A document that could not be read is not an error: the request still answers 200, with null values and empty fields.

Rate limits

You can make 30 requests per minute from one IP address, across all endpoints. Each response tells you where you stand:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in the current minute.
Retry-AfterOn a 429: seconds to wait before trying again.

Keys and usage

Every request made with one of your keys is recorded, whether it succeeds or fails, and shown in your dashboard:

  • Overview — requests today and in the last 30 days, success rate, average time, and breakdowns by status and scenario.
  • API keys — create and revoke keys, and see how many requests each made and when it was last used.
  • Usage — the full request log, filtered by key and status.

Questions about your integration: info@g4t.online