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.
- 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
- Create an account, or log in.
- Open API keys and create a key. It is shown once, so copy it.
- Send a document image with the key in the
X-API-Keyheader:
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:
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.
Process a document
Reads one document. Send its page images, or an image URL, or the name of a built-in sample.
Parameters
| Name | Type | Description |
|---|---|---|
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* | string | An http or https URL of the document image, instead of images[]. It must be reachable from the internet. |
samplerequired* | string | Name of a built-in sample, instead of your own document. See List samples. |
scenariooptional | string | What to read. Defaults to FullProcess. See List scenarios. |
portraitoptional | file | A selfie or other portrait (JPG, PNG, WEBP, up to 15 MB) to compare with the portrait on the document. See Face match. |
include_imagesoptional | boolean | Send 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'
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders(['X-API-Key' => config('services.readout.key')])
->attach('images[]', file_get_contents('id-front.jpg'), 'id-front.jpg')
->attach('images[]', file_get_contents('id-back.jpg'), 'id-back.jpg')
->attach('portrait', file_get_contents('selfie.jpg'), 'selfie.jpg')
->post('https://readout.g4t.io/api/document/process', ['scenario' => 'FullProcess'])
->throw();
$document = $response->json('document');
$holder = $response->json('holder');
// Node.js 18+ (run this on your server, not in the browser)
import { openAsBlob } from 'node:fs';
const form = new FormData();
form.append('images[]', await openAsBlob('id-front.jpg'), 'id-front.jpg');
form.append('images[]', await openAsBlob('id-back.jpg'), 'id-back.jpg');
form.append('portrait', await openAsBlob('selfie.jpg'), 'selfie.jpg');
form.append('scenario', 'FullProcess');
const response = await fetch('https://readout.g4t.io/api/document/process', {
method: 'POST',
headers: { 'X-API-Key': process.env.READOUT_API_KEY },
body: form,
});
if (!response.ok) throw new Error((await response.json()).message);
const result = await response.json();
import os
import requests
with open("id-front.jpg", "rb") as front, open("id-back.jpg", "rb") as back, open("selfie.jpg", "rb") as selfie:
response = requests.post(
"https://readout.g4t.io/api/document/process",
headers={"X-API-Key": os.environ["READOUT_API_KEY"]},
files=[("images[]", front), ("images[]", back), ("portrait", selfie)],
data={"scenario": "FullProcess"},
timeout=90,
)
response.raise_for_status()
result = response.json()
Response 200 OK
{
"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
Returns every scenario you can pass as scenario. A scenario decides what is read from the document; FullProcess reads everything.
{
"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
| Value | What it does |
|---|---|
Mrz | Obtains MRZ data. |
Barcode | Obtains barcode data. |
Locate | Detects document boundaries. |
Ocr | Obtains visual zone OCR results. |
DocType | Recognises the document type. |
MrzOrBarcode | Obtains MRZ and/or barcode data. |
MrzOrLocate | Detects document boundaries and/or obtains MRZ data. |
MrzAndLocate | Detects document boundaries and obtains MRZ data. |
BarcodeAndLocate | Detects document boundaries and obtains barcode data. |
MrzOrOcr | Obtains MRZ data or visual zone OCR results. |
MrzOrBarcodeOrOcr | Obtains MRZ, barcode or visual zone OCR results. |
LocateVisual_And_MrzOrOcr | Detects document boundaries and obtains MRZ data or visual zone OCR results. |
FullProcessdefault | Obtains all document data: text fields, images and checks. |
FullAuth | Obtains all document data and authenticates the document. |
RusStamp | Obtains data from registration stamps. |
OcrFree | Obtains OCR results of any image. |
CreditCard | Obtains bank card data. |
Capture | Returns the original image without any processing. |
DTC | Processes Digital Travel Credentials (DTC-VC) data. |
RFID | Processes RFID chip data. |
mDL | Processes 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
Returns the built-in sample documents. Pass a sample's value as sample to process it without uploading anything — useful for testing your integration.
{
"data": [
{
"value": "PASSPORT",
"title": "Passport",
"description": "One cropped page.",
"preview_url": "https://readout.g4t.io/demo/sample/PASSPORT/preview"
}
]
}
Available samples
| Value | Title | What is sent |
|---|---|---|
PASSPORT | Passport | One cropped page. |
RESIDENCE_PERMIT | Residence Permit | One cropped page. |
ID_CARD | ID Card, incl. RFID data | Front and back, RFID chip session, face match. |
DRIVING_LICENSE | Driving License | One page plus an external portrait for face match. |
ONE_SHOT | One-Shot Identification | Uncropped photo of a person holding the document. |
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
| Key | Type | Description |
|---|---|---|
transaction_id | string · null | Identifier of this processing run. Keep it if you need to ask about a specific request. |
finished | boolean | true when the document was processed completely. |
elapsed_ms | integer · null | Time the reading itself took, in milliseconds. |
scenario | string | The scenario that was used. |
sample | string · null | The sample that was processed, or null for your own document. |
status | object | The overall verdict and each group of checks. See the values below. |
face_match | object · null | null unless a portrait was compared. See Face match. |
document | object | What kind of document it is, its number and dates. |
holder | object | The person the document belongs to. |
fields | array | Every text field that was read, in the order the service returned them. |
images | array | Extracted 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.
| Number | Text | Meaning |
|---|---|---|
1 | passed | The check ran and passed. |
0 | failed | The check ran and failed. |
2 | not_performed | The check did not run, for example RFID without chip data. |
null | null | The service reported nothing for this check. |
Status groups
| Key | What it covers |
|---|---|
overall | The combined verdict of everything below. |
optical | Checks on the images: document type, text validity, expiry, image quality, security features. |
portrait | Comparison of portraits. Needs a portrait in the request, or a sample that includes one. |
rfid | Checks on chip data. Only samples carry chip data. |
stop_list | Whether the document is on a stop list, when the service has one configured. |
age | Age checks on the holder. |
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 -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'
"face_match": { "status": 1, "status_text": "passed", "similarity": 99 }
| Key | Type | Description |
|---|---|---|
status | integer · null | 1 the same person, 0 not a match. Uses the check values. |
status_text | string · null | passed, failed or not_performed. |
similarity | integer · null | How alike the two faces are, from 0 to 100. |
face_matchisnullwhen 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
| Limit | Value |
|---|---|
| Document files per request | 1 to 4, one page per file |
| Document formats | JPG, PNG, WEBP, BMP, TIFF, JP2, PDF |
| Portrait formats | JPG, PNG, WEBP |
| Size per file | 15 MB |
| Image URL | http 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.
| Status | When | What to do |
|---|---|---|
401 | The key is missing, wrong or revoked. | Check the header and the key in the dashboard. |
422 | The request is invalid: no source, bad file type, unknown scenario or sample. | Read errors and fix the named fields. |
429 | Too many requests. See Rate limits. | Wait for the seconds given in Retry-After. |
502 | The 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."
}
{
"message": "Send at least one file in images[], an image_url, or pick a sample. (and 1 more error)",
"errors": {
"images": ["Send at least one file in images[], an image_url, or pick a sample."],
"scenario": ["The selected scenario is not supported. See GET /api/document/scenario."]
}
}
{
"message": "Too Many Attempts."
}
{
"message": "Document service error (HTTP 403)."
}
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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in the current minute. |
Retry-After | On 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