PUBLIC API REFERENCE

VetifyID API Documentation

Build production-grade identity verification flows with a single, well-documented REST API. Authenticate once, verify thousands of NINs per minute.

Create Free AccountTry Sandbox

Quickstart

Sign up, generate an API key from the dashboard, then send your first sandbox verification. Sandbox mode is free and uses pre-seeded mock citizens — switch to live once you've funded your wallet.

POST /api/v1/sandbox/verify · curl
curl -X POST https://api.vetifyid.com/api/v1/sandbox/verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"nin": "12345678901"}'

Authentication

POST
/api/v1/auth/token
Exchange API key/secret for a short-lived bearer token (OAuth2 client credentials).
POST
/api/auth/register
Create a new developer account. Returns user object.
POST
/api/auth/login
Sign in with email + password or email + PIN.

Verification

POST
/api/v1/verify
Verify a NIN in live mode. Charge applies. Returns identity data.
POST
/api/v1/sandbox/verify
Verify a NIN against mock citizens — free, deterministic.
POST
/api/verify/start
Begin a guided verification flow (returns a sessionId).
POST
/api/verify/submit
Submit CAPTCHA / response for an in-flight session.

Wallet & Billing

GET
/api/user/profile
Current user, balance, and API key metadata.
GET
/api/funding/status/:reference
Poll funding reference status (Paystack transfer via KnowIT Merchant).

Account

POST
/api/user/generate-key
Rotate the API key. Old key is invalidated.
POST
/api/user/security-settings
Update password, PIN, or webhook URL.
GET
/api/user/logs
Last 200 API call log rows for this user.

Response Status Codes & Errors

VetifyID uses standard HTTP response codes to indicate the status of your verification requests.

HTTP StatusError CodeWallet Charged?Description
200 OK—YesVerification completed successfully and credentials matched NIMC records.
200 OKRECORD_MISMATCHYesThe NIN exists, but the submitted name or date of birth does not match the official profile.
200 OKINVALID_NINYesThe submitted NIN is invalid, incorrect, or not found on the registry.
402 PayINSUFFICIENT_FUNDSNoTenant wallet balance is lower than the required verification fee. Top up required.
403 ForbiddenENVIRONMENT_LOCKEDNoTenant live API environment is locked. Verification or compliance onboarding pending approval.
503 ServiceGATEWAY_TIMEOUTNoThe official NIMC registry portal timed out or returned connection errors. Re-verify queue item triggers manual follow-up.