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

NameValueRequired

Content-Type

multipart/form-data

true

Authorization

Bearer <access token>

true

Query Parameters

NameValueRequired

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:

Response Status

Status codeStatus MessageDescription

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

PropertyValuesDescription

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": "<<<<<<<<<<<"
  }
}

Last updated