IdentifyOrgIdentifyOrg

API Reference

All endpoints require the X-IdentifyOrg-Key header. Base URL: https://api.identifyorg.com. This reference is generated from our OpenAPI 3.0 specification — the same source of truth our SDKs are built from.

Verify a BVN

POST/v1/verify/bvn

Verify an 11-digit Bank Verification Number. Optionally pass first_name, last_name and date_of_birth for cross-match scoring. Synchronous — responds in under 3 seconds.

Request
{
  "bvn": "12345678901",
  "first_name": "Adaeze",       // optional
  "last_name": "Okafor",        // optional
  "date_of_birth": "1992-04-15" // optional
}
Response
{
  "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",
    "photo": "data:image/jpeg;base64,..."
  }
}

Verify a NIN

POST/v1/verify/nin

Verify an 11-digit National Identification Number issued by NIMC. Returns full identity data including photo where available. Synchronous — responds in under 4 seconds.

Request
{
  "nin": "12345678901"
}
Response
{
  "id": "ver_01hxyz...",
  "type": "nin",
  "status": "success",
  "data": {
    "full_name": "Adaeze N. Okafor",
    "date_of_birth": "1992-04-15",
    "gender": "female",
    "phone": "+2348012345678",
    "state_of_origin": "Anambra",
    "photo": "data:image/jpeg;base64,..."
  }
}

Verify a driver's licence

POST/v1/verify/frsc

Verify a Nigerian driver's licence via licensed FRSC data partners. Returns licence status, class, expiry date and state of issue.

Request
{
  "licence_number": "ABC12345DE67",
  "first_name": "Adaeze", // optional
  "last_name": "Okafor"   // optional
}
Response
{
  "id": "ver_01hxyz...",
  "type": "frsc",
  "status": "success",
  "data": {
    "licence_status": "valid",
    "expiry_date": "2028-11-30",
    "licence_class": "B",
    "state_of_issue": "Lagos"
  }
}

Verify a document

POST/v1/verify/document

Upload a document (multipart/form-data) for OCR verification. Supported types: passport, nin_slip, utility_bill, cac_certificate, bank_statement, certificate_of_occupancy, custom. Asynchronous — returns 202 with a job_id; result delivered via webhook or polling.

Request
POST /v1/verify/document
Content-Type: multipart/form-data

document_type = "passport"
file          = <binary>
retain        = false   // delete after processing (default)
Response
{
  "job_id": "job_01hxyz...",
  "status": "processing",
  "poll_url": "/v1/jobs/job_01hxyz..."
}

Submit a liveness session

POST/v1/verify/liveness

Submit frames captured during a client-side liveness challenge (blink, turn, smile) for server-side passive analysis. Returns a confidence score from 0–100; scores of 75 or above are considered live.

Request
{
  "session_id": "lvs_01hxyz...",
  "frames": ["<base64>", "<base64>", "..."],
  "challenge": "blink_then_smile"
}
Response
{
  "id": "ver_01hxyz...",
  "type": "liveness",
  "status": "success",
  "live": true,
  "confidence_score": 91
}

Compare two faces

POST/v1/verify/face-match

Biometrically compare a live capture against a reference image (e.g. the photo returned by a BVN/NIN lookup). Asynchronous on CPU infrastructure; results in under 15 seconds.

Request
{
  "source_image": "<base64>",
  "reference_image": "<base64>",
  "threshold": 80  // optional, default 80
}
Response
{
  "id": "ver_01hxyz...",
  "type": "face_match",
  "status": "success",
  "match": true,
  "similarity_score": 94.2,
  "distance": 0.21
}

Create a streaming room

POST/v1/stream/rooms

Create a real-time video room for video KYC, live classes or support calls. Use POST /v1/stream/token to generate short-lived participant tokens, and GET /v1/stream/rooms/{id} for room status and participant count. Billed at ₦5 per active room minute.

Request
{
  "name": "kyc-session-4821",
  "max_participants": 2,
  "record": true
}
Response
{
  "room_id": "rm_01hxyz...",
  "name": "kyc-session-4821",
  "status": "active",
  "created_at": "2026-07-02T10:24:00Z"
}

Poll an async job

GET/v1/jobs/{id}

Check the status of an asynchronous verification job (documents, face match, liveness). Statuses: processing, success, failed, manual_review.

Response
{
  "job_id": "job_01hxyz...",
  "status": "success",
  "result": {
    "type": "document",
    "document_type": "passport",
    "checks": {
      "mrz_valid": true,
      "not_expired": true,
      "format_consistent": true
    },
    "extracted": {
      "full_name": "OKAFOR ADAEZE N",
      "passport_number": "A12345678",
      "expiry_date": "2030-05-01"
    }
  }
}

Balance & usage

GET/v1/balance

GET /v1/balance returns your current credit balance and free-tier calls remaining this month. GET /v1/usage returns usage history with date filters (?from=2026-06-01&to=2026-06-30). GET/POST /v1/webhooks manages your webhook endpoints.

Response
{
  "balance": 48250.00,
  "currency": "NGN",
  "low_balance": false,
  "free_tier_remaining": 2
}

PDF to DOCX

POST/v1/tools/pdf-to-docx

Convert a PDF into an editable Word document. multipart/form-data upload, field name `file`. Returns the .docx binary directly (Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document). Max file size 20MB.

Request
curl -X POST https://api.identifyorg.com/v1/tools/pdf-to-docx \
  -H "X-IdentifyOrg-Key: io_live_xxxx" \
  -F "file=@document.pdf" \
  -o converted.docx

DOCX to PDF

POST/v1/tools/docx-to-pdf

Convert a Word document to PDF. multipart/form-data upload, field name `file`. Returns the .pdf binary directly. Max file size 20MB.

Request
curl -X POST https://api.identifyorg.com/v1/tools/docx-to-pdf \
  -H "X-IdentifyOrg-Key: io_live_xxxx" \
  -F "file=@document.docx" \
  -o converted.pdf

Audio format conversion

POST/v1/tools/audio-convert

Convert audio between mp3, wav, aac, flac, ogg and m4a. multipart/form-data upload with fields `file` and `target_format`. Returns the converted audio binary. Max file size 50MB.

Request
curl -X POST https://api.identifyorg.com/v1/tools/audio-convert \
  -H "X-IdentifyOrg-Key: io_live_xxxx" \
  -F "file=@voice-note.wav" \
  -F "target_format=mp3" \
  -o converted.mp3

Background remover

POST/v1/tools/remove-background

Remove the background from an image, returning a transparent PNG. multipart/form-data upload, field name `file`. Max file size 15MB.

Request
curl -X POST https://api.identifyorg.com/v1/tools/remove-background \
  -H "X-IdentifyOrg-Key: io_live_xxxx" \
  -F "file=@photo.jpg" \
  -o no-background.png