KYC Generate token

Requirements

API key
Identity verification credits

Graphical representation of token generation (UML activity)

Sending request

Token generation

Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/api/v2/token

Request Parameters - Main

clientId| Type: String| Required: Yes

Explanation:

A unique string identifying a client. Same clientId is skipping duplicates checking processes.

Constraints:

ASCII characters available
Not null
Max length 100

Default value:

—

firstName| Type: String| Required: No

Explanation:

A name(s) of a client to be identified.

Constraints:

Min length 1
Max length 100
Not digits
Not characters: ~!@#$%^*()_+={}[]|:;",<>/?

Default value:

—

lastName| Type: String| Required: No

Explanation:

A surname(s) of a client to be identified.

Constraints:

Min length 1
Max length 100
Not digits
Not characters: ~!@#$%^*()_+={}[]|:;",<>/?

Default value:

—

successUrl| Type: String| Required: No

Explanation:

A url where a client will be redirected after a successful verification.

Constraints:

Min length 5
Max length 2048
Cannot be used with iframe implementation

Default value:

https://ui.idenfy.com/result?status=success

errorUrl| Type: String| Required: No

Explanation:

A url where a client will be redirected after a failed verification.

Constraints:

Min length 5
Max length 2048
Cannot be used with iframe implementation

Default value:

https://ui.idenfy.com/result?status=fail

unverifiedUrl| Type: String| Required: No

Explanation:

A url where a client will be redirected after a not analyzed verification. E.g. user immediately cancels process.

Constraints:

Min length 5
Max length 2048
Cannot be used with iframe implementation

Default value:

https://ui.idenfy.com/result?status=unverified

locale| Type: String| Required: No

Explanation:

A country code in alpha-2 format. Determines what default language a client will see in verification UI. If not supported locale is used, the default English will be displayed.

Constraints:

See Supported locales

Default value:

showInstructions| Type: Bool| Required: No

Explanation:

Indicates whether instructions should be shown.

Constraints:

—

Default value:

true

expiryTime| Type: Int| Required: No

Explanation:

Length of time in seconds after which a newly generated token will become invalid. More information.

Constraints:

More than 0
Not exceeding 2592000 (30 days)

Default value:

86400

sessionLength| Type: Int| Required: No

Explanation:

Length of time in seconds where a client is given to identify himself in indentification UI. More information.

Constraints:

More than 60
Less than 3600

Default value:

1800

country| Type: String| Required: No

Explanation:

Preselects the default document country for the user. The user cannot change this selection. However, ID verification can still be approved with a document from another country if it is allowed in the account settings.

Constraints:

Any country in alpha-2 code

Default value:

—

documents| Type: List[String]| Required: No

Explanation:

Supported verification documents for the client. The available document types depend on the selected country and the account's allowed document settings. Includes physical and digital ID documents.

Constraints:

Possible values: ID_CARD PASSPORT RESIDENCE_PERMIT DRIVER_LICENSE PAN_CARD AADHAAR VISA NATIONAL_PASSPORT PROVISIONAL_DRIVER_LICENSE OLD_ID_CARD MILITARY_CARD ADDRESS_CARD BANK_ID_SE

Default value:

ID_CARD, PASSPORT

dateOfBirth| Type: String| Required: No

Explanation:

Date of birth of a client.

Constraints:

Format: YYYY-MM-DD

Default value:

—

dateOfExpiry| Type: String| Required: No

Explanation:

Date of expiry of a client document.

Constraints:

Format: YYYY-MM-DD

Default value:

—

dateOfIssue| Type: String| Required: No

Explanation:

Date of issue of a client document.

Constraints:

Format: YYYY-MM-DD

Default value:

—

nationality| Type: String| Required: No

Explanation:

Nationality of a client.

Constraints:

Any country in alpha-2 code

Default value:

—

personalNumber| Type: String| Required: No

Explanation:

Personal/national number of a client.

Constraints:

