Getting started

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

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.

Create a transaction

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

Request headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Request body

{
    "tasks": [
        "document_scan",
        "face_liveness",
        "face_match"
    ],
    "settings": {
        "documentScan": {
            "redactFields": ["personal_number"]
        }
    }
}

Response body

{
    "id": "c3b92333-3935-4c15-a95e-8eb0051e644b",
    "state": "pending",
    "tasks": [
        "document_scan",
        "face_liveness",
        "face_match"
    ],
    "settings": {
        "documentScan": {
            "redactFields": [
                "personal_number"
            ]
        }
    },
    "url": "https://api.cmdisp.com/id-scan/v1/identifications/zAWtVwkuYVDJKg...",
    "expires": "2022-01-01T13:00:00+00:00",
    "created": "2022-01-02T13:00:00+00:00"
}

Task types

TypeDescription
document_scanUpload or take a photo of the front and back side of an ID document.
face_livenessLiveness check using the camera.
face_matchCompares the photo on the ID document with the photo taken during the liveness check.

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.

{
    <other fields omitted for readability>
    "settings": {
        "documentScan": {
            "redactFields": [
                "personal_number",
                "signature"
            ],
            "allowedExpiration": 30
        }
    }
}

Integrate on website

Add an iframe to your website with the transaction URL.

<iframe src="TRANSACTION_URL_HERE" width="650" height="600" allow="camera"></iframe>

📘

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.

<script>
  window.addEventListener('message', function (e) {
    const state = e.data.state;
    const resultId = e.data.resultId;
    // now send the resultId to your backend and retrieve the result
  });
</script>

Retrieve transaction result

When all tasks are completed by the end user you get the result ID from the notification. Use this result ID in combination with the transaction ID to retrieve the transaction results.

Request headers

Authorization: Bearer GENERATED_TOKEN_HERE

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

Response

{
    "id": "c3b92333-3935-4c15-a95e-8eb0051e644b",
    "state": "completed",
    "tasks": [
        {
            "type": "document_scan",
            "state": "completed",
            "score": 0.86,
            "result": [
                {
                    "field": "document_number",
                    "locale": null,
                    "values": [
                        {
                            "source": "mrz",
                            "value": "SPECI2021"
                        },
                        {
                            "source": "visual",
                            "value": "SPECI2021"
                        }
                    ]
                },
                {
                    "field": "given_names",
                    "locale": null,
                    "values": [
                        {
                            "source": "mrz",
                            "value": "WILLEKE LISELOTTE"
                        },
                        {
                            "source": "visual",
                            "value": "WILLEKE LISELOTTE"
                        }
                    ]
                },
                {
                    "field": "given_names",
                    "locale": "nl-NL",
                    "values": [
                        {
                            "source": "visual",
                            "value": "Willeke Liselotte"
                        }
                    ]
                },
                {
                    "field": "nationality",
                    "locale": null,
                    "values": [
                        {
                            "source": "mrz",
                            "value": "Netherlands"
                        }
                    ]
                },
                {
                    "field": "nationality",
                    "locale": "nl-NL",
                    "values": [
                        {
                            "source": "visual",
                            "value": "Nederlandse"
                        }
                    ]
                },
                <other fields omitted for readability>
            ],
            "files": [
                {
                    "category": "document",
                    "type": "Netherlands - Driving License (2022)",
                    "score": 0.85,
                    "url": "https:\/\/api.cmdisp.com\/id-scan\/v1\/downloads\/pz6vLGjX9OOOsiQxEY..."
                },
                {
                    "category": "document",
                    "type": "Netherlands - Driving License (2022) Side B",
                    "score": 0.87,
                    "url": "https:\/\/api.cmdisp.com\/id-scan\/v1\/downloads\/55mrqZQhtp1wa3a1uC..."
                },
                {
                    "category": "image",
                    "type": "portrait",
                    "url": "https:\/\/api.cmdisp.com\/id-scan\/v1\/downloads\/YNBQ0V4nofRehT8e2Y..."
                }
            ]
        },
        {
            "type": "face_liveness",
            "state": "completed"
        },
        {
            "type": "face_match",
            "state": "completed",
            "score": 0.877
        }
    ]
}

📘

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

Authorization: Bearer GENERATED_TOKEN_HERE
GET https://api.cmdisp.com/id-scan/v1/downloads/pz6vLGjX9OOOsiQxEY...

Response

Binary image

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:

{
    "status": 400,
    "message": "Error message"
}