# 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`

```Text Request headers
Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE
```

```json Request body - JSON
{
    "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](https://developers.cm.com/verification/reference/post_transactions)

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}`

```json Response - JSON
{
    "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.