ASCII characters available
Min length 1
Max length 50

Default value:

—

documentNumber| Type: String| Required: No

Explanation:

Number of a client document.

Constraints:

ASCII characters available
Min length 1
Max length 50

Default value:

—

sex| Type: String| Required: No

Explanation:

Gender of a client.

Constraints:

Values: -M -F

Default value:

—

generateDigitString| Type: Bool| Required: No

Explanation:

Specify whether to generate an 8-digit string identifying the token that can be used in our mobile application.

Constraints:

If true, contract must allow to generate digit string
If true, expiryTime must not exceed maximum expiry time of digit string

Default value:

false

address| Type: String| Required: No

Explanation:

Client address provided by partner.

Constraints:

Max length 255

Default value:

—

tokenType| Type: String| Required: No

Explanation:

Determines, what sort of processing the client should go through. -DOCUMENT - verification process consists of document capturing step only; -IDENTIFICATION - verification process consists of document and selfie steps;

Constraints:

Values: -DOCUMENT -IDENTIFICATION

Default value:

IDENTIFICATION

externalRef| Type: String| Required: No

Explanation:

An unique string for external reference to link the client to you and the iDenfy system better.

Constraints:

ASCII characters available
Length ≤ 40

Default value:

—

additionalSteps| Type: String| Required: No

Explanation:

Require your users to upload additional photos in their verification process. Please refer to this manual page for detailed information about additional steps.

Constraints:

Valid JSON. Can't be used together with utilityBill

Default value:

—

additionalData| Type: String| Required: No

Explanation:

Additional data provided alongside any additionalSteps, for example - Social Security Number in UTILITY_BILL

Constraints:

Must be used with additionalSteps

Default value:

—

callbackUrl| Type: String| Required: No

Explanation:

A webhook endpoint for the session, overrides notification endpoints like ID_VERIFICATION /MANUAL_FINISHED / AUTO_FINISHED, etc. In order to override webhook notification must be set.

Constraints:

Must be HTTPS URL, requires permissions enabled (contact tech support via dashboard if the request is refused).

Default value:

—

questionnaire| Type: String| Required: No

Explanation:

Questionnaire must be created in order to add its key

Constraints:

Questionnaire key must be provided

Default value:

—

riskAssessmentProfile| Type: String| Required: No

Explanation:

Risk Assessment profile must be created in order to add its id

Constraints:

Risk Assessment profile id must be provided

Default value:

—

Parameters - Custom Token Settings

You can customize your token generation request by including optional parameters like liveness detection, instructions.

Defaults depend on your environment’s configuration. Some options require prior activation through your contract. Once enabled, they apply to all tokens unless overridden in the request.

Use these settings to tailor the service to your specific use cases. However, some values are already optimized—adjust with caution.

checkLiveness| Type: Bool

Explanation:

Indicates whether to add liveness face detection to the generated token or not.

driverLicenseBack| Type: Bool

Explanation:

An option to allow uploading back side of the driver's license in the verification session.

autoAmlMonitoring| Type: Bool

Explanation:

An option to automatically add the verified person to AML monitoring.

checkIpProxy| Type: Bool

Explanation:

An option to check if an IP proxy was used for verification.

checkFaceBlacklist| Type: Bool

Explanation:

Check if this verification's selfie is added to your environment's face blacklist. If there will be any matches, the verification will be suspected

checkDocFaceBlacklist| Type: Bool

Explanation:

Check if this verification's document photo is added to your environment's face blacklist.

checkDuplicateFaces| Type: Bool

Explanation:

Check if there is already a verification of the same person's face in your environment.

checkDuplicateDocFaces| Type: Bool

Explanation:

Check if there is already a verification of the same person's document face in your environment.

nfcRequired| Type: Bool

Explanation:

Option to require NFC as a method for verification.

levenshteinTextMatchRatio| Type: Float/Integer

Explanation:

