Skip to main content
Versionv1
API docs by Redocly

Identity Hub (1.0.0)

Download OpenAPI specification:Download

Identity Hub lets you verify the identity of your end-users through a single hosted flow, abstracting away the underlying identification methods (such as iDIN and ID Scan). The set of available methods depends on the account's contract.

Create a transaction, redirect the end-user to the returned hosted URL, and retrieve the verified result once the flow is completed. Specify the personal data fields (e.g. name, birthdate, address) to collect via requestedFields; the collected values are returned once the transaction is successful.

Typical use-cases include KYC onboarding, age verification, and confirming a user's identity before granting access to sensitive services.

Transaction

Create and retrieve transactions

Create transaction

Create a new transaction. The response contains the transaction id and a hosted URL that the end-user can be redirected to in order to complete the transaction.

Authorizations:
JWT
Request Body schema: application/json
required
returnUrl
required
string <url> <= 255 characters

The URL the end-user will be redirected to after completing the transaction. The transactionId and state are appended as query parameters, e.g. https://example.com/transaction/return?transactionId=b3e1c8f2-3a9d-4f4f-8b1a-1c2d3e4f5a6b&state=success.

callbackUrl
string <url> <= 255 characters

Updates regarding the transaction will be sent to the callback URL. It must begin with https://. See the Transaction state callback for the payload that is sent.

locale
string (Locale)
Default: "en-US"
Enum: "nl-NL" "en-US" "fr-FR" "de-DE" "hu-HU" "it-IT" "ja-JP" "pl-PL" "pt-PT" "ro-RO" "sk-SK" "es-ES"

Supported locales for the hosted transaction UI:

  • nl-NL - Dutch
  • en-US - English
  • fr-FR - French
  • de-DE - German
  • hu-HU - Hungarian
  • it-IT - Italian
  • ja-JP - Japanese
  • pl-PL - Polish
  • pt-PT - Portuguese
  • ro-RO - Romanian
  • sk-SK - Slovakian
  • es-ES - Spanish
requestedFields
required
Array of strings (RequestedField) non-empty
Items Enum: "givenName" "middleName" "familyName" "gender" "birthdate" "email" "phoneNumber" "address" "nationality" "identifier"

The list of fields to collect from the end-user during the transaction. The collected values are returned via the data property once the transaction is successful.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get transaction

Retrieve a transaction by its id. When the transaction is successful, the data and unavailableFields properties are included in the response. rawData will be included when available.

Authorizations:
JWT
path Parameters
id
required
string <uuid>
Examples: b3e1c8f2-3a9d-4f4f-8b1a-1c2d3e4f5a6b

The UUID of the transaction.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "b3e1c8f2-3a9d-4f4f-8b1a-1c2d3e4f5a6b",
  • "state": "created",
  • "method": null,
  • "methodType": null
}

Callbacks

Updates sent to the callbackUrl provided when creating a transaction

Transaction state Webhook

Sent to the callbackUrl provided when creating the transaction, every time the state of the transaction changes. No callbacks are sent when no callbackUrl was provided. Use it as a trigger to retrieve the latest details with the Get transaction endpoint.

The request is signed so you can verify its authenticity and integrity. The signature is calculated using HMAC-SHA256, with the request body as the message and the client secret as the secret key, and is sent in the Authorization header. Repeat this calculation on the received body and compare the result with the header value.

Respond with a status code in the 2xx range; the response body is ignored. When your endpoint responds with a 5xx status code, the callback is retried several times.

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

Unique identifier of the event.

type
required
string (EventType)
Value: "transaction.state"

Supported event types:

  • transaction.state - The state of the transaction has been updated.
created
required
string <date-time>

The time the event was created, in ISO 8601 format.

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "58128784-9e8d-4424-a89d-08bfe273381c",
  • "type": "transaction.state",
  • "created": "2026-01-01T00:00:00+00:00",
  • "transaction": {
    }
}