IdentifyOrg API Documentation

The IdentifyOrg API is organised around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes. All endpoints are versioned under /v1.

Authentication

Authenticate every request with your API key in the X-IdentifyOrg-Key header. Test keys are prefixed io_test_ and live keys io_live_. Test keys return realistic sandbox data and never charge your balance. Create an account to get your keys.

Test mode and live mode

Every account starts in test mode. A test key is free and unlimited: it never bills you and never contacts a bank, carrier, payment provider or any other third party, so you can finish your integration without spending anything. Every response from a test key says so: it has the header X-IdentifyOrg-Mode: test and a JSON body containing "livemode": false, and calls from test keys show under Test in your dashboard. Virtual accounts and card charges created with a test key are test accounts; complete them with POST /v1/business/test/simulate-payment and POST /v1/business/test/simulate-card-payment. When it works, switch the account to live in the dashboard under API Keys to get live keys and start real, billed calls.

Optional: server-side integrations can send X-IdentifyOrg-Site: yourdomain.com so we can tell which of your sites a call belongs to. Browsers add this information themselves.

Your first verification

Verify a BVN with a single request:

curl -X POST https://api.identifyorg.com/v1/verify/bvn \
  -H "X-IdentifyOrg-Key: io_test_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901",
    "first_name": "Adaeze",
    "last_name": "Okafor"
  }'

A successful response looks like this:

{
  "id": "ver_01hxyz...",
  "type": "bvn",
  "status": "success",
  "match": true,
  "confidence_score": 98,
  "data": {
    "full_name": "Adaeze N. Okafor",
    "date_of_birth": "1992-04-15",
    "phone": "+2348012345678",
    "gender": "female"
  },
  "created_at": "2026-07-02T10:24:00Z"
}

Sync vs async

BVN, NIN and FRSC checks are synchronous — the result comes back in the same request. Document verification, face match and some liveness checks are asynchronous: the API returns a job_id immediately, and you either poll GET /v1/jobs/{id} or receive the result on your webhook endpoint.

WhatsApp: messages, OTP and identity checks

Link your own WhatsApp number once in your dashboard (scan a QR code), then use the same API key to reply to customers, send one-time codes and verify identity over WhatsApp. See the WhatsApp guide for the full walkthrough, or jump to the WhatsApp endpoints in the API reference.

Errors

IdentifyOrg uses conventional HTTP status codes and returns a structured error object:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this verification. Top up to continue.",
    "status": 402
  }
}

Idempotency

Pass an Idempotency-Key header on any POST request to guarantee you are never charged twice for the same verification, even if you retry after a network failure.