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 passive liveness detection using three face images, and optionally validates against NTRA and CSO authority databases.

Concepts

Validation vs. Verification

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.

The transaction

All three capture steps share a single transaction_id. The ID is returned in the first step’s response and must be passed to every subsequent step.

You may submit id/front or id/back in any order, but both must complete before liveness.

Prerequisites

The user must be registered before calling the verification endpoints. Registration returns a user access token — use it as Authorization: Bearer <token> for all verification calls.

See the Quick Start for the registration steps.

Step 1 — Scan ID front

$
curl -X POST https://api.vlenseg.com/api/DigitalIdentity/verify/id/front \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "Authorization: Bearer USER_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "image": "BASE64_ID_FRONT_IMAGE",
>
    "getExtractedData": true
>
  }'

Save data.idFrontData.transaction_id — you need it for steps 2 and 3.

Fields extracted from the front:

Step 2 — Scan ID back

$
curl -X POST https://api.vlenseg.com/api/DigitalIdentity/verify/id/back \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "Authorization: Bearer USER_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "image": "BASE64_ID_BACK_IMAGE",
>
    "transaction_id": "TRANSACTION_ID"
>
  }'

Additional fields from the back:

Step 3 — Liveness detection

$
curl -X POST https://api.vlenseg.com/api/DigitalIdentity/verify/liveness/multi \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "Authorization: Bearer USER_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "image": "BASE64_ID_FRONT",
>
    "face_1": "BASE64_FACE_1",
>
    "face_2": "BASE64_FACE_2",
>
    "face_3": "BASE64_FACE_3",
>
    "transaction_id": "TRANSACTION_ID",
>
    "getExtractedData": true
>
  }'

Success response:

1
{
2
  "data": {
3
    "isVerificationProcessCompleted": true,
4
    "isDigitalIdentityVerified": true,
5
    "user": { "idNumber": "29901234567890" }
6
  },
7
  "services": {
8
    "liveness": true,
9
    "spoofing": { "fake": false },
10
    "SRC": { "isValid": true },
11
    "AML": { "AML_matched": false }
12
  },
13
  "error_code": null
14
}

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.

$
curl -X POST https://api.vlenseg.com/api/DigitalIdentity/LinkUserWithExistingTransaction \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "Authorization: Bearer USER_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "transactionId": "EXISTING_TRANSACTION_ID",
>
    "getExtractedData": true
>
  }'

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:

Admin: retrieve verification images

Admins with the Requests permission can retrieve stored identity images for audit or support:

$
# Step 1 — Get file names
$
curl "https://api.vlenseg.com/api/DigitalIdentity/GetUserDigitalIdentityImages\
>
?emailOrPhoneNumber=%2B201234567890" \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "Authorization: Bearer ADMIN_TOKEN"
$
$
# Step 2 — Download a specific image as base64
$
curl "https://api.vlenseg.com/api/DigitalIdentity/GetStepImage\
>
?TransactionId=TX_ID&FileName=FILENAME" \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "Authorization: Bearer ADMIN_TOKEN"