Extract fields

The extractFields document scan setting allows you to define which fields should be included in the response. Keep in mind that the specified field must exist in the scanned document; if it does not, it will not be included in the response.

POST https://api.cm.com/id-scan/v1/transactions

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

{
    "tasks": [
        "document_scan"
    ],
    "settings": {
        "documentScan": {
            "extractFields": [
                "document_number",
                "given_names",
                "surname"
            ]
        }
    }
}

📘
If you add fields to extractFields, the document image url and portrait image file will not be included in the response. To include them, make sure to add document_image and/or portrait as well.

For a full list of all options see the API reference

Once the transaction is completed, only the requested field will be returned if it is present in the provided document.

GET https://api.cm.com/id-scan/v1/transactions/{transactionId}/results/{resultId}

{
    "id": "6844fc0f-103a-4a3a-9794-aecb20a3f30d",
    "state": "completed",
    "tasks": [
        {
            "type": "document_scan",
            "state": "completed",
            "attempts": 1,
            "score": 0.98,
            "result": [
                {
                    "field": "document_number",
                    "validity": "valid",
                    "comparison": "match",
                    "locale": null,
                    "values": [
                        {
                            "source": "mrz",
                            "value": "SPECI2024"
                        },
                        {
                            "source": "visual",
                            "value": "SPECI2024"
                        }
                    ]
                },
                {
                    "field": "given_names",
                    "validity": "not_checked",
                    "comparison": "match",
                    "locale": null,
                    "values": [
                        {
                            "source": "mrz",
                            "value": "WILLEKE LISELOTTE"
                        },
                        {
                            "source": "visual",
                            "value": "WILLEKE LISELOTTE"
                        }
                    ]
                },
                {
                    "field": "given_names",
                    "validity": "not_checked",
                    "comparison": "not_performed",
                    "locale": "nl-NL",
                    "values": [
                        {
                            "source": "visual",
                            "value": "Willeke Liselotte"
                        }
                    ]
                },
                {
                    "field": "surname",
                    "validity": "not_checked",
                    "comparison": "match",
                    "locale": null,
                    "values": [
                        {
                            "source": "mrz",
                            "value": "DE BRUIJN"
                        },
                        {
                            "source": "visual",
                            "value": "DE BRUIJN"
                        }
                    ]
                },
                {
                    "field": "surname",
                    "validity": "not_checked",
                    "comparison": "not_performed",
                    "locale": "nl-NL",
                    "values": [
                        {
                            "source": "visual",
                            "value": "De Bruijn"
                        }
                    ]
                }
            ],
            "files": [
                {
                    "category": "document",
                    "type": "passport",
                    "name": "Netherlands - ePassport (2024)",
                    "score": 0.98,
                    "url": null
                }
            ]
        }
    ]
}

In the response above, the document image URL is null because document_image was not included in extractFields. If it had been specified, the URL would provide a link to download the document image. Similarly, the portrait file is absent from the response because portrait was not added to extractFields. If portrait were included, the response would contain an additional item in the files section with a link to download the portrait image.