Create Verification Session

POST https://ivs.idenfy.com/api/v2/token
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

Common Examples

Start with these, then customize using the full parameter reference below.

Minimal
With data matching
Restricted countries + docs
Full example

The only required field is clientId:

{
  "clientId": "user-123"
}

Everything else uses your Dashboard defaults.

Provide user data to cross-check against the document. Mismatches trigger SUSPECTED status:

{
  "clientId": "user-123",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15"
}

Lock verification to specific countries and document types:

{
  "clientId": "user-123",
  "firstName": "John",
  "lastName": "Doe",
  "country": ["US", "GB", "DE"],
  "documents": ["PASSPORT", "ID_CARD"]
}

All commonly used fields:

{
  "clientId": "user-123",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "country": "US",
  "documents": ["PASSPORT", "ID_CARD"],
  "locale": "en",
  "expiryTime": 3600,
  "sessionLength": 600,
  "successUrl": "https://yourapp.com/verified",
  "errorUrl": "https://yourapp.com/failed",
  "callbackUrl": "https://yourapp.com/webhook"
}

Code Examples

curl -X POST https://ivs.idenfy.com/api/v2/token \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "user-123", "firstName": "John", "lastName": "Doe"}'

Response

{
  "message": "Token created successfully",
  "authToken": "pgYQX0z2T8mtcpNj9I20uWVCLKNuG0vgr12f0wAC",
  "scanRef": "ec6a7108-8c26-11e9-9758-309c231b1bac",
  "clientId": "user-123",
  "firstName": "JOHN",
  "lastName": "DOE",
  "redirectUrl": "https://ivs.idenfy.com/api/v2/redirect?authToken=pgYQX0z2T8...",
  "digitString": null,
  "expiryTime": 3600,
  "sessionLength": 600
}

Key response fields:

Field	Use it for
`authToken`	Pass to iFrame, SDK, or redirect URL
`redirectUrl`	Redirect user here for hosted verification
`scanRef`	Unique verification ID — store this in your database
`digitString`	8-digit code for mobile app (only if `generateDigitString: true`)

What to Do Next

After generating the token, send your user to verification:

Method	Code	When to use
Redirect	`window.location.href = token.redirectUrl`	Simplest. User leaves your site.
iFrame	`<iframe src="https://ui.idenfy.com/?authToken=TOKEN">`	Embedded. User stays on your site. Details →
Android SDK	`IdenfyController.startIdentification(activity, token.authToken)`	Native Android. Details →
iOS SDK	`IdenfyController.shared.startIdentification(authToken: token.authToken)`	Native iOS. Details →

Then set up webhooks to receive the result.

All Parameters

Most of these can be set as defaults in your Dashboard. Only pass parameters via API when you need per-session customization.

Personal Data `optional`

Parameter	Type	Description
`clientId`	`string` required	Unique client identifier. ASCII, max 100 chars.
`firstName`	`string`	Client name. Letters only, max 100, auto-uppercased.
`lastName`	`string`	Client surname. Letters only, max 100, auto-uppercased.
`dateOfBirth`	`string`	Format: `YYYY-MM-DD`.
`sex`	`string`	`M` or `F`.
`nationality`	`string`	ISO 3166-1 alpha-2 (e.g., `US`, `DE`).
`address`	`string`	Max 255 chars. Used for Proof of Address verification.
`externalRef`	`string`	Your internal reference. ASCII, max 40 chars.

Document Data `optional`

Parameter	Type	Description
`country`	`string` or `string[]`	ISO alpha-2. Restricts accepted countries. Default: all.
`documents`	`string[]`	Accepted document types: `PASSPORT`, `ID_CARD`, `DRIVER_LICENSE`, `RESIDENCE_PERMIT`, etc.
`documentNumber`	`string`	Expected document number. Triggers mismatch check.
`personalNumber`	`string`	Expected personal/national code.
`dateOfExpiry`	`string`	Format: `YYYY-MM-DD`.
`dateOfIssue`	`string`	Format: `YYYY-MM-DD`.

The country parameter sets the expected document country but does not limit the document selection options shown to your user. To restrict which document types and countries are available for selection, adjust the allowed documents settings — see Document Configuration.If you need an option to deny users based on country, contact tech support via the portal.

