PII inquiry without OTP | Vlens

This is the shortest way to run a PII inquiry: one call, no OTP. Use it when your own product has already established that the user controls the phone number — or when you do not need phone-ownership proven by OTP at all.

If you do need that proof, use PII inquiry with OTP instead. The endpoints and the response are identical; the OTP variant just adds two fields and one preceding call.

Both pages call the same endpoints. The only difference is whether you send otpRequestId and otpCode.

Which endpoint to call

I have the ID images

Send the front and back of the national ID as base64.

I have the ID as one PDF

Upload a single PDF with both the front and the back.

I already have a transactionId

Reuse the images from an earlier OCR or Digital Identity capture.

Submit ID images

POST /api/FRAServices/PersonallyIdentifiableInformation

cURL

curl -X POST https://api.vlenseg.com/api/FRAServices/PersonallyIdentifiableInformation \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idFrontBase64Image": "BASE64_ENCODED_IMAGE",
    "idBackBase64Image": "BASE64_ENCODED_IMAGE",
    "phoneNumber": "PHONE_NUMBER"
  }'

Field	Required	Description
`idFrontBase64Image`	Yes	Base64-encoded front of the national ID.
`idBackBase64Image`	Yes	Base64-encoded back of the national ID.
`phoneNumber`	Yes	The phone number being validated.

Submit the ID as one PDF

POST /api/FRAServices/PersonallyIdentifiableInformationPdf

Upload the national ID as one PDF file that contains both the front and the back, instead of two images. The request is multipart/form-data, and the response is the same as for Submit ID images.

cURL

curl -X POST https://api.vlenseg.com/api/FRAServices/PersonallyIdentifiableInformationPdf \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@national-id.pdf;type=application/pdf" \
  -F "phoneNumber=PHONE_NUMBER"

Field	Required	Description
`file`	Yes	One PDF with the front and the back of the national ID.
`phoneNumber`	Yes	The phone number being validated.
`otpRequestId`	No	Only for the OTP variant. Send together with `otpCode`.
`otpCode`	No	Only for the OTP variant. Send together with `otpRequestId`.
`transactionId`	No	An existing transaction ID.
`bypassSpoofingCheck`	No	Defaults to `false`. Send `true` to skip the spoofing check on the ID pages read from the PDF — see below.

The file must be a real PDF — a different file renamed to .pdf is rejected — and no larger than 5 MB.

The front and back are read from the PDF and saved as the usual ID front and ID back steps.

Bypassing the spoofing check

A PDF of a national ID is a scan or a printed copy, so the spoofing check can flag it as a forged document and fail the inquiry with 5005 Spoofed Document. Send bypassSpoofingCheck: true to skip that one check for the pages read from the PDF.

Every other document check still runs — validation, classification, CSO and NTRA are unaffected. Only turn it on for flows where you already trust where the PDF came from.

In the portal, the same upload is available on the Check Phone Ownership page — see Check Phone Ownership.

Submit by transaction

POST /api/FRAServices/CheckIdAndFRAByTransaction

If the ID front and back were already processed in an existing transaction — an OCR or Digital Identity capture, for example — pass that transactionId instead of resending the images.

cURL

curl -X POST https://api.vlenseg.com/api/FRAServices/CheckIdAndFRAByTransaction \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "PHONE_NUMBER",
    "transactionId": "TRANSACTION_ID"
  }'

Field	Required	Description
`phoneNumber`	Yes	The phone number being validated.
`transactionId`	Yes	The `transaction_id` returned by the OCR or Digital Identity capture that processed the ID images.

Response

Both endpoints return the same shape.

