PII inquiry with OTP | Vlens

This is the same PII inquiry as PII inquiry without OTP, with one extra call in front of it: you send an OTP to the phone number, the user reads it back, and you pass it along with the inquiry. That proves the person in front of you actually controls the number being validated.

Use this variant when phone-ownership matters — onboarding a new customer, or any flow where the phone number has not already been verified elsewhere in your product.

Same endpoints, same response. The OTP variant adds one preceding call and two request fields: otpRequestId and otpCode.

The flow

Request an OTP

Call POST /api/FRAServices/RequestOtpForPii with the phone number. Vlens sends the code and returns an otpRequestId.

Collect the code from the user

The user reads the SMS and types the code into your app.

Submit the PII inquiry

Call any of the inquiry endpoints with the phone number, the ID (images, one PDF or transactionId), plus the otpRequestId from step 1 and the otpCode the user typed.

otpRequestId and otpCode travel together. Send both, or send neither and use the no-OTP variant. Sending only one is rejected.

Step 1 — Request the OTP

POST /api/FRAServices/RequestOtpForPii

cURL

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

Field	Required	Description
`phoneNumber`	Yes	The phone number to send the code to. This must be the same number you validate in step 2.
`smsProviders`	No	Which SMS provider to send the code through. Leave it out, or send `0`, and the tenant’s default provider is used.

smsProviders takes the same values as the rest of the API: 1 Infobip, 2 Vodafone, 3 Cequens, 4 Victory Link, 5 BroadNet, 6 Ezagel, 7 Orange. Existing callers that omit the field are unaffected.

{
  "data": {
    "otpRequestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "error_code": 0,
  "error_message": null
}

Keep the otpRequestId — you echo it back on the inquiry call.

Step 2 — Submit the inquiry

Pick the endpoint that matches what you hold.

With 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",
    "otpRequestId": "OTP_REQUEST_ID",
    "otpCode": 123456
  }'

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.
`otpRequestId`	Yes, for this variant	The value returned in step 1.
`otpCode`	Yes, for this variant	The code the user received, as a JSON number — `123456`, not `"123456"`.

With the ID as one PDF

POST /api/FRAServices/PersonallyIdentifiableInformationPdf

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" \
  -F "otpRequestId=OTP_REQUEST_ID" \
  -F "otpCode=123456"

Field	Required	Description
`file`	Yes	One PDF with the front and the back of the national ID — a real PDF, at most 5 MB.
`phoneNumber`	Yes	The phone number being validated.
`otpRequestId`	Yes, for this variant	The value returned in step 1.
`otpCode`	Yes, for this variant	The code the user received. Sent as a form field.

See Submit the ID as one PDF for the optional fields.

With an existing transaction

POST /api/FRAServices/CheckIdAndFRAByTransaction

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",
    "otpRequestId": "OTP_REQUEST_ID",
    "otpCode": 123456
  }'

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.
`otpRequestId`	Yes, for this variant	The value returned in step 1.
`otpCode`	Yes, for this variant	The code the user received, as a JSON number — `123456`, not `"123456"`.

Response

Identical to the no-OTP variant — see Response for the full payload and every field.

Errors

A failed OTP check and a failed ID image both return HTTP 400, with the case in error_code.

OTP not verified

`error_code`	Meaning	What to do
`6106`	Wrong OTP code	Re-enter the code and retry with the same `otpRequestId` — up to 5 tries per OTP.
`6105`	OTP expired	Request a new OTP and retry.
`6101`	OTP request not valid — unknown, already used, or no tries left	Request a new OTP and retry.

{
  "data": null,
  "error_code": 6106,
  "error_message": "OTP Code Incorrect"
}

ID image validation failed

Applies to PersonallyIdentifiableInformation and CheckIdAndFRAByTransaction. The failing fields come back 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": ["idBackBase64Image"]
  },
  "error_code": 6126,
  "error_message": "ID Back Image Validation Failed"
}

See Error codes for the full list.