Session Settings `optional`

Parameter	Type	Default	Description
`successUrl`	`string`	Dashboard setting	Redirect after approval. HTTPS, max 2048.
`errorUrl`	`string`	Dashboard setting	Redirect after denial.
`unverifiedUrl`	`string`	Dashboard setting	Redirect if user cancels.
`callbackUrl`	`string`	—	Override webhook URL for this session.
`locale`	`string`	`en`	UI language. ISO alpha-2.
`expiryTime`	`integer`	`86400`	Token validity (seconds). Max: 2,592,000 (30 days).
`sessionLength`	`integer`	`1800`	Time to complete once started (seconds). Max: 3,600.
`tokenType`	`string`	`IDENTIFICATION`	`IDENTIFICATION` = doc + selfie. `DOCUMENT` = doc only.
`showInstructions`	`boolean`	Dashboard	Show instruction screens before capture.
`generateDigitString`	`boolean`	`false`	Generate 8-digit mobile code.

Verification Features `optional`

Parameter	Type	Description
`verifyEmail`	`boolean`	Add email verification step.
`verifyPhone`	`boolean`	Add phone verification step (SMS).
`verifyAddress`	`boolean`	Enable address/PoA verification.
`verifyBank`	`boolean`	Enable bank verification.
`nfcRequired`	`boolean`	Require NFC chip reading (high assurance).
`nfcOptional`	`boolean`	Optional NFC scan.
`ageLimit`	`integer`	Minimum age. Below = `SUSPECTED`.
`ageMax`	`integer`	Maximum age. Above = `SUSPECTED`.
`driverLicenseBack`	`boolean`	Require both sides of driver’s license.

Security & Fraud Detection `optional`

Parameter	Type	Description
`checkLiveness`	`boolean`	Active 3D liveness (head movement).
`idLiveFaceValidation`	`boolean`	Passive face liveness (detects screens/photos).
`idLiveDocumentValidation`	`boolean`	Passive document liveness (detects copies).
`checkAml`	`boolean`	Auto-add to AML monitoring.
`checkIpProxy`	`boolean`	Detect VPN/proxy usage.
`checkFaceBlacklist`	`boolean`	Check selfie against blacklist.
`checkDocFaceBlacklist`	`boolean`	Check document face against blacklist.
`checkDuplicateFaces`	`boolean`	Detect same face in previous verifications.
`checkDuplicateDocFaces`	`boolean`	Detect same document face.
`checkDuplicatePersonalData`	`boolean`	Detect same personal data.
`checkBlurAndGlare`	`boolean`	Image quality checks.
`autoFaceMatching`	`boolean`	Disabling this turns off all face-related checks.

Customization `optional`

Parameter	Type	Description
`additionalSteps`	`object`	Request extra documents. See Additional Steps →
`additionalData`	`object`	Data for COMPARE-type additional steps.
`utilityBill`	`boolean`	Enable utility bill verification.
`questionnaire`	`string`	Questionnaire key. `null` to disable.
`riskAssessmentProfile`	`integer`	Risk Assessment profile ID.
`reviewFailed`	`boolean`	Trigger manual review for failed sessions.
`reviewSuccessful`	`boolean`	Trigger manual review for successful sessions.

Don’t waste credits. Don’t create new sessions for the same clientId until you receive the final webhook result. Each session consumes a verification credit.

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Fraud Prevention

Bank Verification

Going Live

Reference

Common Examples

Code Examples

Response

What to Do Next

All Parameters

Personal Data `optional`

Document Data `optional`

Session Settings `optional`

Verification Features `optional`

Security & Fraud Detection `optional`

Customization `optional`

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Fraud Prevention

Bank Verification

Going Live

Reference

​Common Examples

​Code Examples

​Response

​What to Do Next

​All Parameters

​Personal Data optional

​Document Data optional

​Session Settings optional

​Verification Features optional

​Security & Fraud Detection optional

​Customization optional

Common Examples

Code Examples

Response

What to Do Next

All Parameters

Personal Data `optional`

Document Data `optional`

Session Settings `optional`

Verification Features `optional`

Security & Fraud Detection `optional`

Customization `optional`