lumex عربي Get started

Developers

API reference

Version 1 · Base URL https://api.lumex.id/v1

Quick start

  1. Create a verification from your server for one of your users.
  2. Send the user to the url in the response. They scan their ID card or passport and take a short selfie in their phone browser.
  3. We post the result to your webhook and send the user back to your redirect_url.

All requests and responses are JSON. Call the API from your server only, never from a browser or mobile app, because your secret key must stay private.

Authentication

Send your secret key in the Authorization header. You get two keys in your dashboard:

KeyUse
lx_test_…Test mode. Runs the full flow with a test banner. Not billed. Up to 100 test verifications in 24 hours.
lx_live_…Live mode. Real checks, counted against your included checks or prepaid credit.
Authorization: Bearer lx_live_…

Create a verification

POST/v1/verifications
FieldTypeDescription
referencestring, requiredYour own ID for the user, up to 100 characters. Returned in every response and webhook.
documentstringid_card, passport or any. Leave it out to use your Accepted documents setting (dashboard, Developers), which starts as any: the user chooses.
id_countriesarray of stringsAccept ID cards only from these countries, as the 3-letter codes printed in the code lines, for example ["KWT", "FRA"]. Up to 60. null or [] accepts an ID card from any country. Leave it out to use your ID cards from setting (dashboard, Developers), which starts as any country. See ID cards from any country.
min_ageintegerThe minimum age for this check, a whole number from 13 to 99. People younger are declined. 0 switches the age check off for this check. Leave it out to use your Minimum age setting (dashboard, Developers), which starts off. See Minimum age.
localestringen or ar. Default en. The user can switch language in the flow.
redirect_urlstringHTTPS address the user returns to when they finish. We add ?verification=vrf_… to it.
metadataobjectUp to 20 string keys and values of your own. Returned as sent.

Send an Idempotency-Key header with a unique value to make retries safe. The same key within 24 hours returns the first result instead of creating a second verification. Test and live keys keep their keys apart.

curl https://api.lumex.id/v1/verifications \
  -H "Authorization: Bearer lx_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b7e-signup-1042" \
  -d '{
    "reference": "user_1042",
    "document": "any",
    "locale": "ar",
    "redirect_url": "https://your-site.com/verified"
  }'

Response 201 Created:

{
  "id": "vrf_7KQ2M9",
  "reference": "user_1042",
  "status": "created",
  "url": "https://verify.lumex.id/v/…",
  "expires_at": "2026-10-09T08:00:00Z",
  "created_at": "2026-10-08T08:00:00Z"
}

The link works for 24 hours and for one person only. Create a new verification if it expires.

Your brand on the verification page

People see your business on the lumex.id page before they start. Set it up once in the dashboard at app.lumex.id.

  • Business name in English and Arabic (Settings). Fill in at least one. The page shows the name in its own language: the Arabic name on Arabic pages, the English name on English pages. A language left empty shows no name. Send locale with each verification so people see the right one.
  • Logo (Settings). PNG, JPG or SVG, up to 500 KB. A square logo looks best: it fills the frame next to your name, on every plan. On the White label plan it also replaces the lumex.id mark.
  • Accepted documents (Developers). ID card or passport (the person chooses), ID card only, or passport only. The document field of a verification overrides it.
  • ID cards from (Developers). Any country, or only the countries you pick. The page names only those countries' cards. The id_countries field of a verification overrides it.
  • Minimum age (Developers). No age check, 18 or older, or another age from 13 to 99. The min_age field of a verification overrides it.

ID cards from any country

