Create 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"
]
}
},
"locale": "nl-NL",
"mobileOnly": true,
"expiresIn": 3600
}
Response body
{
"id": "c3b92333-3935-4c15-a95e-8eb0051e644b",
"state": "pending",
"tasks": [
"document_scan",
"face_liveness",
"face_match"
],
"settings": {
"documentScan": {
"redactFields": [
"personal_number"
]
}
},
"url": "https://id-scan.identity.cm.com/en-us/identifications/zAWtVwkuYVDJKg...",
"locale": "nl-NL",
"mobileOnly": true,
"expires": "2024-01-01T13:00:00+00:00",
"created": "2024-01-02T13:00:00+00:00"
}
Request options
Task types
Type | Description |
---|---|
document_scan | Upload or take a photo of the front and back side of an ID document. |
face_liveness | Liveness check using the camera. |
face_match | Compares 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 document scan task behavior. For example, change the allowed document expiration or redact fields from the downloaded document image. Or specify which capture sources should be allowed.
{
// other fields omitted for readability
"settings": {
"documentScan": {
"allowedExpiration": 30,
"redactFields": [
"personal_number",
"signature"
],
"captureSources": [
"camera",
"file"
],
"level": "advanced",
"minimumAge": 16,
"maximumAge": 80,
"requireBothSides": true,
"validateFields": [
"personal_number"
]
}
}
}
Property | Type | Description |
---|---|---|
allowedExpiration | integer | Increase or decrease the allowed expiration of the document based on its expiry date. For more information, see document expiration. |
redactFields | array | The fields to be masked/blurred on the downloaded ID document. For more information, see redact fields. |
captureSources | array | Specify how you would like the user to upload their document, allowed options arefile and camera . For more information, see allowed capture sources. |
level | string | Set the level of the authenticity check performed on the ID document. Either basic or advanced . If not specified, will conduct an advanced scan. |
minimumAge | integer | Set a minimum age of the user. If provided and the user's age derived from the document doesn't meet the criteria, the transaction will fail. |
maximumAge | integer | Set a maximum age of the user. If provided and the user's age derived from the document doesn't meet the criteria, the transaction will fail. Must be higher than minimumAge if both properties are provided. |
requireBothSides | boolean | If set to true , the user will be required to provide both sides of their ID document, even if the personal number was detected on the front side. |
validateFields | array | Specify which document fields should be validated. A field with a validity status of not_checked is also considered valid. If any of the fields have an invalid status, the user must attempt to scan again. A full list of available fields can be found in the API Reference |
Locale
Sets the language of the transaction. Currently supports English en-US
, Dutch nl-NL
, and French fr-FR
. This setting is optional. By default, a transaction is in English en-US
.
{
// other fields omitted for readability
"tasks": [
"document_scan"
],
"locale": "nl-NL"
}
Mobile only
Controls whether a user is forced to use a mobile device to complete all task for the transaction. When set to true
a user is forced to use a mobile device and when set to false
a user can also use a non-mobile device like a desktop. This setting is optional. By default, this is false
.
{
// other fields omitted for readability
"tasks": [
"document_scan"
],
"mobileOnly": true
}
Expires in
Set the time in seconds after which a transaction expires. The number of seconds can be between 3600 (1 hour) to a maximum of 86400 seconds (24 hours). This setting is optional. By default a transaction will expire after one hour.
{
// other fields omitted for readability
"tasks": [
"document_scan"
],
"expiresIn": 7200
}
Integrate on website
Integration with iframe
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 transactionId = e.data.transactionId;
const state = e.data.state;
const resultId = e.data.resultId;
// now send the resultId to your backend and retrieve the result
});
</script>
Integration with return URL
Create the transaction with return URL and scan return URL.
{
"tasks": [
"document_scan"
],
"returnUrl": "https://example.com",
"scanReturnUrl": "https://example.com"
}
Redirect the user to the url
returned in the transaction response.
After the transaction is completed the user is redirected to the returnUrl
. The query parameters trxid
and resultid
are appended to the URL. Use transaction ID in combination with the result ID to retrieve the transaction result.
The scanReturnUrl
is used to redirect the user back to your own status page. This is only used when the QR code is scanned and the user completes the transaction on a mobile device. When no URL is set a default status page is shown.
Events
To get notified when a transaction is completed or other events occurred, you can subscribe to events.
See: Events
Updated about 2 months ago