ID Reader Plus

POST

  https://api.apptenticate.com/api/v3.2/ocr/

Authentication

Use your JWT obtained from the authentication process to make requests to this endpoint.

The response will be 401 unauthorized if the JWT is expired. In this case you will have to obtain a new JWT.

---

This endpoint receives all requests directed to the Apptenticate OCR microservice that allows data to be extracted from identification documents.

If this service has been contracted, a Proof of Life verification of the document is carried out to verify the validity of the document. This service verifies the veracity of the image to detect attacks such as documents not physically possessed or manipulation of an otherwise authentic document, documents presented as a hard copy, face replacement, or documents on another screen.

In the end, the ID Reader microservice will return a JSON with the extracted data if the operation was successful, or the appropriate error if it fails the proof-of-life check.

NOTE

• The response may be 401 unauthorized if the JWT token must be refreshed.
• Images sent in jpg format or in base64 must not exceed 2MB.
• The images (frontside and backside) can be sent as a .jpg file or as a base64 string, for example: "data:image/jpg;base64,<base64_content>".
• If you want to obtain the transaction ID in the response, you must indicate "return_id": "True" in the JSON of the request.
• It must be specified in the request whether a photo of a passport or ID is sent using the “document_type” parameter, which can take the values “passport” or “identification_card”.
• When the document liveness check succeeds, the response may include the warnings field as extra information: an array of image quality alerts (code and message) that do not prevent valid from being true.

Request structure - method: POST

The payload sent is the same for IDs and Passports

Ruta: api/ocr/

• Payload for base request:

Payload: {
    'frontside': Image of the front of the document,
    'document_type': 'passport'
    'document_id': Passport code // optional if you want to obtain the OCR of a passport that is supported in the library
} // (where images are .jpg files or base64 strings)

• Payload with image in base64:

Payload: {
    'frontside': 'data:image/jpg;base64,<base64_content>',
    'document_type': 'passport',
}

• Payload for ID base request:

Payload: {
    'frontside': Image of the front of the document,
    'backside': Image of the back of the document,
    'document_type': 'identification_card',
} // (where images are .jpg files or base64 strings)

• If you want to obtain the transaction ID:

Payload: {
    'frontside': Image of the front of the document,
    'document_type': 'passport',
    'return_id':True
    'document_id': Passport code // optional if you want to obtain the OCR of a passport that is supported in the library
} // (where images are .jpg files or base64 strings)

• If you want to improve the precision of the life test

Payload: {
    'frontside': Image of the front of the document,
    'document_type': 'passport',
    'device':'IOS', // Devices: IOS, ANDROID or DESKTOP
    'document_id': Passport code // optional if you want to obtain the OCR of a passport that is supported in the library
} // (where images are .jpg files or base64 strings)

Response structure

• Response with transaction ID:

Response format: JSON

{
    "document_number": "E-8-123456",
    "names": "Sofia Maria",
    "surnames": "Lopez Contreras",
    "gender": "F",
    "birth_country": "VENEZUELA",
    "birth_date": "10-10-1994",
    "nationality": "VENEZOLANA",
    "issuing_date": "12-08-2022",
    "expiration_date": "12-08-2032",
    "valid": true,
    "warnings": [ // Document image quality alerts (may appear even when valid is true)
        {
            "code": 823,
            "message": "Los bordes del documento están fuera de la imagen."
        },
        {
            "code": 825,
            "message": "El documento está demasiado cerca del borde del marco."
        }
    ],
    "id": 281234
}

• Response with transaction ID and validate_sides (True):

Response format: JSON

{
    "backside": {
        "document_number": "E-8-123456",
        "names": "Sofia Maria",
        "surnames": "Lopez Contreras",
        "gender": "F",
        "birth_country": "VENEZUELA",
        "birth_date": "10-10-1994",
        "nationality": "VENEZOLANA",
        "issuing_date": "12-08-2022",
        "expiration_date": "12-08-2032"
    },
    "frontside": {
        "names": "Sofia Maria",
        "surnames": "Lopez Contreras",
        "birth_date": "11-07-1986",
        "document_number": "E-8-123456",
        "birth_country": "VENEZUELA",
        "gender": "F",
        "blood_type": "",
        "issuing_date": "12-08-2022",
        "expiration_date": "15-12-2036",
        "nationality": "VENEZOLANA"
    },
    "matches_percentage": 100.0,
    "match": true,
    "valid": true,
    "warnings": [ // Document image quality alerts (may appear even when valid is true)
        {
            "code": 823,
            "message": "Los bordes del documento están fuera de la imagen."
        },
        {
            "code": 825,
            "message": "El documento está demasiado cerca del borde del marco."
        }
    ],
    "id": 5323
}

Note about warnings: when the ID Reader Plus service is contracted and the document liveness check succeeds, the response may include the warnings field. It is an array of objects with code and message that indicates image quality alerts (for example, borders outside the frame or document too close to the edge). These alerts do not prevent valid from being true.

Request examples

Answers to documents that do not pass the life test

Ruta: api/ocr/

{
    "valid": false,
    "error_code": 820,
    "error": "The document photo is not detected in the image.",
    "id": 391
},

{
    "valid": false,
    "error_code": 821,
    "error": "The document is cropped, part of the document is not present in the image.",
    "id": 392
},

{
    "valid": false,
    "error_code": 819,
    "error": "The document is not detected in the image.",
    "id": 393
}

Códigos de error:

Codigo	Mensaje
818	Image quality for document liveness not acceptable.
819	The document is not detected in the image.
820	The document photo is not detected in the image.
821	The document is cropped, part of the document is not present in the image.
822	The size of the document is lower than 10 % of the size of the image.
823	The document borders are outside of the photo frame.
824	There is more than one document in the photo frame.
825	The document is near of the edges of the photo frame.
826	The document is too blurry.
827	The document is overly compressed..
828	The document is either too bright or too dark.
829	The document has reflections