lumex reads a national ID card from any country, the same way it reads passports: from the code lines (machine readable zone) on the back of the card. Most national ID cards have them, including most of Europe and the GCC citizens' cards.

  • A card's country is the one printed in its code lines, never the visitor's location. With Only these countries, a card from another country gets the message "This card isn't accepted here", and the person can scan another card or use their passport. Nothing is charged for it.
  • The verification page names only what you accept: "Your national ID card" for any country, the countries by name for a list, or the card's own name for one country, such as "Kuwait Civil ID".
  • Before any scan, the page shows a short Before you scan box: soft light away from direct light, a dark flat surface, the card tilted slightly against shine, and the whole card in the frame. It sits under the QR code on a computer and on the first screen on a phone, in the page's language, worded for a card, a passport or either. There is nothing to set up.
  • Cards with no code lines on the back, such as US driving licences, Saudi resident cards and India's Aadhaar, cannot be read. After a few tries the person is told and offered their passport.
  • The country of the card used is in document.country. The list a check used is in id_countries, or null for any country.
  • Every card gives the details in its code lines. A Kuwait Civil ID also gives the full English name, the Arabic name, the address and the blood group. A UAE Emirates ID also gives its 15-digit ID number in personal_number.

Minimum age

Set a minimum age and lumex declines anyone younger, using the date of birth in the document's code lines. Those lines have already passed their check digits, and on a Kuwait Civil ID the birth date must also match the civil number. Age is worked out on today's date in UTC. Nothing extra is asked of the person, and it costs nothing extra.

  • The start screen tells the person the minimum age, for example "You must be 18 or older".
  • Someone younger is stopped right after the document scan, before any selfie is taken. The check is declined with under_minimum_age and billed like any other decline. No document copy is kept.
  • A document with no full date of birth (some passports leave out the day or month) is declined with birth_date_unknown. With Send to me for review on, it waits for you as in_review with the reason birth_date_unknown instead.
  • A check with an age check carries min_age and checks.age: "passed", "failed" or "review". Without one, min_age is null and there is no checks.age.
{
  "status": "declined",
  "decline_reasons": ["under_minimum_age"],
  "min_age": 18,
  "checks": { "code_lines": "passed", "expiry": "passed", "age": "failed" }
}

Device and connection

While the person scans, lumex also looks at the phone and the connection. This catches what a document and a selfie cannot: a camera app feeding in a video, a browser driven by a script, or one phone behind many users. Nothing extra is asked of the person, and it costs nothing extra. There is no setting: it follows your Unclear checks choice.

