Passports
POSThttps://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. In this case, it is possible to process passports that contain MRZ (Machine Readable Zone) and Panamanian ID cards with or without QR code. These requests must specify the type of document to be processed, an image of the front of the document and an image of the back (in the case of identity cards). 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 was not.
NOTE
• The response may be 401 unauthorized if the JWT token must be refreshed.
• Images sent in jpg format must not exceed 2MB.
• 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 if a photo of a passport or an ID card is sent through the parameter “document_type,” which can take the values “passport,” “passport_plus,” or “identification_card.”
Request structure - method: POST
• 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)
• 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)
• 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)
• If OCR of the passport is desired in addition to MRZ reading:
Payload:
{
"frontside": Image of the front of the document,
"document_type": "passport_plus",
"device": "IOS" // Devices: IOS, ANDROID, or DESKTOP
}
// (where images are .jpg files)
Request examples
# JWT Token
header = { 'Authorization': 'Bearer {}'.format(token) }
# Base request payload
data = {'document_type': 'passport'}
files = {
'frontside': imagen_1.jpg,
} # Where images are .jpg files
# If the transaction ID is required
data = {'document_type': 'passport', 'return_id': True}
files = {
'frontside': imagen_1.jpg,
} # Where images are .jpg files
# Base request payload to obtain both MRZ and OCR from a passport
data = {'document_type': 'passport','document_id': '052' }
files = {
'frontside': imagen_1.jpg
} # Where images are .jpg files
# Sending the request
response = requests.post(
apptenticate_url,
data=data,
files=files,
headers=header
)
response = json.loads(response.content)
Response structure
• Response for transaction id (passport):
{
"document_number": "AN654321",
"registry_number": "CC0123456789",
"country": "COL",
"names": "JULIAN ANDRES",
"surnames": "PEREZ GARCIA",
"birth_date": "02-05-94",
"gender": "M",
"expiration_date": "30-07-22",
"image_score": 100,
"valid": true,
"id": 281234
}
• Response from Passport Plus:
{
"MRZ": {
"document_number": "G123456",
"registry_number": "",
"country": "MEX",
"names": "LUIS ALFREDO",
"surnames": "LOPEZ",
"birth_date": "06-07-64",
"gender": "M",
"expiration_date": "15-09-23",
"image_score": 100
},
"OCR": {
"names": "LUIS",
"surnames": "LOPEZ",
"midlename": "ALFREDO",
"document_number": "G123456",
"expiration_date": "15-09-2023",
"birth_date": "06-07-1964",
"issuing_date": "15-09-2017",
"place_of_birth": "MEXICO MEXICO",
"mrz_code": "P<MEXPIZARRO<ZUNIGA<<LUIS<ALFREDO<<<<<<<<<<<\nG123456789MEX7654321M1234567<<<<<<<<<<<<<<00"
},
"valid": true,
"id": 8824
}
Passports supported to obtain OCR
| Country | Code (document_id) |
|---|---|
| Mexico | 052 |
• Response with OCR for document_id (052):
{
"MRZ": {
"document_number": "N1234567",
"registry_number": "",
"country": "MEX",
"names": "MARIA FERNANDA",
"surnames": "PENAFLOR AMADO",
"birth_date": "19-08-94",
"gender": "F",
"expiration_date": "24-08-26",
"image_score": 100
},
"OCR": {
"country": "MEX",
"document_number": "N1234567",
"CURP": "PEAF940819MDFXMR03",
"gender": "F",
"names": "MARIA",
"midlename": "FERNANDA",
"expiration_date": "24-08-2026",
"birth_date": "19-08-1994",
"issuing_date": "24-08-2023",
"place_of_birth": "ALVARO OBREGON DISTRITO FEDERAL"
}
}
• In case of a failed OCR:
{
"MRZ": {
"document_number": "N123567",
"registry_number": "",
"country": "VEN",
"names": "MARIA FERNANDA",
"surnames": "PENAFLOR AMADO",
"birth_date": "24-04-94",
"gender": "F",
"expiration_date": "08-10-31"
}
"OCR": {
"error": "El código de pasaporte enviando no está soportado aún por el servicio",
"error_code": 817
}
}
Códigos de error:
| Code | Message |
|---|---|
800 | The submitted file could not be processed correctly. |
801 | The MRZ could not be extracted from the document. |
802 | The date of birth could not be processed. |
803 | The gender could not be processed. |
804 | The expiration date could not be processed. |
805 | Error processing QR. |
806 | The document metadata could not be extracted. |
807 | Could not extract names from the document. |
808 | The ID number could not be extracted from the document. |
809 | The "frontside" was not sent in the request. |
810 | The "backside" was not sent in the request. |
816 | The document does not match the one specified in the parameters. |
817 | The submitted passport code is not yet supported by the service. |
818 | No se pudo obtener el OCR del frontside. |