Identify a user

A transaction is a session in which an end-user proves their identity using a specific identification method. Creating a transaction returns a hosted URL that the end-user should be redirected to in order to complete the flow.

When creating a transaction, you specify the list of fields to collect from the end-user via requestedFields. If the transaction is successful, the collected values are returned via the data property when retrieving the transaction. Fields that were requested but could not be provided by the identification method used by the end-user are listed in unavailableFields. The raw, unprocessed response from the identification method is also available via rawData whenever present.

The language of the hosted transaction UI can be configured per transaction. If no locale is provided, the UI defaults to en-US.

After the end-user is redirected back to the returnUrl, use the Get a transaction endpoint with the transactionId to retrieve the final state and any collected data.

Create a transaction

Request

Request

POST https://api.cm.com/identity-hub/v1/transactions

Request headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Request body

{
    "returnUrl": "https://example.com/transaction/return",
    "callbackUrl": "https://example.com/transaction/callback",
    "locale": "en-US",
    "requestedFields": ["givenName", "familyName", "birthdate", "identifier"]
}

Parameters

Property	Type	Required	Description
returnUrl	string	Yes	The URL the end-user will be redirected to after completing the transaction. The transactionId and state will be appended as query parameters. Maximum length is 255 characters.
callbackUrl	string	No	An HTTPS URL that is notified whenever the transaction changes state, so you can retrieve the latest details. Maximum length is 255 characters. See Events.
locale	string	No	The language used for the hosted transaction UI. Defaults to en-US if not provided. Possible locales are nl-NL, en-US, fr-FR, de-DE, hu-HU, it-IT, ja-JP, pl-PL, pt-PT, ro-RO, sk-SK, es-ES.
requestedFields	array	Yes	The list of fields to collect from the end-user during the transaction. At least one field is required. Possible items are givenName, middleName, familyName, gender, birthdate, email, phoneNumber, address, nationality, identifier.

Response body

{
    "id": "b3e1c8f2-3a9d-4f4f-8b1a-1c2d3e4f5a6b",
    "url": "https://www.cm.com/app/identity-hub/session/aQ9pX3vN7wL2kB4mR8sT6yU0iO5cF1eH"
}

Parameters

Property	Description
id	Unique identifier of the transaction. In UUID format. Use this to retrieve the transaction later.
url	The hosted URL the end-user should be redirected to in order to complete the transaction flow.

Get a transaction

Retrieve an existing transaction by its id. The shape of the response depends on the current state of the transaction:

• created: The transaction has been created but the end-user has not started the flow yet.
• started: The end-user has selected a method and started the transaction flow.
• success: The transaction was successful.
• failed: The transaction was not successful.

Request

Request

GET https://api.cm.com/identity-hub/v1/transactions/{id}

Request headers

Authorization: Bearer GENERATED_TOKEN_HERE

URL parameter

Parameter	Type	Description
id	string	The UUID of the transaction, returned in the response after creating it.

Response body

{
    "id": "b3e1c8f2-3a9d-4f4f-8b1a-1c2d3e4f5a6b",
    "state": "success",
    "method": "idin",
    "methodType": "full",
    "data": {
        "givenName": "J.",
        "familyName": "Doe",
        "birthdate": "1980-01-31",
        "identifier": "NLINGB3x4u89498qe4tqjvdaj0"
    },
    "unavailableFields": ["nationality"],
    "rawData": {
        "status": "success",
        "issuer_id": "RABONL2U",
        "bin": "NLINGB3x4u89498qe4tqjvdaj0",
        "name": {
            "initials": "J.",
            "last_name": "Doe"
        },
        "age": {
            "date_of_birth": "1980-01-31"
        }
    }
}

Parameters

Property	Description
id	Unique identifier of the transaction. In UUID format.
state	Current state of the transaction. Possible values: created, started, success, failed.
method	The identification method selected by the end-user. null until the end-user has selected a method.
methodType	The specific type of the selected method, when a method offers more than one. For example basic or full for ID Scan. null when not applicable.
data	The collected transaction data. Only included when state is success. See data fields for the full list.
unavailableFields	The requested fields that could not be provided by the identification method used. Only included when state is success.
rawData	The raw, unprocessed response from the identification method used. Its structure depends on the method and is not normalized. Included whenever available, typically once the transaction is success or failed.

Data fields

Property	Description
givenName	The end-user's given name(s).
middleName	The end-user's middle name(s).
familyName	The end-user's family name.
gender	The end-user's gender.
birthdate	The end-user's date of birth in YYYY-MM-DD format.
email	The end-user's email address.
phoneNumber	The end-user's phone number in E.164 format.
address	The end-user's address.
nationality	The end-user's nationality.
identifier	A stable user identifier that is unique per identification method (e.g. the iDIN BIN). Not available for all methods.