iDIN invites

This API offers the ability to create a group of persons that needs to identify using iDIN.

Authentication

Before you can start using the API, you need to be provided with credentials. The credentials provided by CM are confidential and 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, 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 like:

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

Create a token that is valid for 60 seconds and assume we have received the following credentials:

Key ID: 3b438437-04a4-40bb-8389-54bb02766fba
Key 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 is the time the token is generated
nbf is the time after the token is valid
exp is the time the token will expire

Make sure the UNIX timestamp is 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 a token.

Base URL

https://api.cm.com

Create a group

POST /idin-invites/v1/groups

Request:

{
  "name": "Company ABC"
}

Response:

{
  "id": "1f7d7d18-3b0e-4322-8919-49e51d40c38b",
  "name": "Company ABC",
  "status": "pending",
  "expires_at": "2020-02-01T00:00:00+00:00",
  "updated_at": "2020-01-01T00:00:00+00:00",
  "created_at": "2020-01-01T00:00:00+00:00"
}

Add persons to a group

POST /idin-invites/v1/groups/{groupId}/persons

Request:

{
  "name": "Andre van Dijk",
  "email_address": "[email protected]",
  "attributes": {
    "identity": false,
    "name": "true",
    "address": false,
    "18y_or_older": false,
    "date_of_birth": false,
    "gender": false,
    "telephone_number": false,
    "email_address": false
  }
}

Response:

{
  "id": "81f50a17-b556-48b2-a79b-6bc5315d9083",
  "name": "Andre van Dijk",
  "email_address": "[email protected]",
  "attributes": {
    "identity": false,
    "name": "true",
    "address": false,
    "18y_or_older": false,
    "date_of_birth": false,
    "gender": false,
    "telephone_number": false,
    "email_address": false
  },
  "redirect_url": null,
  "status": null,
  "result": null,
  "updated_at": "2020-01-01T00:00:00+00:00",
  "created_at": "2020-01-01T00:00:00+00:00"
}

Send identification invite

POST /idin-invites/v1/groups/{groupId}/persons/{personId}/invites

Request:

{
  "email": true
}

Response:

{
  "id": "c6f5a012-524a-4a2e-a77a-5f2c27397c3e",
  "url": "https://www.cm.com/app/idin-invite/WMqmJ8qneA7CiLe3w33NBjSAPiGWFVWeWbMluTI8IkgGjoznfhuajzuV5Y1Xdpfc0SRB1m",
  "email": true,
  "expires_at": "2020-01-01T00:00:00+00:00",
  "updated_at": "2020-01-01T00:00:00+00:00",
  "created_at": "2020-01-01T00:00:00+00:00"
}

Retrieve person identification result

GET /idin-invites/v1/groups/{groupId}/persons/{personId}

Response:

{
  "id": "81f50a17-b556-48b2-a79b-6bc5315d9083",
  "name": "Andre van Dijk",
  "email_address": "[email protected]",
  "status": "success",
  "result": {
    "transaction_id": "1241533522837401",
    "issuer_id": "ABNANL2A",
    "status": "success",
    "bin": "CMBANL9Z3xOcyYKUhR8s0mS+tbkNO2xF2/U/Ns3eIyMOWYWmOZeUGw8StPKPhAdRTyN1XWne1rgJQA",
    "name": {
      "gender": "male",
      "initials": "A",
      "first_name": "Andre",
      "last_name": "Dijk",
      "last_name_prefix": "van"
    },
    "address": {
      "street": "Dijklaan",
      "house_number": "1",
      "house_number_suffix": "b",
      "postal_code": "0000AA",
      "city": "Amsterdam",
      "country": "NL"
    },
    "age": {
      "date_of_birth": "1974-01-31",
      "18y_or_older": true
    },
    "telephone_number": "0031612345678",
    "email_address": "[email protected]"
  },
  "updated_at": "2020-01-01T00:00:00+00:00",
  "created_at": "2020-01-01T00:00:00+00:00"
}

For details about the returned attributes in result check our iDIN documentation

Webhook

A webhook URL can be configured for your client to retrieve status updates. Please contact our support team if you would like to use this feature.

Please note that the URL must respond with a success status code, e.g. 200 or 204. Otherwise the request will be retried.

Events

POST https://your.api.url

Group status updated

{
    "id": "EVENT_GUID",
    "event": "group.updated",
    "group": "GROUP_GUID",
    "status": "pending|completed|declined|expired",
    "created": "2020-01-01T00:00:00+00:00"
}

Group deleted

{
    "id": "EVENT_GUID",
    "event": "group.deleted",
    "group": "GROUP_GUID",
    "status": "pending|completed|declined|expired",
    "created": "2020-01-01T00:00:00+00:00"
}

Person identification status updated

{
    "id": "EVENT_GUID",
    "event": "person.updated",
    "group": "GROUP_GUID",
    "person": "PERSON_GUID",
    "status": "success|cancelled|failure|expired",
    "created": "2020-01-01T00:00:00+00:00"
}

Person deleted from group

{
    "id": "EVENT_GUID",
    "event": "person.deleted",
    "group": "GROUP_GUID",
    "person": "PERSON_GUID",
    "status": "success|cancelled|failure|expired",
    "created": "2020-01-01T00:00:00+00:00"
}

Swagger API documentation

For a complete technical documentation with specifications for all field types, JSON objects and methods, you can consult our complete swagger specification.

Swagger API docs