# 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 | <p>(true or false)</p><p>Default value: <strong>false</strong></p><p>If true disables document expiry validation</p>                                          | false    |
| exportFaceImage         | <p>(true or false)</p><p>Default value: <strong>true</strong></p><p>Enable or disable face detection in the document. If not needed it should be disabled</p> | false    |

## Payload (multipart/form-data)

The payload contains the following parts:

| Name         | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| documentType | <p><a href="scan/country-specific-ids/usa_dl-usa-driving-licence">USA\_DL</a></p><p><a href="scan/country-specific-ids/uae_id-uae-emirates-id">UAE\_ID</a></p><p><a href="scan/country-specific-ids/uae_id-uae-emirates-id-digital">UAE\_ID\_DIGITAL</a></p><p><a href="scan/country-specific-ids/uae_dl-uae-driving-licence">UAE\_DL</a></p><p><a href="scan/country-specific-ids/uae_vl-uae-vehicle-licence">UAE\_VL</a></p><p><a href="scan/country-specific-ids/uae_visa-uae-visa">UAE\_VISA</a></p><p><a href="scan/country-specific-ids/uae-evisa">UAE\_EVISA</a><br><a href="scan/country-specific-ids/uae-id-application-form">UAE\_ID\_APPLICATION\_FORM</a></p><p><a href="scan/country-specific-ids/omn_id-oman-id">OMN\_ID</a></p><p><a href="scan/passports">PASSPORT</a></p><p><a href="scan/country-specific-ids/pak_id-pakistan-id">PAK\_ID</a></p><p><a href="scan/country-specific-ids/sau_id-saudi-arabia-id">SAU\_ID</a></p><p><a href="scan/country-specific-ids/sau_dl-saudi-arabia-driving-licence">SAU\_DL</a></p><p><a href="scan/country-specific-ids/bhr_id-bahrain-id">BHR\_ID</a></p><p><a href="scan/country-specific-ids/kwt_id-kuwait-id">KWT\_ID</a></p><p><a href="scan/generic-national-ids">GENERIC\_ID</a></p><p><a href="scan/country-specific-ids/qat_id-qatar-id">QAT\_ID</a></p><p><a href="scan/country-specific-ids/qat_dl-qatar-driving-licence">QAT\_DL</a><br><a href="scan/country-specific-ids/qat_vl-qatar-vehicle-license">QAT\_VL</a></p><p><a href="scan/country-specific-ids/nld_dl-netherlands-driving-licence">NLD\_DL</a></p><p><a href="scan/country-specific-ids/gha_id-ghana-national-id">GHA\_ID</a></p><p><a href="scan/country-specific-ids/gha_dl-ghana-driving-licence">GHA\_DL</a></p><p><a href="scan/country-specific-ids/gha_voter_id-ghana-voter-id">GHA\_VOTER\_ID</a></p><p><a href="scan/country-specific-ids/gha_ssnit-ghana-social-security-and-national-insurance-trust">GHA\_SSNIT</a></p><p><a href="scan/country-specific-ids/nga_dl-nigeria-driving-licence">NGA\_DL</a></p><p><a href="scan/country-specific-ids/nga_voter_id-nigeria-voter-card">NGA\_VOTER\_ID</a></p><p><a href="scan/country-specific-ids/nga_nin-nigeria-digital-nin">NGA\_NIN</a></p><p><a href="scan/country-specific-ids/rwa_id-rwanda-id">RWA\_ID</a></p><p><a href="scan/country-specific-ids/ind_id-india-identity-card">IND\_ID</a></p><p><a href="scan/country-specific-ids/ken_id-kenya-id">KEN\_ID</a></p><p><a href="scan/country-specific-ids/egy_id-egypt-id">EGY\_ID</a></p><p><a href="scan/country-specific-ids/sen_id-senegal-id">SEN\_ID</a></p><p><a href="scan/country-specific-ids/uga_id-uganda-id">UGA\_ID</a></p><p><a href="scan/country-specific-ids/uga_voter_id-uganda-voter-id">UGA\_VOTER\_ID</a></p><p><a href="scan/country-specific-ids/zaf_id-south-africa-id">ZAF\_ID</a></p><p><a href="scan/country-specific-ids/zaf_dl-south-africa-driving-license">ZAF\_DL</a></p><p><a href="scan/country-specific-ids/gbr-dl-uk-driving-license">GBR\_DL</a></p><p><a href="scan/country-specific-ids/sdn_id-sudan-id">SDN\_ID</a></p><p><a href="scan/country-specific-ids/sdn_dl-sudan-driving-licence">SDN\_DL</a></p><p><a href="scan/country-specific-ids/sdn_vl-sudan-vehicle-license">SDN\_VL</a></p><p><a href="scan/country-specific-ids/dza_id-algerian-id">DZA\_ID</a></p><p><a href="scan/country-specific-ids/tur_id-turkish-id">TUR\_ID</a></p><p><a href="scan/country-specific-ids/gbr_id-uk-resident-id">GBR\_ID</a></p><p><a href="scan/country-specific-ids/cod_dl-drc-driving-licence">COD\_DL</a></p><p><a href="scan/country-specific-ids/cod_voter_id-drc-voter-id">COD\_VOTER\_ID</a></p><p><a href="scan/country-specific-ids/omn_dl-oman-driving-licence">OMN\_DL</a></p><p><a href="scan/country-specific-ids/omn_vl-oman-vehicle-license">OMN\_VL</a></p><p><a href="scan/country-specific-ids/phl_dl-philippines-driving-license">PHL\_DL</a></p><p><a href="scan/country-specific-ids/bhr_dl-bahrain-driving-licence">BHR\_DL</a></p><p><a href="scan/country-specific-ids/rsl_id-somaliland-national-id">RSL\_ID</a></p><p><a href="scan/country-specific-ids/ind_pan-indian-pan-card">IND\_PAN</a></p><p><a href="scan/mrz-only-td1-or-td3">MRZ</a></p><p><a href="scan/country-specific-ids/lbn_id-lebanese-id">LBN\_ID</a></p><p><a href="scan/country-specific-ids/lbn-dl-lebanese-driving-licence">LBN\_DL</a></p><p><a href="scan/country-specific-ids/irq_id-iraqi-id">IRQ\_ID</a><br><a href="scan/country-specific-ids/tun_id-tunisian-id">TUN\_ID</a><br><a href="scan/country-specific-ids/som_id-somali-id">SOM\_ID</a><br><a href="scan/country-specific-ids/bhr_vl-bahrain-vehicle-license">BHR\_VL</a><br><a href="scan/country-specific-ids/jor_vl-jordan-vehicle-license">JOR\_VL</a><br><a href="scan/country-specific-ids/sau_vl-saudi-vehicle-license">SAU\_VL</a><br><a href="scan/country-specific-ids/mar_id-moroccan-id">MAR\_ID</a><br><a href="scan/country-specific-ids/idn_id-indonesian-id">IDN\_ID</a></p> | 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](https://docs.uqudo.com/docs/kyc/uqudo-api/broken-reference) |
| 400         | Bad Request            | See [2.6. Response Body for Status Code 400](https://docs.uqudo.com/docs/kyc/uqudo-api/broken-reference)                       |
| 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": "<<<<<<<<<<<"
  }
}
```