{
  "data": {
    "phoneNumberOwnerOutput": {
      "isMatched": true,
      "errorCode": 0,
      "errorKey": null,
      "errorMessage": null
    },
    "idFrontOutput": {
      "services": {
        "Validations": { "validation_errors": [] },
        "spoofing": { "fake": false },
        "classification": { "doc_type": "id_front" },
        "liveness": null,
        "AML": { "AML_matched": false, "data": [] },
        "SRC": null
      },
      "data": {
        "name": "محمد على حسن ابراهيم",
        "first_name": "محمد",
        "last_names": "على حسن ابراهيم",
        "name_english": "Mohamed Ali Hassan Ibrahim",
        "first_name_english": "Mohamed",
        "last_names_english": "Ali Hassan Ibrahim",
        "idNumber": "29001011234567",
        "idKey": "AB1234567",
        "dateOfBirth": "1990-01-01T00:00:00",
        "gender": null,
        "govern": "القاهرة",
        "govern_english": "Cairo",
        "city": "القاهرة",
        "district": "المعادي",
        "address": "١٢ شارع النيل-المعادي القاهرة",
        "address_1": "١٢ شارع النيل",
        "address_2": "المعادي القاهرة",
        "address_english": "12 Nile Street-Maadi Cairo",
        "address_1_english": "12 Nile Street",
        "address_2_english": "Maadi Cairo",
        "client_transaction_id": null,
        "request_id": "00000000-0000-0000-0000-000000000000",
        "transaction_id": "9c1f0e2a-7b3d-4f5a-8c6e-1d2b3a4c5d6e"
      },
      "error_code": null,
      "error_message": null,
      "error_descriptions": null
    },
    "idBackOutput": {
      "services": {
        "Validations": { "validation_errors": [] },
        "spoofing": { "fake": false },
        "classification": { "doc_type": "id_back" },
        "liveness": null,
        "AML": null,
        "SRC": null
      },
      "data": {
        "maritalStatus": "متزوج",
        "marital_status_english": "married",
        "job": "مهندس",
        "job_english": "Engineer",
        "jobTitle": "",
        "job_title_english": null,
        "religion": "مسلم",
        "religion_english": "muslim",
        "husbandName": "",
        "husbandName_english": null,
        "gender": "ذكر",
        "gender_english": "male",
        "releaseDate": "2023-04-01T00:00:00",
        "idExpiry": "2030-04-29T00:00:00",
        "idNumber": "29001011234567",
        "client_transaction_id": null,
        "request_id": "00000000-0000-0000-0000-000000000000",
        "transaction_id": "9c1f0e2a-7b3d-4f5a-8c6e-1d2b3a4c5d6e"
      },
      "error_code": null,
      "error_message": null,
      "error_descriptions": null
    },
    "csoOutput": {
      "isValid": true,
      "errorCode": 0,
      "errorMessage": null
    },
    "criminalRecordValidationOutput": null
  },
  "error_code": null,
  "error_message": null,
  "error_descriptions": null
}

The identity values above are placeholders. A real response returns the actual card holder’s name, address, ID number and date of birth — treat the whole data block as personal data and store it accordingly.

Response fields

Field	Description
`data.phoneNumberOwnerOutput.isMatched`	Whether the phone number is registered to the ID holder.
`data.idFrontOutput`	Extraction and checks for the front of the card.
`data.idBackOutput`	Extraction and checks for the back of the card.
`data.csoOutput.isValid`	Central Security Organisation (CSO) validation result.
`data.criminalRecordValidationOutput`	Criminal-record check. `null` unless the check is enabled for your tenant.
`error_code` / `error_message` / `error_descriptions`	Top-level error envelope. All `null` on success — note this is `null`, not `0`.

Each of idFrontOutput and idBackOutput carries the same envelope:

Field	Description
`services.Validations.validation_errors`	Field-level validation failures. Empty when the scan is clean.
`services.spoofing.fake`	`true` when the document image looks forged.
`services.classification.doc_type`	Detected document type — `id_front` or `id_back`.
`services.liveness`	Not run in this flow; always `null`.
`services.AML`	AML screening — `AML_matched` plus any matched `data` records. `null` when not run.
`services.SRC`	Reserved; `null`.
`data`	The extracted fields. The front carries name, address, ID number, ID key and date of birth; the back carries marital status, job, religion, gender, release date and expiry. Arabic values come with an `_english` counterpart.
`error_code` / `error_message` / `error_descriptions`	Per-document error envelope.

The services block on this endpoint uses a capitalised Validations key. The OCR API returns the same block as lowercase validations. Match the casing to the endpoint you are calling.

Errors

When an ID image fails validation, the call returns HTTP 400 with the code in error_code and the failing fields in data.validation_errors.

`error_code`	Meaning	What to do
`6125`	ID front image failed validation	Recapture the front of the ID and retry.
`6126`	ID back image failed validation	Recapture the back of the ID and retry.

{
  "data": {
    "validation_errors": ["idFrontBase64Image"]
  },
  "error_code": 6125,
  "error_message": "ID Front Image Validation Failed"
}

See Error codes for the full list.

PII inquiry with OTP

Add phone-ownership proof to either of the calls above.

Which endpoint to call

Submit ID images

cURL

Submit the ID as one PDF

cURL

Bypassing the spoofing check

Submit by transaction

cURL

Response

Response fields

Errors

Next