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>",
  "externalRef": "<string>",
  "generateDigitString": false,
  "expiryTime": 1296000,
  "locale": "<string>",
  "country": "<string>",
  "sessionLength": 1830,
  "documents": [
    "<string>"
  ],
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "documentNumber": "<string>",
  "personalNumber": "<string>",
  "dateOfExpiry": "2023-12-25",
  "dateOfIssue": "<string>",
  "address": "<string>",
  "successUrl": "<string>",
  "errorUrl": "<string>",
  "unverifiedUrl": "<string>",
  "callbackUrl": "<string>",
  "showInstructions": true,
  "reviewSuccessful": true,
  "reviewFailed": true,
  "questionnaire": "<string>",
  "questionnaireRequired": true,
  "riskAssessmentProfile": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "theme": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "registryCentersCountries": [
    "<string>"
  ],
  "verifyEmail": true,
  "verifyPhone": true,
  "verifyBank": true,
  "verifyBankAccounts": true,
  "verifyBankBalances": true,
  "verifyBankTransactions": true,
  "verifyAddress": true,
  "checkAml": true,
  "checkCriminal": true,
  "checkLiveness": true,
  "checkFaceBlacklist": true,
  "checkDocFaceBlacklist": true,
  "checkPersonBlacklist": true,
  "checkDuplicateFaces": true,
  "checkDuplicateDocFaces": true,
  "checkDuplicatePersonalData": true,
  "checkDriverLicense": true,
  "checkLid": true,
  "checkIpProxy": true,
  "allowBsnMasking": true,
  "nfcRequired": true,
  "autoAmlMonitoring": true,
  "driverLicenseBack": true,
  "faceMatchingThresholdModifier": 123,
  "additionalSteps": {},
  "additionalData": {},
  "utilityBill": true,
  "nfcOptional": true,
  "ageLimit": 123,
  "ageMax": 123
}
'

{
  "authToken": "<string>",
  "scanRef": "<string>",
  "message": "<string>",
  "redirectUrl": "<string>",
  "clientId": "<string>",
  "personScanRef": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "successUrl": "<string>",
  "errorUrl": "<string>",
  "unverifiedUrl": "<string>",
  "callbackUrl": "<string>",
  "locale": "<string>",
  "country": "<string>",
  "expiryTime": 123,
  "sessionLength": 123,
  "documents": [
    "<string>"
  ],
  "allowedDocuments": {},
  "dateOfBirth": "<string>",
  "dateOfExpiry": "<string>",
  "dateOfIssue": "<string>",
  "nationality": "<string>",
  "personalNumber": "<string>",
  "documentNumber": "<string>",
  "sex": "<string>",
  "address": "<string>",
  "showInstructions": true,
  "utilityBill": null,
  "additionalSteps": {},
  "additionalData": {},
  "externalRef": "<string>",
  "questionnaire": "<string>",
  "registryCentersCountries": [
    "<string>"
  ],
  "riskAssessmentProfile": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "theme": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allowBsnMasking": true,
  "verifyBankTransactions": true,
  "checkLid": true,
  "checkDriverLicense": true,
  "verifyAddress": true,
  "checkFaceBlacklist": true,
  "verifyEmail": true,
  "checkPersonBlacklist": true,
  "checkDuplicateDocFaces": true,
  "reviewSuccessful": true,
  "reviewFailed": true,
  "verifyBank": true,
  "autoAmlMonitoring": true,
  "verifyPhone": true,
  "faceMatchingThresholdModifier": 123,
  "checkCriminal": true,
  "checkAml": true,
  "checkDuplicateFaces": true,
  "driverLicenseBack": true,
  "verifyBankAccounts": true,
  "checkDuplicatePersonalData": true,
  "verifyBankBalances": true,
  "nfcRequired": true,
  "checkIpProxy": true,
  "checkDocFaceBlacklist": true,
  "checkLiveness": true,
  "digitString": "<string>"
}

POST

