Skip to main content
Versionv1
API docs by Redocly

ID Scan API (1)

Download OpenAPI specification:Download

With ID Scan, you can verify your customer's identity by letting them scan their identity document using a mobile device, like a passport or a driver's license. An advanced OCR engine abstracts data from their document and detects the customer as a living human being via their device's camera.

Transactions

Create or get transactions with identification tasks.

Create a transaction

Create a new transaction. To get notified about status updates, configure a webhook via the /webhooks endpoint. For the event structure see the Webhook Events section.

Authorizations:
JWT
Request Body schema: application/json
required
expiresIn
integer [ 3600 .. 86400 ]
Default: 3600

The time in seconds after which a transaction should expire.

tasks
required
Array of strings (TaskType)
Items Enum: "document_scan" "face_liveness" "face_match"

The tasks to be performed by the user. The face_liveness task can only be performed when the document_scan task is added. For the face_match task both the document_scan task and face_liveness task must be added.

object (Settings)
locale
string (Locale)
Default: "en-US"
Enum: "en-US" "nl-NL" "fr-FR" "it-IT"

The language of the ID Scan process. Currently supports English, Dutch, French.

mobileOnly
boolean
Default: false

When this is set to true, the user must complete the transaction on their mobile device.

returnUrl
string
Default: null

The URL to redirect the user to after the transaction is completed. The trxid, state and resultid will be added as a query parameter. If the URL is not set a default page is shown.

scanReturnUrl
string
Default: null

The URL to redirect the user to in case the transaction is transferred to a mobile device (by scanning the QR code) and the transaction is completed. The trxid and state will be added as a query parameter. If the URL is not set a default page is shown.

Responses

Request samples

Content type
application/json
{
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "state": "pending",
  • "tasks": [
    ],
  • "settings": {
    },
  • "locale": "en-US",
  • "url": "https://example.com/en-us/Dtiu9rE2GE",
  • "mobileOnly": false,
  • "returnUrl": null,
  • "scanReturnUrl": null,
  • "expires": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z"
}

Get all transactions

Get all transactions

Authorizations:
JWT
query Parameters
since
required
string <date-time>
Example: since=2026-01-01T00:00:00Z

Filter transactions created after this date (inclusive). This date may not be older than 1 year.

until
required
string <date-time>
Example: until=2026-02-01T00:00:00Z

Filter transactions created before this date (exclusive).

pageSize
number [ 1 .. 100 ]
Default: 20

The number of items per page

cursor
string

The pointer to the next item in the data set, returned by the previous request.

Responses

Response samples

Content type
application/json
{}

Get transaction details

Retrieve the details of a transaction by its ID.

Authorizations:
JWT
path Parameters
transactionId
required
string

Unique identifier for the transaction

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "state": "pending",
  • "created": "2019-08-24T14:15:22Z",
  • "expires": "2019-08-24T14:15:22Z",
  • "completed": "2019-08-24T14:15:22Z",
  • "tasks": [
    ]
}

Get transaction results

Retrieve the results for a completed transaction.

Authorizations:
JWT
path Parameters
transactionId
required
string <uuid>

A unique identifier for the transaction.

resultId
required
string <uuid>

This result ID can be obtained from the resultId parameter in the iframe event or query parameter resultid in the return url after the user completes the transaction.

query Parameters
includeRawImages
boolean
Default: false
Example: includeRawImages=true

If set to true, a url to download the raw images will be added to the result

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "state": "pending",
  • "tasks": [
    ]
}

Get transaction report

Retrieve an audit report of a completed transaction.

Can specify the type of report using the type query parameter.

Simple reports are always available to be retrieved.

Extended audit reports contain all documents and will be sealed, only retrievable within transaction validity.

Authorizations:
JWT
path Parameters
transactionId
required
string <uuid>

A unique identifier for the transaction.

resultId
required
string <uuid>

This result ID can be obtained from the resultId parameter in the iframe event or query parameter resultid in the return url after the user completes the transaction.

query Parameters
type
string (AuditReportType)
Default: "simple"
Enum: "simple" "extended"

Specify the type of audit report. Defaults to simple.

Simple audit report already exists and can always be retrieved.

Extended audit report can be requested within the ID Scan transaction validity.

Responses

Response samples

Content type
application/json
{
  • "status": 401,
  • "message": "Unauthorized"
}

Webhooks

Manage the webhooks that receive notifications when the state of a transaction or task changes.

Add a webhook

Add a webhook

Authorizations:
JWT
Request Body schema: application/json
required
url
required
string <uri>

The URL must begin with https://.

events
Array of strings (WebhookType)
Default: ["transaction.state.updated","task.state.updated"]
Items Enum: "transaction.state.updated" "task.state.updated"

