OCR API

---

Authentication

Description

The API uses a token-based authentication scheme. Each request must include an Authorization header containing your access key.

Header Example

{
  "Authorization": "YOUR_KEY",
}

• Required: Yes
• Format: Plain-text token.

---

Available endpoints and methods:

• POST /api/process

Description

This endpoint processes submitted documents for OCR and returns structured results.

Request

1. Headers
   • Authorization: Your personal access key (provided by our team).
   • Content-Type: Must be set to application/json.
2. Body
   The request body must include a documents array. Each element in the array should be a string in Base64 format (it may include the data URI prefix, e.g., data:image/jpeg;base64,). This array is designed to allow you to specify both the front and back of a document when applicable. If you need to send multiple parts (e.g., front and back), simply add each Base64-encoded image as a separate element in the array.

Example body:

{
"documents": [
 "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAA...",
 "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAA..."
]
}

Responses

Success Example (200)

{
  "id": "5ad67ada-cbd3-45a8-a1aa-7acc35476365",
  "startTimestamp": 1650451011751,
  "endTimestamp": 1650453826335,
  "value": {
    "types": [
      {
        "name": "IDCARD",
        "probability": 0.9090492129325866,
        "year": "2007-2009",
        "country": "PRT",
        "id": "PRT_IDCARD_2007-2009",
        "side": "A"
      }
    ],
    "fields": [
      {
        "name": "DOCUMENT_NUMBER",
        "sources": [
          {
              "source": "VISUAL",
              "value": "008390126ZX2",
              "original_value": "00839012 6ZX2",
              "probability": 0.9
          }
        ],
        "value": "008390126ZX2",
        "validity_status": true,
        "status": true
      }
    ],
    "images": [
      {
        "name": "PORTRAIT",
        "value": "/9j/4AAQSkZJRgABAQEAxwDHAAD/"
      }
    ],
    "authenticity": [
      {
        "name": "PATTERN_CHECKS",
        "value": true
      }
    ],
    "validations": [
      {
        "name": "OVERALL",
        "value": true
      }
    ]
  }
}

• id: The ID of the process.
• startTimestamp: The timestamp when the process started.
• endTimestamp: The timestamp when the process ended.
• value: OCR results, including types, fields, images, authenticity checks, and validations.

Errors

• 400: Bad Request: The request is invalid.
• 403: Forbidden: Invalid or missing Authorization key.

---

Response Fields Explanation

The value object in the response contains detailed results from the OCR process. Below is a breakdown of its structure and fields.

---

1. types

This field provides information about the type of document identified by the OCR.

Fields:

• name: (string) The type of document detected (e.g., "IDCARD", "PASSPORT").
• probability: (float) The confidence score for the identified type.
• year: (string) The year associated with the document type (e.g., issuance or template year).
• country: (string) The country code where the document is issued (ISO 3166-1 alpha-3 format).
• id: (string) A unique identifier for the detected document type.

---

2. fields

This field contains the extracted text fields from the document. Each entry corresponds to a specific field extracted by the OCR.

Fields:

• name: (string) The name of the extracted field (e.g., "DOCUMENT_NUMBER", "DATE_OF_BIRTH").
• sources: (array) Detailed information about the origin of the extracted field:
  • source: (string) The method or region from which the field was extracted (e.g., "VISUAL", "MRZ").
  • value: (string) The final, processed value for the field.
  • original_value: (string) The raw value as extracted.
  • probability: (float) The confidence score for the extracted value.
• value: (string) The final value of the field (may match the processed sources.value).
• validity_status: (boolean) Whether the extracted field passed validation checks.
• status: (boolean) The overall status of the field extraction.

Each field in the "fields" array represents a relevant piece of data extracted from the identity document, including names, age, nationality, issuing country, and more.

Field Name	Description
SURNAME	Surname
GIVEN_NAMES	Given Name
NATIONALITY_CODE	ISO3166 Country Code
PERSONAL_NUMBER	Document Number
DATE_OF_BIRTH	Date of Birth
AGE	Age
ISSUING_STATE_CODE	Document Issuing Country ISO3166
NATIONALITY	Nationality of the Individual
ISSUING_STATE_NAME	Document Issuing Country (Name)
SURNAME_AND_GIVEN_NAMES	Concatenated Surname and Given Name
DOCUMENT_CLASS_CODE	Document Type
REMAINDERTERM	Months to Document Expiry
FINAL_CHECKDIGIT	Check Digit in MRZ
DATE_OF_EXPIRY_CHECKDIGIT	Check Digit for Expiry Date in MRZ
DATE_OF_EXPIRY	Expiry Date
DATE_OF_BIRTH_CHECKDIGIT	Check Digit for Date of Birth in MRZ
MRZ_STRINGS	Full MRZ
DOCUMENT_NUMBER	Document Number
DOCUMENT_NUMBER_CHECKDIGIT	Check Digit for Document Number in MRZ
SEX	Sex
OPTIONAL_DATA	MRZ Data (often matches the document number)
MRZ_TYPE	Standard ICAO MRZ Type
PARENTS_GIVEN_NAMES	Parents' Given Names
EID_PLACEOFBIRTH_CITY	Place of Birth
ADDRESS	Address
LINE2_OPTIONAL_DATA	MRZ Data
AUTHORITY_CODE	Code of the Document Issuing Authority

---

3. images

This field contains information about the images of the scanned document. Each object in the array has two properties: "name" (the image type name, such as "PORTRAIT" for the holder's photo) and "value" (the image value in base64 format).

Field Name	Description
PORTRAIT	Document holder's photo
GHOST_PORTRAIT	Security impression
SIGNATURE	Holder's signature
DOCUMENT_REVERSE_SIDE	Document reverse side
DOCUMENT_FRONT_SIDE	Document front side

---

4. authenticity

This field contains authenticity checks performed on the document. Each check is represented as a key-value pair.

Fields:

• name: (string) The name of the authenticity check (e.g., "PATTERN_CHECKS").
• value: (boolean or null) The result of the authenticity check:
  • true: The check passed successfully.
  • false: The check failed.
  • null: The check could not be performed.

---

5. validations

This field lists the validations performed on the document, with their respective results.

Fields:

• name: (string) The name of the validation performed. Common validations include:
  • HAS_ALL_PAGES: Whether all expected pages are present.
  • DOCUMENT_TYPE: Whether the document type is valid.
  • EXPIRE: Whether the document has expired.
  • IMAGE_QUALITY: Whether the image quality is acceptable.
  • MRZ: Whether the Machine-Readable Zone is valid.
  • OVERALL: The overall result of the validations.
  • SECURITY: Whether security features are verified. This is the result of all the authenticity checks performed on the document (e.g., PATTERN_CHECKS). If any authenticity check fails, SECURITY will be false.
  • TEXT: Whether the text extraction passed validation.
• value: (boolean or null) The result of the validation:
  • true: The validation passed.
  • false: The validation failed.
  • null: The validation could not be performed.

Notes on OVERALL:

• The OVERALL validation result reflects the general success of the OCR process.
• If any of the following validations fail (false), OVERALL will also be false:
  • SECURITY
  • DOCUMENT_TYPE
  • EXPIRE
  • TEXT

---