Create an Identification

Creates a new identity verification process. It returns an identID which can be used for SDK or web integration.

Endpoint

POST /api/v1/{customer}/identifications/{transaction-number}/start

Path parameters

Parameter	Type	Required	Description
customer	string	Yes	Your company identifier
transaction-number	string	Yes	Unique transaction identifier

Request

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

Request Parameters

All fields are optional unless otherwise noted. Field names are lowercase.

{
  "firstname": "Erika",
  "lastname": "Mustermann",
  "email": "erika@example.com",
  "mobilephone": "+49175310960",
  "birthday": "1987-05-23",
  "birthplace": "Munich",
  "nationality": "DE",
  "gender": "FEMALE",
  "zipcode": "80469",
  "city": "Munich",
  "street": "High Street",
  "streetnumber": "100",
  "country": "DE",
  "custom1": "any custom string",
  "custom2": "any custom string",
  "custom3": "any custom string",
  "custom4": "any custom string",
  "custom5": "any custom string"
}

note

mobilephone is required only if your account has mandatory SMS OTP authentication enabled. firstname and lastname are always required for QES/eSign workflows.

Response

{
  "id": "TST-FXWF"
}

The id field is the IdentID (format: ABC-DEFGH). Use this to build the verification URL for your user (see API Reference Overview for URL patterns).

---

Identification or TransactionNumber Expiration

Per default, a user has 90 days to verify themselves. For almost all use-cases, this is more than enough time for your customer to complete the KYC process, negating the necessity to issue a new Ident-ID to your user.

The value is configurable. If you want this to be adjusted, please reach out to your Customer Success Manager.

Note: As the transaction number/Ident-ID is unique, it can not be reused once the identification has been deleted.

---

Get Binding Key

Retrieves the Binding Key for an Ident. A 'Binding Key' is a unique token that can be sent by customers when initializing the DocIDV SDK. It can be used for device binding use cases and helps establish a correlation between a user's verified identity and their mobile device on which the identification was performed. It is particularly useful for device authentication and re-authentication scenarios when users change devices.

BindingKey for a completed identification can be fetched via this API endpoint and can then be compared with the one that was originally generated and sent during SDK initialization.

This is an optional feature which needs to be enabled for your account. Please contact your technical contact at IDnow for enabling this feature. For information on sending the BindingKey via the SDK, please see our SDK Guide iOS, Android

GET  /api/v1/{customer}/identifications/{transaction-number}/bindingKey

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

Response

{
  "bindingKey": "binding-key-12345",
  "expiresAt": "2024-03-21T12:00:00Z"
}