Scan API

The following API allows uploading the front and back image of the document using multipart form data.

JPEG, PNG and PDF are supported. Max file size allowed is 5MB for each file. Although we recommend uploading smaller files to avoid affecting performances.

A picture size of ~500KB with a resolution of 1080x1920 can work perfectly fine. High resolution pictures don’t improve the quality of the result and are not needed. If you need to accept a bigger file you need to decrease the size at your end before calling this API.

Note: When a PDF file is used you have two choices for a two page document: you can send front and back in separate files or you can send a single PDF with both images. The system will assume that the first image is the front page of the document.

Note: Utilize this API within your backend and do not make direct calls within your frontend application.

Endpoint URL

POST <Api base url>/api/v1/scan

The <Api base url> is listed in the Customer Portal under Development > Credentials.

Headers

Name	Value	Required
Content-Type	multipart/form-data	true
Authorization	Bearer <access token>	true

Query Parameters

Name	Value	Required
disableExpiryValidation	(true or false) Default value: false If true disables document expiry validation	false
exportFaceImage	(true or false) Default value: true Enable or disable face detection in the document. If not needed it should be disabled	false

Payload (multipart/form-data)

The payload contains the following parts:

Name	Value	Required
documentType	USA_DL UAE_ID UAE_ID_DIGITAL UAE_DL UAE_VL UAE_VISA UAE_EVISA UAE_ID_APPLICATION_FORM OMN_ID PASSPORT PAK_ID SAU_ID SAU_DL BHR_ID KWT_ID GENERIC_ID QAT_ID NLD_DL GHA_ID GHA_DL GHA_VOTER_ID GHA_SSNIT NGA_DL NGA_VOTER_ID NGA_NIN RWA_ID IND_ID KEN_ID EGY_ID SEN_ID UGA_ID UGA_VOTER_ID ZAF_ID ZAF_DL GBR_DL SDN_ID SDN_DL SDN_VL DZA_ID TUR_ID GBR_ID COD_DL COD_VOTER_ID OMN_DL OMN_VL PHL_DL BHR_DL QAT_DL RSL_ID IND_PAN MRZ LBN_ID LBN_DL IRQ_ID TUN_ID SOM_ID BHR_VL JOR_VL SAU_VL MAR_ID	true
frontImage	Binary image of the front page of the document	true
backImage	Binary image of the back page of the document	False (required for a two side document)

Response Status

Status code	Status Message	Description
200	OK	Successful operation. See 2.7. Response Body for Status Code 200
400	Bad Request	See 2.6. Response Body for Status Code 400
401	Unauthorized	Access token missing, invalid or expired
403	Forbidden	Access token not allowed to access a certain API or functionality
413	Payload Too Large
415	Unsupported Media Type
500	Internal Server Error	Unexpected error

Response Body for Status Code 400

Property	Values	Description
error	INVALID_INPUT	Missing required input or invalid format
	SCAN_DOCUMENT_NOT_RECOGNIZED	Document type not recognized. Scanning failed or document type doesn’t match the provided document
	SCAN_DOCUMENT_EXPIRED	Document is expired
	SCAN_DOCUMENT_FRONT_BACK_MISMATCH	Front and back pages don't belong to the same document. Not supported for every document type
message	Description of the error

Response Body for Status Code 200 (application/json)

The API returns a JSON object with the following structure:

{
  "front": {},
  "back": {}
}

Sample Request using curl

$ curl -v \
-H 'Authorization: Bearer token' \
https://example.com/api/v1/scan \
-F documentType=UAE_ID \
-F frontImage=@/front.jpg \
-F backImage=@/back.jpg

Please note that “https://example.com” needs to be replaced with the api server base url.

#Sample Response Body

Below an example of UAE_ID scan process response body:

{
  "front": {
    "fullName": "Mario Casola",
    "identityNumber": "784-19XX-XXXXXXX-9",
    "nationality": "Italy",
    "faceImage": "<base64 encoded face image>"
  },
  "back": {
    "secondaryId": "MARIO",
    "primaryId": "CASOLA",
    "dateOfBirth": "800825",
    "dateOfExpiry": "200306",
    "documentNumber": "0880XXX20",
    "serialNumber": "0B800029B46XXXXX",
    "nationality": "ITA",
    "issuer": "ARE",
    "sex": "M",
    "documentCode": "IL",
    "mrzText": "ILARE0880XXX20378419XXXXXXXXX9\n8008253M2003061ITA<<<<<<<<<<<9\nCASOLA<<MARIO<<<<<<<<<<<<<<<<<\n",
    "mrzVerified": true,
    "opt1": "78419XXXXXXXXX9",
    "opt2": "<<<<<<<<<<<"
  }
}