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.
• Optional: download document images or the 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 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:

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.

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:

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

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.

📘

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.

Authorization: Bearer GENERATED_TOKEN_HERE

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

Error handling

Generic

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

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.

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.

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