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](🔗)

If you need technical assistance, please contact your account manager or support ([[email protected]](🔗)).

# 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:

• Create a transaction with tasks.

• Load the transaction URL in an iframe on your website.

• The end user will perform the transaction tasks.

• After all tasks are completed, a JavaScript event is sent with the result ID.

• Listen for the event with the result ID.

• Retrieve the data using the result ID.

# 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](🔗) 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:

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>.

**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:

JWT header:

JWT payload:

• `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.

📘



Make sure these are UNIX timestamps in seconds

This results in the following token:

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

The <https://jwt.io> website provides a way to inspect or validate JWT tokens.

# Create a transaction

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

**Request headers**

**Request body**

**Response body**

## Task types

**Valid combinations**

• `document_scan`

• `document_scan`, `face_liveness`

• `document_scan`, `face_liveness`, `face_match`

## Settings

Configure the task behavior. For example, change the allowed [document expiration](🔗) or [redact fields](🔗) from the downloaded document image.

### Locale

Sets the language of the transaction. Currently supports English `en-US`, Dutch `nl-NL`, and French `fr-FR`. This setting is optional. By default, a transaction is in English `en-US`.

### Mobile only

Controls whether a user is forced to use a mobile device to complete all task for the transaction. When set to `true` a user is forced to use a mobile device and when set to `false` a user can also use a non-mobile device like a desktop. This setting is optional. By default, this is `false`.

### Expires in

Set the time in seconds after which a transaction expires. The number of seconds can be between 3600 (1 hour) to a maximum of 86400 seconds (24 hours). This setting is optional. By default a transaction will expire after one hour.

# Integrate on website

## Integration with iframe

Add an iframe to your website with the transaction URL.

📘



Make sure the minimum width is set to 650 to ensure there is enough space for the embedded page.

Add an event listener on the page to retrieve a notification when the transaction completes.

## Integration with return URL

Create the transaction with return URL and scan return URL.

Redirect the user to the `url` returned in the transaction response.

After the transaction is completed the user is redirected to the `returnUrl`. The query parameters `trxid` and `resultid` are appended to the URL. Use transaction ID in combination with the result ID to retrieve the transaction result.

The `scanReturnUrl` is used to redirect the user back to your own status page. This is only used when the QR code is scanned and the user completes the transaction on a mobile device. When no URL is set a default status page is shown.

# Retrieve transaction result

When all tasks are completed by the end user you get the result ID from the notification or as query parameter in the return URL. Use this result ID in combination with the transaction ID to retrieve the transaction results. It is recommended to use the `mrz` source if available for a given field, as this will contain the most accurate value.

**Request headers**

`GET https://api.cm.com/id-scan/v1/transactions/{transactionId}/results/{resultId}`

**Response**

📘



This example only shows a small section of field types in results. For a full list of all fields see the [API reference](🔗).

## Download document image

The URL in the `files` section for the `document_scan` task contains the URLs of the document images.

**Request headers**

**Response**

Binary image

# Retrieve transaction report

Once the transaction is completed, you can retrieve an audit report.

This audit report is available to be retrieved by using the transaction ID of the completed transaction as well as the result ID from the notification or return URL query parameter.

There are two types of audit reports: simple and extended.

**Request headers**

**Response**

Downloadable PDF file.

## Simple audit report

The simple report is created when the transaction is completed. This report is always retrievable.

It contains no documents and is not sealed.

## Extended audit report

The extended report is available to be created on request, only within the validity period of the transaction.

After the transaction expires, the extended report will **not ** be able to be retrieved.

It contains all the scanned documents from the transaction and will be digitally sealed. Specify the `type=extended` query parameter to request this report.

# Events

To get notified when a transaction is completed or other events occurred, you can subscribe to events. See: [Events](🔗)

# Error handling

When an error occurs, you will receive a JSON response describing the error. The error codes per endpoint can be found in the API reference.

Example: