Responses and Status Codes

Handle the response envelope, completed statuses, and endpoint-specific verification data.

Idyntic uses a stable response envelope with endpoint-specific verification data.

Completed verification envelope

{
  "success": true,
  "message": "NIN Verification (NIN) Successful",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440001",
    "status": "SUCCESSFUL",
    "type": "nin",
    "environment": "live",
    "nin_data": {}
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": true,
    "note": "Wallet charged 100.00 NGN"
  }
}

BVN endpoints use bvn_data instead of nin_data.

Completed statuses

StatusMeaningIdentity data
SUCCESSFULA matching identity record was returnedVerification data object
NOT_FOUNDThe lookup completed without a matching recordnull
SUSPENDEDNIMC reports that the NIN is suspendedVerification data when available, otherwise null
BLOCKEDThe BVN is blocked or watchlistedVerification data when available, otherwise null

All four statuses return HTTP 200 and success: true. Always branch on data.status.

Type values

TypeEndpoint
ninNIN Verification
nin_phoneNIN Verification by Phone
bvnBVN Verification
bvn_phoneBVN Verification by Phone

Environment values

  • test: deterministic sandbox response.
  • live: live identity data and wallet billing.

Verification data contract

The fields inside nin_data and bvn_data are specific to each verification endpoint. Idyntic:

  • Returns every documented field for the endpoint.
  • Preserves empty strings, null, booleans, casing, and field names.
  • Keeps response field names stable within API version v1.

Build against the response example for the endpoint you use. Contract changes are introduced through API versioning.

Request identifier

Every response includes an X-Request-Id header. Error bodies also include the same identifier at error.requestId. Include it when contacting support.


Did this page help you?