---
title: "ID Scan"
description: "ID Scan is a service to perform online ID verifications. This documentation focuses on the API integration."
canonical: "https://docs.cm.com/verification/id-scan"
---

# ID Scan

> ID Scan is a service to perform online ID verifications. This documentation focuses on the API integration.

Source: https://docs.cm.com/verification/id-scan

ID Scan is a service to perform online ID verifications. This documentation focuses on the **API** integration.

For a complete technical documentation with specifications for all field types, **JSON** objects and methods, you can consult our complete API reference: [API reference](https://docs.cm.com/verification/id-scan/v1/api-reference)

If you need technical assistance, please contact your account manager or [support](https://www.cm.com/app/support/).

## Service description

### Transactions

A transaction is a collection of information related to the ID verification process. It consists of tasks and settings.

### Task

A task is an action that needs to be performed by the end user.

## Environment

The base URL for all API requests:

Production: `https://api.cm.com/id-scan/v1/`

## Usage

The steps for using the service are:

1. [Create a transaction](https://docs.cm.com/verification/id-scan/create-transaction) with tasks.
2. [Load the transaction URL](https://docs.cm.com/verification/id-scan/create-transaction#integrate-on-website) in an iframe on your website.
3. The end user will perform the transaction tasks.
4. After all tasks are completed, a JavaScript event is sent with the result ID.
5. [Listen for the event](https://docs.cm.com/verification/id-scan/events) with the result ID.
6. [Retrieve the data](https://docs.cm.com/verification/id-scan/transaction-result) using the result ID.
7. _Optional: download [document images](https://docs.cm.com/verification/id-scan/transaction-result#download-document-image-and-video) or the [audit report](https://docs.cm.com/verification/id-scan/transaction-result#retrieve-audit-report)_

## Authentication

Before you can start using the API, you need API credentials. Credentials consist of a key ID and secret. Contact your account manager to get production credentials. Credentials should be kept secret.

In order to authenticate you need to use your credentials to generate a JWT Bearer token. The [JWT token](https://jwt.io/introduction/) has to be generated using the `HS256` algorithm and your credentials. This JWT has to contain the following attributes: `iat`, `nbf`, and `exp` in the payload, as well as the attribute `kid` in the header of the JWT. This `kid` attribute needs to contain the Key ID of your credentials.

The generated token needs to be passed via the HTTP Authorization header:

```text title="Request headers"
Authorization: Bearer GENERATED_TOKEN_HERE
```

There are many libraries available for different programming languages that can help you to generate a JWT. See the Libraries tab on [https://jwt.io](https://jwt.io).

**Example**

Assuming we want to create a token that is valid for 60 seconds and we have received the following credentials:

Key ID: `3b438437-04a4-40bb-8389-54bb02766fba`
Secret: `AC4Etykn7jusGR5FwLDAtILtQbiQbTMKedP31szXg4WlSbjGEXyNMZ`

We need to create a JWT with the following properties:

```json title="JWT header"
{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "3b438437-04a4-40bb-8389-54bb02766fba"
}
```

```json title="JWT payload"
{
    "iat": 1546300800,
    "nbf": 1546300800,
    "exp": 1546300860
}
```

- `iat`: the time when the token was generated.
- `nbf`: the time after which the token is valid, usually equal to `iat`.
- `exp`: the time when the token will expire.

:::note
Make sure these are UNIX timestamps in seconds
:::

This results in the following token:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjNiNDM4NDM3LTA0YTQtNDBiYi04Mzg5LTU0YmIwMjc2NmZiYSJ9.eyJpYXQiOjE1NDYzMDA4MDAsIm5iZiI6MTU0NjMwMDgwMCwiZXhwIjoxNTQ2MzAwODYwfQ.bwqCUHS1d5d8guAPHDsdd9-a8oXxH1q45O0tDP1asTo
```

Add this token to the `Authorization` header in the API request.

```text title="Request headers"
Authorization: Bearer GENERATED_TOKEN_HERE
```

> The [https://jwt.io](https://jwt.io) website provides a way to inspect or validate JWT tokens.

## Branding

The ID Scan UI can be customized to match your brand or website theme. Contact us to have this configured.

| Option | Description |
| - | - |
| Primary color | The accent color, for example used for buttons. |
| Background color | Background color of the frame/page. |
| Text color | Heading and body text color. |
| Font | Heading and body font family (must be web safe or a generic font family) |

## Error handling

### Generic

When a 4xx or 5xx error occurs, you will receive a JSON response describing the error.

```json title="Example"
{
    "status": 400,
    "message": "Error message"
}
```

### Document scan errors

The table below specifies each possible error response during a document scan task along with a description and reason it might occur.

| Error in response | Description |
| - | - |
| processing | **Error occurred while processing the document**<br />An (unexpected) problem occurred on the server. |
| unknown\_type\_front | **Front side of document was not recognized**<br />Image/scan quality was not sufficient for document recognition. |
| unknown\_type\_back | **Back side of document was not recognized**<br />Image/scan quality was not sufficient for document recognition. |
| expiration\_criteria\_not\_met | **Document was expired**<br />The document has been found to have expired according to the expiration date indicated on it, as per the set criteria. By default, this refers to the current date. |
| unable\_to\_determine\_date\_of\_expiry | **Unable to determine expiry date on the document**<br />While the image/scan quality was sufficient for document recognition, it was either still of poor quality or masked, resulting in this field being unreadable. |
| text\_fields\_analysis\_failed | **Document fields failed to be detected**<br />While the image/scan quality was sufficient for document recognition, it was still of poor quality, resulting in all OCR fields being unreadable. |
| age\_criteria\_not\_met | **Transaction aborted due to user's age**<br />The user's age does not meet the criteria set for the transaction, as determined from the age field on the document. |
| unable\_to\_determine\_age | **Unable to determine age on the document**<br />While the image/scan quality was sufficient for document recognition, it was either still of poor quality or masked, resulting in this field being unreadable. |
| field\_validation\_failed | **Document data was invalid**<br />The field from the document was found to be invalid (incorrect social security number formats or impossible values), suggesting the possibility of a fake or tampered document. |
| front\_side\_provided\_back\_side\_required | **Back side of the document is required**<br />The front side of the document has been provided, but the back side of the document is also required. |
| back\_side\_provided\_front\_side\_required | **Front side of the document is required**<br />The back side of the document has been provided, but the front side of the document is also required. |
| image\_quality\_requirements\_not\_met | **Image quality requirements were not met**<br />One or more of the image quality checks enabled for your account failed. See [image quality checks](https://docs.cm.com/verification/id-scan/configuration#image-quality-checks). |

:::note
**Other side required occasions**

Another side/page of the document may be required in the following scenarios:

- ID-1 size documents (most ID cards and driving licenses) was detected
- `requireBothSides` setting enabled
- MRZ not found
- Date of expiry not found
- Date of birth not found and `minimumAge` or `maximumAge` settings were included
:::

## Invoicing

Not all document scan tasks are invoiced. To help clarify what exactly is invoiced during a document scan task, the table below specifies each possible error response during a document scan task and whether it will be invoiced. As of the 1st of January 2025, only one document scan attempt will be invoiced per transaction.

| Error in response | Invoiced |
| - | - |
| processing | No |
| unknown\_type\_front | No |
| unknown\_type\_back | No |
| expiration\_criteria\_not\_met | Yes |
| unable\_to\_determine\_date\_of\_expiry | Yes |
| text\_fields\_analysis\_failed | Yes |
| age\_criteria\_not\_met | Yes |
| unable\_to\_determine\_age | Yes |
| field\_validation\_failed | Yes |
| front\_side\_provided\_back\_side\_required | Yes |
| back\_side\_provided\_front\_side\_required | Yes |
| image\_quality\_requirements\_not\_met | Yes |
| _null_ | Yes |

All _executed_ face liveness and face match tasks are invoiced, regardless of the final state.