This setting adjusts the Levenshtein matching ratio that is used for string comparison and searches for inconsitencies between them. The technology behind this method can be found on the web, for example - here. The default setting is already in tested and optimal value - 0.8

levenshteinMrzMatchRatio| Type: Float/Integer

Explanation:

This setting adjusts the Levenshtein matching ratio for document's MRZ. The technology principle is the same as levenshteinTextMatchRatio but used separately for MRZ. The default setting is already in tested and optimal value - 0.7

Only `clientId` provided

Request example

{
  "clientId": "100000"
}

Response example

{
  "message": "Token created successfully",
  "authToken": "LEWCd6xHTW2auHrst9MEqZN8tUgKsUQ8hSMNYoLI",
  "scanRef": "9b11acb2-8c27-11e9-9758-309c231b1bac",
  "clientId": "100000",
  "personScanRef": "100000",
  "firstName": null,
  "lastName": null,
  "successUrl": null,
  "errorUrl": null,
  "locale": "en",
  "showInstructions": true,
  "country": null,
  "expiryTime": 3600,
  "sessionLength": 300,
  "documents": ["ID_CARD", "PASSPORT", "RESIDENCE_PERMIT", "DRIVER_LICENSE"],
  "allowedDocuments": {
    "ALL": ["ID_CARD", "PASSPORT", "RESIDENCE_PERMIT", "DRIVER_LICENSE"]
  },
  "dateOfBirth": null,
  "dateOfExpiry": null,
  "dateOfIssue": null,
  "nationality": null,
  "personalNumber": null,
  "documentNumber": null,
  "sex": null,
  "digitString": "4823657",
  "address": null,
  "tokenType": "IDENTIFICATION",
  "externalRef": null,
  "utilityBill": false,
  "riskAssessmentProfile": null,
  "additionalSteps": null,
  "additionalData": null
}

Multiple fields provided

Request example

{
  "clientId": "100000",
  "firstName": "John Tom",
  "lastName": "Smith",
  "successUrl": "[https://www.my-company.com/idenfy/success](https://www.my-company.com/idenfy/success)",
  "errorUrl": "[https://www.my-company.com/idenfy/fail](https://www.my-company.com/idenfy/fail)",
  "unverifiedUrl": "[https://www.my-company.com/idenfy/unverified](https://www.my-company.com/idenfy/unverified)",
  "callbackUrl": "[https://mywebsite.com/idenfy/webhookendpoint](https://mywebsite.com/idenfy/webhookendpoint)",
  "locale": "en",
  "showInstructions": true,
  "expiryTime": 600,
  "sessionLength": 600,
  "country": "lt",
  "documents": ["PASSPORT"],
  "dateOfBirth": "1990-12-20",
  "dateOfExpiry": "1990-12-20",
  "dateOfIssue": "1990-12-20",
  "nationality": "lt",
  "personalNumber": "123456789",
  "documentNumber": "123456",
  "sex": "M",
  "address": "Address",
  "tokenType": "IDENTIFICATION",
  "externalRef": "reference",
  "utilityBill": false,
  "additionalSteps": null,
  "additionalData": null,
  "questionnaire": "c8QgVx5xzspjVnQ4nJ7MCf"
}

Response example