The subscribed webhook events.

object or null

The custom HTTP headers sent with each request to the webhook URL. The value is null when no headers are set.

Responses

Request samples

Content type
application/json
{
  • "url": "https://example.com",
  • "events": [
    ],
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "https://example.com",
  • "events": [
    ],
  • "headers": {
    },
  • "updated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z"
}

Retrieve all webhooks

Retrieve all webhooks

Authorizations:
JWT

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a webhook

Retrieve a webhook

Authorizations:
JWT
path Parameters
webhookId
required
string <uuid>

A unique identifier for the webhook.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "https://example.com",
  • "events": [
    ],
  • "headers": {
    },
  • "updated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z"
}

Update a webhook

Update a webhook

Authorizations:
JWT
path Parameters
webhookId
required
string <uuid>

A unique identifier for the webhook.

Request Body schema: application/json
required
url
required
string <uri>

The URL must begin with https://.

events
Array of strings (WebhookType)
Default: ["transaction.state.updated","task.state.updated"]
Items Enum: "transaction.state.updated" "task.state.updated"

The subscribed webhook events.

object or null

The custom HTTP headers sent with each request to the webhook URL. The value is null when no headers are set.

Responses

Request samples

Content type
application/json
{
  • "url": "https://example.com",
  • "events": [
    ],
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "https://example.com",
  • "events": [
    ],
  • "headers": {
    },
  • "updated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z"
}

Delete a webhook

Delete a webhook

Authorizations:
JWT
path Parameters
webhookId
required
string <uuid>

A unique identifier for the webhook.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "https://example.com",
  • "events": [
    ],
  • "headers": {
    },
  • "updated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z"
}

Webhook Events

Events sent to your webhook URL when the state of a transaction or task changes. Webhooks are subscribed to via the Webhooks endpoints.

Transaction state updated Webhook

The state of a transaction is updated. For example, from pending to completed. The resultId is only present when the state is completed. This event is sent by default.

Your server implementation should return a 2xx HTTP status code if the event was received successfully. The response body is ignored.

Request Body schema: application/json
required
id
required
string <uuid>

A unique identifier for the event.

created
required
string <date-time>

The date the event was created.

type
required
string

The type of the event.

Value: "transaction.state.updated"
required
object

Responses

Request samples

Content type
application/json
{
  • "id": "b041a287-bc92-4469-801e-ae1a39c08f6e",
  • "type": "transaction.state.updated",
  • "created": "2026-01-01T00:00:00+00:00",
  • "transaction": {
    }
}

Task state updated Webhook

The state of a task is updated. For example, from pending to completed. This event is sent by default.

Your server implementation should return a 2xx HTTP status code if the event was received successfully. The response body is ignored.

Request Body schema: application/json
required
id
required
string <uuid>

A unique identifier for the event.

created
required
string <date-time>

The date the event was created.

type
required
string

The type of the event.

Value: "task.state.updated"
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "id": "c36f5fc9-b412-4aeb-9cbd-bdb6cdca581f",
  • "type": "task.state.updated",
  • "created": "2026-01-01T00:00:00+00:00",
  • "transaction": {
    },
  • "task": {
    }
}

Configuration

Configure how transactions behave, such as which image quality checks are enforced for document scans.

Retrieve the configuration

Retrieve the configuration

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "documentScan": {
    }
}

Update the configuration

Update the configuration. Only the provided values are changed; omitted values keep their current setting.

Authorizations:
JWT
Request Body schema: application/json
required
object (DocumentScanConfig)

Configuration applied to document scan tasks.

object (ImageQualityChecks)

The individual image quality checks. A check is only enforced when set to true; all checks are disabled by default.

glare
boolean
Default: false

Checks for the presence of glare on the document image.

focus
boolean
Default: false

Checks whether the document image is in focus.

resolution
boolean
Default: false

Checks whether the document image has a low resolution.

color
boolean
Default: false

Checks whether the image is colorless, for example a black-and-white scan or photocopy.

perspective
boolean
Default: false

Checks whether the document in the image has perspective distortion.

bounds
boolean
Default: false

Checks whether the document is fully present in the image.

moire
boolean
Default: false

Checks for moiré patterns, which indicate the image is a screen capture instead of a physical document.

portrait
boolean
Default: false

Checks whether the portrait is present on the document.

handwritten
boolean
Default: false

Checks whether the document contains handwritten text in the scanned fields.

brightness
boolean
Default: false

Checks whether the document image is bright enough.

occlusion
boolean
Default: false

Checks whether part of the document is occluded in the image.

Responses

Request samples

Content type
application/json
{
  • "documentScan": {
    }
}

Response samples

Content type
application/json
{
  • "documentScan": {
    }
}