Consent-based Digital Identity (CDI) | Vlens

Consent-based Digital Identity (CDI) lets users who already have a validated identity in the VLens Network register with your tenant without repeating national ID capture or email OTP. The user explicitly consents via OTP before their identity is linked. CSO and NTRA re-checks run automatically against the identity already on file.

This is a separate product flow from Digital Identity KYC (ID scan + liveness after registration) and from E-Contracting. Pick one registration path per user.

Standard registration vs CDI — 8 user steps vs 2 user steps (phone and liveness)

All CDI endpoints require only the ApiKey header — no bearer token. See Authentication for the full list of API-key-only endpoints.

If CheckExistenceOfEmailOrPhone returns hasCDI: false, use the standard registration flow instead. Do not call StepVerifyCDI or pass useCdi: true for those users.

VLens Network architecture

CDI works because the user’s digital identity already exists in the VLens Network. When a user verified with another tenant joins your app, Vlens matches their selfies against the ID already on file instead of asking them to scan their national ID again.

VLens Network consent-based identity

Concept	Meaning
VLens Network	Shared pool of users who completed full KYC with any Vlens tenant
`hasCDI: true`	User exists in the network — eligible for CDI at your tenant
`useCdi: true`	OTP step records user consent to link their network identity to your organization
`StepVerifyCDI`	Liveness + face match against the on-file ID (no new ID photos)

How CDI works

Only 2 user-facing steps

Phone OTP (consent) and liveness — no email OTP or ID capture.

Up to 70% faster onboarding

Skip repeated document capture for users already verified in the VLens Network.

Same security

CSO and NTRA re-checks run automatically against the ID already on file.

Higher conversions

Fewer steps means more users complete registration.

Step overview

From the user’s perspective, CDI is only two steps: phone OTP (consent) and liveness. Your app handles CheckExistenceOfEmailOrPhone, OTP validation, and StepCreate in the background.

Step 1 — Check existence

Call CheckExistenceOfEmailOrPhone before registration. When the response includes hasCDI: true, the user has a network identity eligible for CDI and can onboard via the CDI flow.

cURL

JavaScript

Python

$ curl -X POST https://api.vlenseg.com/api/DigitalIdentity/CheckExistenceOfEmailOrPhone \
>   -H "ApiKey: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "phoneNumber": "+201234567890",
>     "email": "user@example.com"
>   }'

Response (CDI-eligible user):

1 {
2   "data": {
3     "hasCDI": true
4   },
5   "error_code": null
6 }

Step 2 — Send CDI phone OTP

For CDI onboarding, send the phone OTP with useCdi: true. VLens notifies the user they are consenting to link their network identity to your organization. The OTP confirms phone possession and CDI approval.

cURL

JavaScript

Python

$ curl -X POST https://api.vlenseg.com/api/DigitalIdentity/Register/StepVerifyPhone \
>   -H "ApiKey: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "phoneNumber": "+201234567890",
>     "useCdi": true
>   }'

Step 3 — Validate CDI phone OTP

Validate the OTP using the same endpoint:

cURL

JavaScript

Python

$ curl -X POST https://api.vlenseg.com/api/DigitalIdentity/Register/StepVerifyPhone \
>   -H "ApiKey: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "phoneNumber": "+201234567890",
>     "phoneNumberOtpRequestId": "OTP_REQUEST_ID",
>     "phoneNumberOtp": "123456"
>   }'

Step 4 — CDI liveness and face match

Submit three selfie frames. Vlens checks liveness, matches the selfies against the validated ID already on file, and performs CSO and NTRA re-checks in the background.

Three selfie frames for StepVerifyCDI

Capture rules: All three images must be of the same person and captured within 0.5 seconds of each other. Identical frames or frames taken too far apart will fail liveness.

Image compression

Encode each selfie as base64 JPEG or PNG before sending in scanTransaction. Compress for speed and reliability:

Guideline	Recommendation
Target size	Under 500 KB per image (best performance)
Hard limit	3 MB per image
Resolution	Max 25 megapixels
Format	JPEG recommended for selfies
Encoding	Base64 in JSON body

1 // Example: resize before upload (conceptual)
2 // Use your platform's image library — e.g. react-native-image-resizer, browser canvas, or server-side sharp
3 const compressed = await resizeImage(selfieUri, { maxWidth: 1024, quality: 0.85 });
4 const base64 = await toBase64(compressed);

See Errors for limit-related error codes (5002, 5003, 5006).

cURL

JavaScript

Python

$ curl -X POST https://api.vlenseg.com/api/DigitalIdentity/Register/StepVerifyCDI \
>   -H "ApiKey: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "phoneNumberOtpRequestId": "OTP_REQUEST_ID",
>     "scanTransaction": {
>       "face_1": "BASE64_SELFIE_1",
>       "face_2": "BASE64_SELFIE_2",
>       "face_3": "BASE64_SELFIE_3"
>     }
>   }'

Step 5 — Create the user

If CDI verification succeeds, complete registration with SkipEmail: true:

cURL

JavaScript

Python

$ curl -X POST https://api.vlenseg.com/api/DigitalIdentity/Register/StepCreate \
>   -H "ApiKey: YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "username": "+201234567890",
>     "password": "USER_PASSWORD",
>     "phoneNumberOtpRequestId": "OTP_REQUEST_ID",
>     "geoLocation": { "latitude": 30.0444, "longitude": 31.2357 },
>     "imei": "DEVICE_IMEI",
>     "SkipEmail": true
>   }'