Guides

Create transaction

Suggest Edits

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

TypeDescription
document_scanUpload or take a photo of the front and back side of an ID document.
face_livenessLiveness check using the camera.
face_matchCompares 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,
            "validateFields": [
                "personal_number"
            ]
        }
    }
}
PropertyTypeDescription
allowedExpirationintegerIncrease or decrease the allowed expiration of the document based on its expiry date. For more information, see document expiration.
redactFieldsarrayThe fields to be masked/blurred on the downloaded ID document. For more information, see redact fields.
captureSourcesarraySpecify how you would like the user to upload their document, allowed options arefile and camera. For more information, see allowed capture sources.
levelstringSet the level of the authenticity check performed on the ID document. Either basic or advanced. If not specified, will conduct an advanced scan.
minimumAgeintegerSet 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.
maximumAgeintegerSet 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.
requireBothSidesbooleanIf 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.
validateFieldsarraySpecify 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 5 months ago

What’s Next