This API offers the ability to create a group of persons that needs to identify using iDIN.
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
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 generatednbf
is the time after the token is validexp
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.
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"
}
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"
}
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"
}
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
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.
POST https://your.api.url
{
"id": "EVENT_GUID",
"event": "group.updated",
"group": "GROUP_GUID",
"status": "pending|completed|declined|expired",
"created": "2020-01-01T00:00:00+00:00"
}
{
"id": "EVENT_GUID",
"event": "group.deleted",
"group": "GROUP_GUID",
"status": "pending|completed|declined|expired",
"created": "2020-01-01T00:00:00+00:00"
}
{
"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"
}
{
"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"
}
For a complete technical documentation with specifications for all field types, JSON objects and methods, you can consult our complete swagger specification.