SignalReview offReview on
Camera app (such as OBS or ManyCam) or a script-driven browserDeclined, device_tamperingin_review, reason device_tampering
The same phone used for 3 or more other users on your account in 24 hoursReportedin_review, reason repeat_device
The same connection behind 3 or more other users, a VPN or data-centre network, or a connection country different from the documentReported only, never declined
  • checks.device is "passed", "flagged" (something worth knowing), "review" or "failed" (camera app or script-driven browser).
  • device holds the details: os and browser, ip_country (three-letter code, like the document's), network ("isp" or "hosting"), network_name, vpn_suspected, virtual_camera, automation, and same_device_24h and same_network_24h (other users on your account in the last 24 hours). It is null for checks made before these checks existed.
  • The internet address itself is never stored or returned. It is kept only as a one-way fingerprint that is different for each business, and cleared after 24 hours.

Risk score

Every check that reaches the selfie gets a risk score from 0 to 100. It adds up warning signs lumex already checks, so you can see at a glance which passed checks deserve a second look. Clear failures are still declined as before, and it costs nothing extra.

SignalCodePoints
Camera app or automated browserdevice_tampering60
Same face as another user with a different IDsame_face40
Possible photo of a screen or a printspoof_suspected35
Face match below the line but close to itface_close30
Same ID as another userduplicate_id30
Details on the ID disagreedetails_disagree30
Same phone as 3 or more other users in 24 hoursrepeat_device30
The ID may be a photocopypossible_photocopy25
Same connection as 3 or more other users in 24 hoursrepeat_network15
Same phone as 1 or 2 other users in 24 hoursshared_device10
VPN or data-centre networkvpn10
Some details could not be readdetails_unread10
Phone clock differs from the connectiontimezone_mismatch5

Points add up to a maximum of 100. Levels: low below 30, medium from 30 to 59, high from 60. A VPN alone (10) or a shared office connection (15) stays low.

Your High risk checks setting (dashboard, Developers) decides what happens to a check scoring 60 or more that would otherwise be approved:

  • Show the score only (the default): nothing changes.
  • Send to review: the check goes to in_review with the reason high_risk. This needs Unclear checks set to review.
  • Decline: the check is declined with the reason high_risk. The person is asked to contact your site and never sees the score.

risk holds score, level and signals (the codes above, strongest first). It is null until the selfie step has finished, for checks stopped earlier (for example by the age check), and for checks made before risk scores existed.

Get a verification

GET/v1/verifications/{id}

Returns the full verification object. Use it to double-check a webhook, or to poll if you cannot receive webhooks.

curl https://api.lumex.id/v1/verifications/vrf_7KQ2M9 \
  -H "Authorization: Bearer lx_live_…"

The verification object

{
  "id": "vrf_7KQ2M9",
  "reference": "user_1042",
  "status": "approved",
  "decline_reasons": [],
  "min_age": 18,
  "id_countries": null,
  "document": {
    "type": "id_card",
    "country": "KWT",
    "number": "0123456789",
    "surname": "ALSALEM",
    "given_names": "FAHAD",
    "nationality": "KWT",
    "birth_date": "1987-04-15",
    "sex": "M",
    "expiry_date": "2029-03-01",
    "personal_number": "287041501208",
    "name_ar": "فهد السالم",
    "name_en": "FAHAD ABDULLAH ALSALEM",
    "blood_group": "O+",
    "address": {
      "area": "الجابرية",
      "block": "7",
      "street": "15",
      "avenue": null,
      "building": "22",
      "floor": "3",
      "unit_type": "شقة",
      "unit_number": "4",
      "paci_number": "12345678"
    }
  },
  "checks": {
    "code_lines": "passed",
    "expiry": "passed",
    "liveness": "passed",
    "face_match": { "result": "passed", "score": 0.97 },
    "duplicate": "passed",
    "same_face": "passed",
    "age": "passed",
    "device": "passed"
  },
  "device": {
    "os": "iPhone",
    "browser": "Safari",
    "ip_country": "KWT",
    "network": "isp",
    "network_name": "Zain Kuwait",
    "vpn_suspected": false,
    "virtual_camera": false,
    "automation": false,
    "same_device_24h": 0,
    "same_network_24h": 1
  },
  "risk": {
    "score": 0,
    "level": "low",
    "signals": []
  },
  "duplicate_of": [],
  "same_face_as": [],
  "metadata": {},
  "document_images": null,
  "review": null,
  "created_at": "2026-10-08T08:00:00Z",
  "completed_at": "2026-10-08T08:01:04Z"
}

Status only moves forward:

StatusMeaning
createdLink made, user has not opened it yet.
in_progressUser opened the link and is scanning.
in_reviewWaiting for your review, up to 24 hours. See Manual review.
redo_requestedYou asked the person to redo a step. A new link was made and the old one no longer works.
approvedAll checks passed. Final.
declinedOne or more checks failed. See decline_reasons. Final.
expiredThe link was not finished within 24 hours. Final, not billed.

document stays null until the check is approved or declined: the document's details come only with a final, billed result. While a check waits for your review, you see them in the dashboard.

Decline reasons: document_expired, liveness_failed, face_mismatch, document_mismatch (the front and back are from different cards: the front must show the surname, given name or document number in the back's code lines; with review on, the check waits as details_disagree), under_minimum_age, birth_date_unknown (see Minimum age), passport_not_allowed (the check needs an ID card and a passport was shown: stopped at once, not charged), device_tampering (see Device and connection), high_risk (see Risk score). After a manual review: review_face_mismatch, review_document_altered, review_screen_or_print, review_duplicate, review_other and not_reviewed_in_time. A document that cannot be read is never declined: the person is asked to scan it again.

Document fields to know:

FieldWhat it is
numberThe document's own number. On a Kuwait Civil ID this is the card serial number, not the civil number.
personal_numberKuwait Civil ID: the 12-digit civil number. Returned only when its check digit is right and the birth date inside it matches the card, otherwise null. UAE Emirates ID: the 15-digit ID number, when its check digit is right. Passports: the personal number field, when present. Use it to allow one account per person.
name_arThe holder's name in Arabic, read from the front of a Kuwait Civil ID. null when it does not read cleanly, so ask the person instead of guessing.
name_enKuwait Civil ID: the full name in English as printed on the front, with every middle name (the code lines hold only the first and family name). Returned only when it starts with the given name and ends with the surname from the code lines, otherwise null.
addressKuwait Civil ID: the address printed on the back, as area, block, street, avenue, building, floor, unit_type, unit_number and paci_number (the PACI automated address number). paci_number comes from the code lines, which are checked. Each other part is returned when it reads cleanly; a part that does not, or is not printed, is null, so ask the person for it. The whole address is null only when the card's print contradicts its code lines. Numbers come as strings. The phone number on the card is never read.
blood_groupKuwait Civil ID: the blood group printed on the back, such as O+. null when it does not read cleanly.
surname, given_namesThe Latin name from the document's code lines.

Country codes are the three-letter codes printed in the document's code lines. Selfie images are never returned and are deleted once the result is decided. Document images are deleted too, unless your account receives document copies (below). The details read from the document are deleted 24 hours after the result: after that document is null and document_deleted is true. Save what you need when you receive the result.

Manual review

Some checks are not clearly right or clearly wrong: the face is close to a match but not over the line, the liveness check is unsure, or the card's details do not read cleanly. With Send to me for review on (dashboard, Developers), these wait for you as in_review instead of being declined. With Decline straight away, they are declined as before. New accounts start with review on.

In the dashboard you see why it waits, the selfie next to the document photo, and the document sides. Then you choose:

ActionResult
ApproveStatus becomes approved.
DeclineStatus becomes declined with a review_… reason.
Ask to redoStatus becomes redo_requested and a new link is made, valid for 24 hours. The person retakes the selfie only, or the ID card and selfie. Send them the link yourself: it is in the dashboard and in the webhook as url.

A check not decided within 24 hours is declined as not_reviewed_in_time. We email you when one is waiting, and again when 6 hours are left. Photos are kept only while it waits, and deleted once it is decided. A check is billed once, when it is approved or declined.

A verification that went to review carries review:

"review": {
  "reasons": ["face_close"],
  "due_at": "2026-10-11T08:01:04Z",
  "reviewed": false,
  "reviewed_at": null,
  "redo_steps": null,
  "redo_count": 0
}

Reasons are face_close, spoof_unsure, details_unread, possible_photocopy, details_disagree, duplicate_id (see Duplicate IDs), same_face (see Same face on different IDs), birth_date_unknown (see Minimum age), device_tampering and repeat_device (see Device and connection), and high_risk (see Risk score). due_at is set only while the status is in_review. redo_steps is selfie or all.

Duplicate IDs

lumex checks whether the same ID was already verified on your account for a different reference. It matches the Civil ID number, or the personal number in a passport, and otherwise the document number and country. Only your own checks are compared, in the same mode (live or test), and only checks that were approved or are waiting for review. The same reference verifying again, for example with a renewed card, is not a duplicate.

  • checks.duplicate is "passed" when the ID is new on your account, or "flagged" when it was used before.
  • duplicate_of lists the earlier checks it matched: id, reference, status and completed_at. It is empty when there are none.
  • With Send to me for review on, a duplicate waits as in_review with the reason duplicate_id. You approve it, or decline it as review_duplicate. With review off, the check is decided as usual and duplicate_of tells your site which user already has this ID, so it can refuse the second account itself.
"duplicate_of": [
  { "id": "vrf_3HB71P", "reference": "user_3108", "status": "approved", "completed_at": "2026-09-02T16:05:11Z" }
]

Same face on different IDs

lumex checks whether the same face was already verified on your account with a different ID under another reference: one person opening a second account with another ID card or passport. After the selfie, lumex keeps a face fingerprint, a set of numbers that cannot be turned back into a picture, for 90 days. Each new check is compared only with your own checks from the last 90 days, in the same mode (live or test), that were approved or are waiting for review. Never with other businesses.

  • checks.same_face is "passed" or "flagged". It is left out when the check is off, or when the document has no number to compare.
  • same_face_as lists the earlier checks it matched: id, reference, status, completed_at and score, how alike the two faces were from 0 to 1 (flagged from 0.80).
  • With Send to me for review on, the check waits as in_review with the reason same_face. You approve it, or decline it as review_duplicate. With review off, the check is decided as usual and the match adds same_face to the risk score. It is never declined on its own: twins and close relatives can look alike.
  • The same ID used again is caught by Duplicate IDs, not here.
  • The check is on for every account. Switch it off in the dashboard (Developers, Same face on different IDs); switching it off deletes the fingerprints kept. Your privacy notice should say faces are compared to prevent repeat sign-ups.
"checks": { "duplicate": "passed", "same_face": "flagged" },
"same_face_as": [
  { "id": "vrf_3HD8Q2", "reference": "user_1874", "status": "approved", "completed_at": "2026-09-02T10:14:00Z", "score": 0.91 }
]

Document copies

If your service needs a copy of the ID for the user's profile, switch on Document copies in your dashboard under Developers (+$0.10 per check, both plans). Before the first copy, someone signed in to your account accepts responsibility for the copies your business receives; the acceptance is recorded with their name, the date and time and their IP address, and emailed to the account owner. You can switch copies off again at any time. The person is told before the scan that you will receive a copy. Each side comes back flattened, cropped to the document's edges and turned upright, whatever angle it was scanned at.

When copies are on, a finished verification carries document_images:

"document_images": { "sides": ["front", "back"], "expires_at": "2026-10-09T08:01:04Z" }

Sides are front and back for an ID card, or passport for a passport. Download each one as a JPEG within 24 hours. After that we delete them and the endpoint returns 404 images_unavailable.

GET/v1/verifications/{id}/images/{side}
curl https://api.lumex.id/v1/verifications/vrf_7KQ2M9/images/front \
  -H "Authorization: Bearer lx_live_…" -o front.jpg

Webhooks

Add your webhook address in the dashboard. We send a POST with a JSON body for each event:

EventWhen
verification.startedThe user opened the link.
verification.in_reviewThe verification is waiting for your review.
verification.redo_requestedYou asked the person to redo a step. data.url is the new link.
verification.approvedThe verification was approved.
verification.declinedThe verification was declined.
verification.expiredThe link expired unfinished.
{
  "id": "evt_3HZ81L",
  "type": "verification.approved",
  "created_at": "2026-10-08T08:01:04Z",
  "data": { /* the verification object */ }
}

Reply with any 2xx status within 10 seconds. If you do not, we retry with growing gaps for up to 24 hours. The same event can arrive more than once, so ignore an id you have already handled.

Check the signature on every webhook. Each request has a Lumex-Signature header like t=1791446464,v1=5257a8…. Compute an HMAC-SHA256 of t + "." + raw body with your webhook secret and compare it to v1. Reject it if t is more than 5 minutes old.

import crypto from "node:crypto";

export function verifyLumex(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(",").map(x => x.split("=")));
  const t = Number(p.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  if (!p.v1 || p.v1.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}

Use the raw request body exactly as received. Parsing and re-encoding the JSON first changes the bytes and breaks the signature.

Errors

Errors return a JSON body with a stable code you can check in your code, and a readable message:

{ "error": { "code": "invalid_field", "message": "redirect_url must start with https://" } }
HTTPWhen
400A field is missing or not valid.
401The key is missing, wrong or revoked.
402Your plan is not active, or your prepaid credit does not cover this check and your live checks still open. Top up in the dashboard.
404No verification with that ID in this mode.
409The same Idempotency-Key was used with a different body, or a request with that key is still being handled (idempotency_in_progress).
429Too many requests. Wait for the seconds in Retry-After. With a test key, test_limit: the 100 test verifications in 24 hours are used.
5xxOur side. Retry with the same Idempotency-Key.

Need a hand?

Tell us about your stack through the contact form and we will help you connect your first site.