Skip to main content
POST
/
api
/
v2
/
token
Generate KYC token
curl --request POST \
  --url https://ivs.idenfy.com/api/v2/token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientId": "<string>",
  "tokenType": "IDENTIFICATION",
  "externalRef": "<string>",
  "generateDigitString": false,
  "lifetime": 1296000,
  "locale": "<string>",
  "sessionLength": 1830,
  "allowedCountries": [
    "<string>"
  ],
  "allowedDocuments": [
    "<string>"
  ],
  "client": {
    "name": "<string>",
    "surname": "<string>",
    "dateOfBirth": "2023-12-25",
    "nationality": "<string>",
    "documentNumber": "<string>",
    "personalNumber": "<string>",
    "sex": "M",
    "dateOfExpiry": "2023-12-25",
    "dateOfIssue": "<string>"
  },
  "urls": {
    "successUrl": "<string>",
    "failUrl": "<string>",
    "unverifiedUrl": "<string>",
    "webhookUrl": "<string>"
  },
  "settings": {
    "verifyEmail": true,
    "verifyPhone": true,
    "verifyBank": true,
    "verifyBankAccounts": true,
    "verifyBankBalances": true,
    "verifyBankTransactions": true,
    "verifyPoaAddress": true,
    "showInstructions": true,
    "reviewFailedVerifications": true,
    "reviewSuccessfulVerifications": true
  },
  "questionnaire": "<string>",
  "questionnaireRequired": true,
  "riskAssessmentProfile": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "address": "<string>"
}
'
{
  "tokenString": "<string>",
  "scanRef": "<string>",
  "isValid": true,
  "tokenType": "IDENTIFICATION",
  "clientId": "<string>",
  "digitString": "<string>",
  "expiration": "2023-11-07T05:31:56Z",
  "isActive": true,
  "externalRef": "<string>",
  "locale": "<string>",
  "sessionLength": 123,
  "sessionUrl": "<string>"
}

Authorizations

​
Authorization
string
header
required

The request must contain basic auth headers where username is API key and password is API secret.
In order for you to start using our API you will need an API key and API secret.
Both can be retrieved by contacting iDenfy's support or iDenfy's sales team.

Body

application/json
​
clientId
string
required

A unique string identifying the client on your side.

Maximum string length: 100
​
tokenType
enum<string>
required
  • IDENTIFICATION — document scan + selfie (default)
  • DOCUMENT — document scan only
Available options:
IDENTIFICATION,
DOCUMENT
​
externalRef
string | null

Optional internal reference. Returned as-is in webhooks.

Maximum string length: 40
​
generateDigitString
boolean
default:false

If true, generates an 8-digit mobile app code.

​
lifetime
integer

Token validity in seconds. Maximum 2,592,000 (30 days).

Required range: 0 <= x <= 2592000
​
locale
string | null

UI language code (e.g. en, de, ko).

Maximum string length: 7
​
sessionLength
integer

Seconds the user has to complete verification once started.

Required range: 60 <= x <= 3600
​
allowedCountries
string[] | null

Restrict accepted document-issuing countries (ISO alpha-2).

​
allowedDocuments
string[] | null

Restrict accepted document types (e.g. PASSPORT, ID_CARD).

​
client
object

Pre-fill known client data. Mismatches trigger SUSPECTED status.

​
urls
object

Override default redirect URLs for this session.

​
settings
object

Session-level feature overrides.

​
questionnaire
string | null

Questionnaire key for this session. Pass null to disable.

​
questionnaireRequired
boolean
default:true
​
riskAssessmentProfile
string<uuid> | null
​
address
string | null

Client address for Proof of Address verification.

Response

201 - application/json

Token created successfully.

​
tokenString
string
required

Pass this to the frontend, SDK, or redirect URL to start verification.

​
scanRef
string
required

Unique session ID. Store this to correlate with webhook results.

​
isValid
boolean
required
​
tokenType
enum<string>
required
Available options:
IDENTIFICATION,
DOCUMENT
​
clientId
string | null
​
digitString
string | null

8-digit mobile code. Only present when generateDigitString was true.

​
expiration
string<date-time>
​
isActive
boolean
deprecated
​
externalRef
string | null
​
locale
string | null
​
sessionLength
integer | null
​
sessionUrl
string | null

Direct URL to the verification session.