api

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>",
  "externalRef": "<string>",
  "generateDigitString": false,
  "expiryTime": 1296000,
  "locale": "<string>",
  "country": "<string>",
  "sessionLength": 1830,
  "documents": [
    "<string>"
  ],
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "documentNumber": "<string>",
  "personalNumber": "<string>",
  "dateOfExpiry": "2023-12-25",
  "dateOfIssue": "<string>",
  "address": "<string>",
  "successUrl": "<string>",
  "errorUrl": "<string>",
  "unverifiedUrl": "<string>",
  "callbackUrl": "<string>",
  "showInstructions": true,
  "reviewSuccessful": true,
  "reviewFailed": true,
  "questionnaire": "<string>",
  "questionnaireRequired": true,
  "riskAssessmentProfile": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "theme": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "registryCentersCountries": [
    "<string>"
  ],
  "verifyEmail": true,
  "verifyPhone": true,
  "verifyBank": true,
  "verifyBankAccounts": true,
  "verifyBankBalances": true,
  "verifyBankTransactions": true,
  "verifyAddress": true,
  "checkAml": true,
  "checkCriminal": true,
  "checkLiveness": true,
  "checkFaceBlacklist": true,
  "checkDocFaceBlacklist": true,
  "checkPersonBlacklist": true,
  "checkDuplicateFaces": true,
  "checkDuplicateDocFaces": true,
  "checkDuplicatePersonalData": true,
  "checkDriverLicense": true,
  "checkLid": true,
  "checkIpProxy": true,
  "allowBsnMasking": true,
  "nfcRequired": true,
  "autoAmlMonitoring": true,
  "driverLicenseBack": true,
  "faceMatchingThresholdModifier": 123,
  "additionalSteps": {},
  "additionalData": {},
  "utilityBill": true,
  "nfcOptional": true,
  "ageLimit": 123,
  "ageMax": 123
}
'

