KYC Generate token
- API key
- Identity verification credits
Graphical representation of token generation (UML activity)
Sending request
Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/api/v2/token
Request Parameters
Most parameters and features can be set as defaults in the dashboard. While it’s possible to override these settings during token generation, we strongly recommend pre-configuring tokens through the dashboard UI.
Use API parameters only if your flow requires high flexibility or involves complex conditions.
Parameters you can set as defaults in the dashboard
- From Document Data:
documents,country - Session Settings (except
expiryTimeandsessionLength) - All parameters under Advanced Checks
- All parameters under Customization
You can only override features, parameters, and variables available in your environment.
- While
clientIdis the only mandatory parameter, we recommend also providing the client'sfirstNameandlastNamewhen 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"
}
-
Avoid unnecessary credit usage - do not generate new tokens for the same user with same
clientIduntil 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
overallstatus will beSUSPECTEDwith specificmismatchTags: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.
digitStringIf 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.
Request example
{
"clientId": "100000",
"firstName": "John Tom",
"lastName": "Smith",
"successUrl": "https://www.my-company.com/idenfy/success",
"errorUrl": "https://www.my-company.com/idenfy/fail",
"unverifiedUrl": "https://www.my-company.com/idenfy/unverified",
"callbackUrl": "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",
"errorUrl": "https://www.my-company.com/idenfy/fail",
"unverifiedUrl": "https://www.my-company.com/idenfy/unverified",
"callbackUrl": "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"
}
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:
This
Authentication
Request Body
{}