ProductsFRA Services

PII inquiry without OTP

Validate an ID and phone number against national records in a single call
View as Markdown

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 two 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 already have a transactionId

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

Submit ID images

POST /api/FRAServices/PersonallyIdentifiableInformation

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"
  }'
FieldRequiredDescription
idFrontBase64ImageYesBase64-encoded front of the national ID.
idBackBase64ImageYesBase64-encoded back of the national ID.
phoneNumberYesThe phone number being validated.

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 -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"
  }'
FieldRequiredDescription
phoneNumberYesThe phone number being validated.
transactionIdYesThe 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

FieldDescription
data.phoneNumberOwnerOutput.isMatchedWhether the phone number is registered to the ID holder.
data.idFrontOutputExtraction and checks for the front of the card.
data.idBackOutputExtraction and checks for the back of the card.
data.csoOutput.isValidCentral Security Organisation (CSO) validation result.
data.criminalRecordValidationOutputCriminal-record check. null unless the check is enabled for your tenant.
error_code / error_message / error_descriptionsTop-level error envelope. All null on success — note this is null, not 0.

Each of idFrontOutput and idBackOutput carries the same envelope:

FieldDescription
services.Validations.validation_errorsField-level validation failures. Empty when the scan is clean.
services.spoofing.faketrue when the document image looks forged.
services.classification.doc_typeDetected document type — id_front or id_back.
services.livenessNot run in this flow; always null.
services.AMLAML screening — AML_matched plus any matched data records. null when not run.
services.SRCReserved; null.
dataThe 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_descriptionsPer-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.

Next

PII inquiry with OTP

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