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.

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.

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.