Digital Identity
Digital Identity (DI) verification confirms that your users are who they say they are. Vlens performs OCR on the Egyptian national ID (front + back), runs liveness detection using three face images, and optionally validates against NTRA and CSO authority databases.
This page covers the standard KYC path: ID capture and liveness after standard registration. For users with hasCDI: true, use the separate Consent-based Digital Identity (CDI) product — no steps on this page apply to them.
8 user steps — phone/email OTP, account, ID scan, liveness
2 user steps — phone OTP + liveness, verified at StepCreate
Concepts
Validation vs. verification
The user has not yet completed ID scanning and liveness, or one of the steps failed.
isDigitalIdentityVerified: false
All three capture steps passed, and any required authority checks (NTRA / CSO) also passed.
isDigitalIdentityVerified: true
Whether NTRA and CSO checks are required depends on your tenant configuration. If both are disabled, a user is marked Verified as soon as all three capture steps pass.
Verification flow (standard registration)
After standard Register/StepCreate, the user has a token but isDigitalIdentityVerified is false until the three capture steps below complete. CDI users do not follow this path.
Both standard registration and login give you a user accessToken. The ID and liveness steps apply whenever the user is not yet verified.
You may submit id/front and id/back in any order, but both must complete before liveness.
Prerequisites (standard verification)
The user must complete standard registration before calling the verify/* endpoints below. Register/StepCreate returns a user access token — use it as Authorization: Bearer <token> for all verification calls.
CDI users are already verified at StepCreate and should not call verify/id/front, verify/id/back, or verify/liveness/multi.
See User Profile — Standard registration or the Quick Start for registration steps.
Step 1 — Scan ID front
transaction_id is optional. You may generate your own UUID and send it, or omit it and let the server generate one. Either way, the server always returns transaction_id in the response — save data.transaction_id and pass it to steps 2 and 3.
cURL
JavaScript
Python
data.transaction_id is always returned by the server — save it and pass it to steps 2 and 3.
Fields extracted from the front:
Step 2 — Scan ID back
cURL
JavaScript
Python
Additional fields from the back:
Step 3 — Liveness detection
All three images must be captured within 0.5 seconds of each other. Identical images or images captured too far apart will fail the liveness check. Compress each image to under 500 KB for best performance.
cURL
JavaScript
Python
Success response:
Alternative: link an existing transaction
If your app captures the national ID before the user logs in (using API-key-only calls), you can link the completed transaction to the user after login instead of repeating the capture flow.
This is a native API pattern for mobile or custom integrations where your app calls /verify/* or /v1/ocr/* before the user has a token. It is not used with Iframe Integration (IdentityUserSession/*) or hosted web URLs (GenerateRegisterLink / GenerateLoginLink).
cURL
JavaScript
Python
When to use this: The client performs OCR using only the ApiKey while the user is not yet authenticated. After login, call this endpoint to associate the completed verification with the user’s account — no re-capture needed.
Backend verification services
Each response includes a services object with results from the backend checks:
Delete user account
Authenticated users can permanently delete their VLens account through a three-step flow: initiate deletion, verify OTP, and submit a face match. This removes the user and their digital identity data from your tenant.
Deletion is only available when the user has no signed contracts. If the user has completed any e-contract signing, the API rejects the deletion request.
All steps require ApiKey and a user bearer token.
Step 1 — Initiate deletion
No request body. Returns otpRequestId for the next steps.
cURL
JavaScript
Python
Step 2 — Verify deletion OTP
cURL
JavaScript
Python
If isUserDeleted is true, the account is deleted and no further steps are needed.
Step 3 — Submit face match
Required when OTP verification alone does not complete deletion. Submit a base64-encoded selfie matched against the identity on file.
cURL
JavaScript
Python
Admin — list deletion audits
Admins can query deletion audit records for compliance and support.
Cancel verified digital identity
Revoke a user’s verified digital identity status. After cancellation, isDigitalIdentityVerified returns false and the user must complete the verification flow again before signing e-contracts.
User — cancel own verification
The authenticated user cancels their own verified digital identity. No request body is required.
cURL
JavaScript
Python
Admin — cancel for any user
An admin cancels verified digital identity for a specific user by passing userId in the request body.
cURL
JavaScript
Python
Cancelling verified digital identity is irreversible from the user’s perspective — they must re-verify before signing e-contracts. Use the admin endpoint only for support or compliance workflows.
Admin: retrieve identity data and images
Identity data (OCR fields)
Returns idFront and idBack objects with OCR-extracted national ID fields.
To look up the raw transaction record by transaction_id, see OCR — Lookup transaction.
Verification images
Admins with the Requests permission can retrieve stored identity images for audit or support. Use GetUserDigitalIdentityImages or GetUserDigitalIdentityImagesV2, then download each file with GetStepImage or GetStepImageV2.
The images response includes idFrontImage, idBackImage, livenessImage, and individual liveness face images (livenessFace01Image, livenessFace02Image, livenessFace03Image).