{
  "message": "Token created successfully",
  "authToken": "pgYQX0z2T8mtcpNj9I20uWVCLKNuG0vgr12f0wAC",
  "scanRef": "ec6a7108-8c26-11e9-9758-309c231b1bac",
  "clientId": "100000",
  "firstName": "JOHN TOM",
  "lastName": "SMITH",
  "successUrl": "[https://www.my-company.com/idenfy/success](https://www.my-company.com/idenfy/success)",
  "errorUrl": "[https://www.my-company.com/idenfy/fail](https://www.my-company.com/idenfy/fail)",
  "unverifiedUrl": "[https://www.my-company.com/idenfy/unverified](https://www.my-company.com/idenfy/unverified)",
  "callbackUrl": "[https://mywebsite.com/idenfy/webhookendpoint](https://mywebsite.com/idenfy/webhookendpoint)",
  "locale": "en",
  "showInstructions": true,
  "country": "lt",
  "expiryTime": 600,
  "sessionLength": 600,
  "documents": ["PASSPORT"],
  "allowedDocuments": {
    "ALL": ["ID_CARD", "PASSPORT", "DRIVER_LICENSE", "RESIDENCE_PERMIT"]
  },
  "dateOfBirth": "1990-12-20",
  "dateOfExpiry": "1990-12-20",
  "dateOfIssue": "1990-12-20",
  "nationality": "lt",
  "personalNumber": "123456789",
  "documentNumber": "123456",
  "sex": "M",
  "digitString": "4823657",
  "address": "Address",
  "tokenType": "IDENTIFICATION",
  "externalRef": "reference",
  "questionnaire": null,
  "utilityBill": false,
  "additionalSteps": null,
  "additionalData": null,
  "riskAssessmentProfile": "e8cadb52-d429-4dc2-b788-99dfbbe8a4ab",
  "callbackUrl": "[https://mywebsite.com/idenfy/webhookendpoint](https://mywebsite.com/idenfy/webhookendpoint)"
}

The response JSON mirrors the fields provided during token generation, includes default values for any unspecified optional fields, and contains the following additional response-specific fields:

message

Explanation:

A message for a developer about the status of generated token. Constraints: Max length 100

Example:
Token created successfully

authToken

Explanation:

A unique string for verification process (will be passed as a url parameter when redirecting a client to verification platform). Constraints: Length ≤ 40

Example:
3FA5TFPA2ZE3LMPGGS1EGOJNJE

scanRef

Explanation:

A unique string identifying a client verification on iDenfy’s side. Constraints: Length ≤ 40

Example:
d2714c8a-ec05-11e8-834f-067891e3383a

clientId

Explanation:

A unique string identifying a client on your company's side. (The same value when requesting to generate a token)

Example:
5F7E4FR14

digitString

Explanation:

A unique string identifying the token that can be used by the client in our mobile application. Will be null if generateDigitString is not true. Constraints: Length = 8

Example:
89567412

Authentication

Request Body

{}

Response

for best outcome

While clientId is the only mandatory parameter, we recommend also providing the client's firstName and lastName when possible. This enables our system to perform an Information Comparison, where we cross-check the data you provide against the information extracted from the ID document.

Note: The more data you provide, the more thorough the check becomes. This increases verification accuracy but also means that typos or discrepancies between the data in your system and the data on the document can cause the verification to be flagged. For the highest success rate, ensure the data you pass is accurate.

{
  "clientId": "100000",
  "firstName": "John Tom",
  "lastName": "Smith"
}

Be aware

Avoid unnecessary credit usage - do not generate new tokens for the same user with same clientId until you have received the final results via the webhooks.
If provided information is incorrect or different from document information, cross-matching will be triggered, and verification overall status will be SUSPECTED with specific mismatchTags: NAME, SURNAME, DATE_OF_BIRTH
Malformation in JSON or API key/secret issues will trigger a standard iDenfy API error response, detailed at iDenfy's error messages.

digitString

If you're generating an 8 digit mobile code, please keep in mind that for security purposes, expiryTime cannot be longer than generateDigitString default value(must be the value as default expiryTime). If you need to increase the maximum default value of the mobile code expiration, please contact sales@idenfy.com or our technical support team via dashboard.

Graphical representation of token generation (UML activity)​

Sending request​

Request Parameters - Main​

Parameters - Custom Token Settings​

Only clientId provided​

Request example​

Response example​

Multiple fields provided​

Request example​

Response example​

Authentication

Required Parameters

Request Body

Response

Graphical representation of token generation (UML activity)

Sending request

Request Parameters - Main

Parameters - Custom Token Settings

Only `clientId` provided

Request example

Response example

Multiple fields provided

Request example

Response example