{
  "authToken": "<string>",
  "scanRef": "<string>",
  "message": "<string>",
  "redirectUrl": "<string>",
  "clientId": "<string>",
  "personScanRef": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "successUrl": "<string>",
  "errorUrl": "<string>",
  "unverifiedUrl": "<string>",
  "callbackUrl": "<string>",
  "locale": "<string>",
  "country": "<string>",
  "expiryTime": 123,
  "sessionLength": 123,
  "documents": [
    "<string>"
  ],
  "allowedDocuments": {},
  "dateOfBirth": "<string>",
  "dateOfExpiry": "<string>",
  "dateOfIssue": "<string>",
  "nationality": "<string>",
  "personalNumber": "<string>",
  "documentNumber": "<string>",
  "sex": "<string>",
  "address": "<string>",
  "showInstructions": true,
  "utilityBill": null,
  "additionalSteps": {},
  "additionalData": {},
  "externalRef": "<string>",
  "questionnaire": "<string>",
  "registryCentersCountries": [
    "<string>"
  ],
  "riskAssessmentProfile": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "theme": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allowBsnMasking": true,
  "verifyBankTransactions": true,
  "checkLid": true,
  "checkDriverLicense": true,
  "verifyAddress": true,
  "checkFaceBlacklist": true,
  "verifyEmail": true,
  "checkPersonBlacklist": true,
  "checkDuplicateDocFaces": true,
  "reviewSuccessful": true,
  "reviewFailed": true,
  "verifyBank": true,
  "autoAmlMonitoring": true,
  "verifyPhone": true,
  "faceMatchingThresholdModifier": 123,
  "checkCriminal": true,
  "checkAml": true,
  "checkDuplicateFaces": true,
  "driverLicenseBack": true,
  "verifyBankAccounts": true,
  "checkDuplicatePersonalData": true,
  "verifyBankBalances": true,
  "nfcRequired": true,
  "checkIpProxy": true,
  "checkDocFaceBlacklist": true,
  "checkLiveness": true,
  "digitString": "<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 returned as digitString.

expiryTime

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

country

string | null

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

sessionLength

integer

Seconds the user has to complete verification once started.

Required range: 60 <= x <= 3600

documents

string[] | null

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

firstName

string | null

Pre-fill client first name. Mismatch triggers SUSPECTED status.

Maximum string length: 100

lastName

string | null

Pre-fill client last name. Mismatch triggers SUSPECTED status.

Maximum string length: 100

dateOfBirth

string<date> | null

Pre-fill client date of birth.

nationality

string | null

Pre-fill client nationality.

documentNumber

string | null

Pre-fill document number.

Maximum string length: 50

personalNumber

string | null

Pre-fill personal/national ID number.

Maximum string length: 50

sex

enum<string> | null

Pre-fill client sex.

Available options:

M,

F

dateOfExpiry

string<date> | null

Pre-fill document expiry date.

dateOfIssue

string | null

Pre-fill document issue date.

address

string | null

Client address for Proof of Address verification.

successUrl

string<uri> | null

Redirect URL on successful verification.

errorUrl

string<uri> | null

Redirect URL on failed verification.

unverifiedUrl

string<uri> | null

Redirect URL when verification result is unverified.

callbackUrl

string<uri> | null

Override webhook callback URL for this session only.

showInstructions

boolean

reviewSuccessful

boolean

Enable manual review for successful verifications.

reviewFailed

boolean

Enable manual review for failed verifications.

questionnaire

string | null

Questionnaire key for this session. Pass null to disable.

questionnaireRequired

boolean

default:true

riskAssessmentProfile

string<uuid> | null

theme

string<uuid> | null

registryCentersCountries

string[] | null

verifyEmail

boolean

verifyPhone

boolean

verifyBank

boolean

verifyBankAccounts

boolean

verifyBankBalances

boolean

verifyBankTransactions

boolean

verifyAddress

boolean

checkAml

boolean

checkCriminal

boolean

checkLiveness

boolean

checkFaceBlacklist

boolean

checkDocFaceBlacklist

boolean

checkPersonBlacklist

boolean

checkDuplicateFaces

boolean

checkDuplicateDocFaces

boolean

checkDuplicatePersonalData

boolean

checkDriverLicense

boolean

checkLid

boolean

checkIpProxy

boolean

allowBsnMasking

boolean

nfcRequired

boolean

autoAmlMonitoring

boolean

driverLicenseBack

boolean

faceMatchingThresholdModifier

number

additionalSteps

object

Request extra document steps. See Additional Steps documentation.

additionalData

object

Data for COMPARE-type additional steps.

utilityBill

boolean | null

nfcOptional

boolean

ageLimit

integer

Minimum required age. Below this triggers SUSPECTED status.

ageMax

integer

Maximum allowed age. Above this triggers SUSPECTED status.

Response

201 - application/json

Token created successfully.

authToken

string

required

read-only

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

scanRef

string

required

read-only

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

tokenType

enum<string>

required

Available options:

IDENTIFICATION,

DOCUMENT

message

string

read-only

redirectUrl

string | null

read-only

Direct URL to the hosted verification flow. Redirect the user here or embed in an iFrame.

clientId

string | null

personScanRef

string | null

firstName

string | null

lastName

string | null

successUrl

string | null

errorUrl

string | null

unverifiedUrl

string | null

callbackUrl

string | null

locale

string | null

country

string | null

expiryTime

integer

Token expiry time in seconds.

sessionLength

integer

documents

string[]

allowedDocuments

object

Show child attributes

dateOfBirth

string | null

dateOfExpiry

string | null

dateOfIssue

string | null

nationality

string | null

personalNumber

string | null

documentNumber

string | null

sex

string | null

address

string | null

showInstructions

boolean

utilityBill

unknown

additionalSteps

object

additionalData

object

externalRef

string | null

questionnaire

string | null

registryCentersCountries

string[]

riskAssessmentProfile

string<uuid> | null

theme

string<uuid> | null

allowBsnMasking

boolean

verifyBankTransactions

boolean

checkLid

boolean

checkDriverLicense

boolean

verifyAddress

boolean

checkFaceBlacklist

boolean

verifyEmail

boolean

checkPersonBlacklist

boolean

checkDuplicateDocFaces

boolean

reviewSuccessful

boolean

reviewFailed

boolean

verifyBank

boolean

autoAmlMonitoring

boolean

verifyPhone

boolean

faceMatchingThresholdModifier

number

checkCriminal

boolean

checkAml

boolean

checkDuplicateFaces

boolean

driverLicenseBack

boolean

verifyBankAccounts

boolean

checkDuplicatePersonalData

boolean

verifyBankBalances

boolean

nfcRequired

boolean

checkIpProxy

boolean

checkDocFaceBlacklist

boolean

checkLiveness

boolean

digitString

string | null

read-only

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

API Reference List identifications

⌘I