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.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 toiat
.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.
Option | Description |
---|---|
Primary color | The accent color, for example used for buttons. |
Background color | Background color of the frame/page. |
Text color | Heading and body text color. |
Font | Heading and body font family (must be web safe or a generic font family) |
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.
Error in response | Description |
---|---|
processing | Error occurred while processing the document An (unexpected) problem occurred on the server. |
unknown_type_front | Front side of document was not recognized Image/scan quality was not sufficient for document recognition. |
unknown_type_back | Back side of document was not recognized Image/scan quality was not sufficient for document recognition. |
expiration_criteria_not_met | Document was expired The document has been found to have expired according to the expiration date indicated on it, as per the set criteria. By default, this refers to the current date. |
unable_to_determine_date_of_expiry | Unable to determine expiry date on the document While the image/scan quality was sufficient for document recognition, it was either still of poor quality or masked, resulting in this field being unreadable. |
text_fields_analysis_failed | Document fields failed to be detected While the image/scan quality was sufficient for document recognition, it was still of poor quality, resulting in all OCR fields being unreadable. |
age_criteria_not_met | Transaction aborted due to user's age The user's age does not meet the criteria set for the transaction, as determined from the age field on the document. |
unable_to_determine_age | Unable to determine age on the document While the image/scan quality was sufficient for document recognition, it was either still of poor quality or masked, resulting in this field being unreadable. |
field_validation_failed | Document data was invalid The field from the document was found to be invalid (incorrect social security number formats or impossible values), suggesting the possibility of a fake or tampered document. |
front_side_provided_back_side_required | Back side of the document is required The front side of the document has been provided, but the back side of the document is required. |
back_side_provided_front_side_required | Front side of the document is required The back side of the document has been provided, but the front side of the document is required. |
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.
Error in response | Invoiced |
---|---|
processing | No |
unknown_type_front | No |
unknown_type_back | No |
expiration_criteria_not_met | Yes |
unable_to_determine_date_of_expiry | Yes |
text_fields_analysis_failed | Yes |
age_criteria_not_met | Yes |
unable_to_determine_age | Yes |
field_validation_failed | Yes |
front_side_provided_back_side_required | Yes |
back_side_provided_front_side_required | Yes |
null | Yes |
All executed face liveness and face match tasks are invoiced, regardless of the final state.
Updated about 2 months ago