Document OCR

Extract structured data from identity documents by submitting front and back images in base64 format. The service performs Optical Character Recognition (OCR) and returns parsed fields such as name, document number, and date of birth.

POST

/api/gw/services/document_ocr

---

Authorizations

---

Body

frontImageBase64 · string · required

Base64 encoded front image of the document.

backImageBase64 · string

Base64 encoded back image of the document (if applicable).

documentType · string

Type of document (e.g., passport, id_card, driver_license).

documentCountry · string

Issuing country of the document (ISO3 format recommended).

---

Response

200

success · boolean

Indicates whether the request was processed successfully.

requestId · string

Unique identifier for the API request.

correlationId · string

Identifier used for tracing the request across systems.

data · object

Contains extracted document details.

data.documentType · string

Detected document type (e.g., PASSPORT).

data.issuingCountry · string

Country that issued the document (ISO code).

data.documentNumber · string

Extracted document number.

data.firstName · string

Extracted first name.

data.lastName · string

Extracted last name.

data.dateOfBirth · string

Extracted date of birth (YYYY-MM-DD).

data.gender · string

Extracted gender (e.g., M/F).

data.nationality · string

Extracted nationality (ISO code).

data.issueDate · string

Document issue date (YYYY-MM-DD).

data.expiryDate · string

Document expiry date (YYYY-MM-DD).

data.isExpired · boolean

Indicates whether the document is expired.

data.mrzLine1 · string

Machine-readable zone line 1.

data.mrzLine2 · string

Machine-readable zone line 2.

data.mrzLine3 · string

Machine-readable zone line 3 (if available).

data.confidenceScore · number

Confidence score for extracted data (0 to 1).

data.portraitImage · string

Extracted face image in base64 format (data URL).

error · object | null

Contains error details if the request fails; otherwise null.

durationMs · number

Time taken to process the request in milliseconds.

processedAt · string

Timestamp when the request was processed (ISO 8601 format).

400

error · string

Error message returned when OCR processing fails.

---

Curl

curl -X POST "https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr" \
  -H "Content-Type: application/json" \
  -d '{
    "frontImageBase64": "<base64-front>",
    "backImageBase64": "<base64-back>",
    "documentType": "passport",
    "documentCountry": "GBR"
}'

import requests

url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr"

payload = {
    "frontImageBase64": "<base64-front>",
    "backImageBase64": "<base64-back>",
    "documentType": "passport",
    "documentCountry": "GBR"
}

res = requests.post(url, json=payload)
print(res.json())

fetch("https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    frontImageBase64: "<base64-front>",
    backImageBase64: "<base64-back>",
    documentType: "passport",
    documentCountry: "GBR"
  })
})
.then(res => res.json())
.then(console.log);

<?php
$url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr";

$data = [
  "frontImageBase64" => "<base64-front>",
  "backImageBase64" => "<base64-back>",
  "documentType" => "passport",
  "documentCountry" => "GBR"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

package main

import (
  "bytes"
  "net/http"
)

func main() {
  json := []byte(`{
    "frontImageBase64":"<base64-front>",
    "backImageBase64":"<base64-back>",
    "documentType":"passport",
    "documentCountry":"GBR"
  }`)

  http.Post(
    "https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr",
    "application/json",
    bytes.NewBuffer(json),
  )
}

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {

    OkHttpClient client = new OkHttpClient();

    String json = "{\"frontImageBase64\":\"<base64-front>\", \"backImageBase64\":\"<base64-back>\", \"documentType\":\"passport\", \"documentCountry\":\"GBR\" }";

    RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

    Request request = new Request.Builder()
      .url("https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr")
      .post(body)
      .build();

    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}

require 'net/http'
require 'uri'
require 'json'

uri = URI("https://dev-idf-gw.cognetlabs.org/api/gw/services/document_ocr")

payload = {
  frontImageBase64: "<base64-front>",
  backImageBase64: "<base64-back>",
  documentType: "passport",
  documentCountry: "GBR"
}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri, {'Content-Type': 'application/json'})
request.body = payload.to_json

response = http.request(request)
puts response.body

200

{
"success":true,
"requestId":"da0a115e519e",
"correlationId":"58664e8f17d1452ea3b171e7a90e09bf",
"data":{
"documentType":"PASSPORT",
"issuingCountry":"GBR",
"documentNumber":"123456789",
"firstName":"John",
"lastName":"Doe",
"dateOfBirth":"1992-05-11",
"gender":"M",
"nationality":"GBR",
"issueDate":"2018-01-01",
"expiryDate":"2028-01-01",
"isExpired":false,
"mrzLine1":"P<GBRDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2":"1234567890GBR9205111M2801012<<<<<<<<<<<<<<",
"mrzLine3":"",
"confidenceScore":0.97,
"portraitImage":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
},
"error":null,
"durationMs":303,
"processedAt":"2026-04-29T13:59:35.9472104Z"
}

{
  "error": "FrontImageBase64 is required"
}