API Reference

One endpoint. Validate an Arab-world company's registration number (TRN/VAT), surface risk signals, and report registry confidence.

Quickstart

Sign in with your email — enter it on the home page; we email a one-time sign-in link (15 min). Don't see it? Check your spam or trash folder.
Create an API key — in your dashboard, click Create API key. The full key is shown once.
Call the endpoint — send x-api-key plus a JSON body.
Read the verdict — check trn_format_valid, verdict and risk_tags.

Server-side signup is also supported via POST /api/v1/keys — the key starts unverified and activates after the emailed confirmation link.

# 1. Get a key (shown once)
curl -X POST https://mena-biz-api.vercel.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com"}'

# 2. Call the endpoint
curl -X POST https://mena-biz-api.vercel.app/api/v1/verify-company \
  -H "x-api-key: lb_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"SA","trn":"310000000000000","name":"Acme Trading LLC"}'

Authentication

Every request needs an x-api-key header. Keys look like lb_test_….

Keys are stored only as SHA-256 hashes. We cannot recover a lost key — request a new one.
Missing, invalid or revoked key → 401.
One key per email; requesting a second time returns 409.
Never ship a key in client-side code or a public repo.

Endpoints

POST/api/v1/verify-company

Field	Type	Required	Notes
`country`	string	yes	ISO-2 — SA, AE, BH, KW, QA, OM, LB
`trn`	string	no	Registration / VAT number to validate
`name`	string	no	Company name, used for risk-tag heuristics

POST/api/v1/keys

Body: { "email": "you@company.com" }. Returns the key once, plus tier, requests_limit and founder_slots_left.

GET/api/v1/keys

Public. Returns founder_slots, founder_calls, claimed and slots_left.

POST/api/v1/keys/rotate

Rotate a key. Send the current key in x-api-key; the old key stops working immediately and the new key is returned once. Usage counters are preserved — rotation does not refill your quota.

curl -X POST https://mena-biz-api.vercel.app/api/v1/keys/rotate \
  -H "x-api-key: lb_test_YOUR_CURRENT_KEY"

Response

{
  "country": "SA",
  "trn_format_valid": true,
  "verdict": "likely",            // likely | invalid | unknown
  "risk_tags": ["generic_shell"], // offshore | newly_registered | generic_shell
  "checks": {
    "registry_live": "not_queried_no_feed",
    "sanctions_match": "not_queried_no_feed"
  }
}

warning

Honest scope. Today this API validates TRN/VAT format and returns risk heuristics. It does not query live government registries or sanctions lists — every response reports registry_live: "not_queried_no_feed" until a licensed regional data feed is connected. No fabricated verdicts.

Errors

Code	Meaning
`400`	Missing country or malformed JSON
`401`	Missing, invalid or revoked x-api-key
`403`	Key exists but the email is not confirmed yet
`409`	Email already has a verified key
`429`	Quota exhausted, rate limit hit, or too many signups from this IP
`500`	Server error

Rate limits & quotas

500calls

Founder quota (100 on the standard tier). Exceeding it returns 429.

60req / min

Per key. Enforced from the usage log; exceeding it returns 429.

Every successful call is incremented on your key and written to the usage-logs table.

Signup limits: 3 key requests per hour per IP, and disposable / throwaway email domains are rejected. Unconfirmed keys do not authorize calls, so a squatted email can always be reclaimed by its real owner.

Pricing

Tier	Price
Founder	500 calls — free for the first 50 signups
Pay-as-you-go	Usage-based, billed via Dodo Payments (opens after the founder round)

FAQ

Is the data live from government registries?

Not yet — see the honest note above. Format validation and risk heuristics work today; live registry lookups require a licensed regional data feed.

Which countries are supported?

Saudi Arabia, UAE, Bahrain, Kuwait, Qatar, Oman and Lebanon.

I lost my key.

Keys are stored as SHA-256 hashes and cannot be recovered. Request a new one from the home page (one key per email).

Can I call it from an AI agent?

Yes — it is a plain REST endpoint with a header-based key. The hands, not the brain.