Skip to main content
POST
Look up a Nigerian NIN or BVN
Retrieves the available person details for a Nigerian NIN or BVN. The endpoint does not compare a submitted name or DOB and does not make a verification decision. Each NIN provider attempt costs ₦120 and each BVN provider attempt costs ₦70, including attempts that return no person details.

Headers

string
required
An active production FossaPay API key with full permission. The associated business must have completed verification.
string
required
A unique key for this logical verification request, up to 255 characters. Retry with the same key and identical body to avoid an additional charge.

Body

string
required
NIN or BVN.
string
required
The person’s 11-digit NIN or BVN. Preserve leading zeros.
Nigeria is selected automatically. Do not include country, names, date of birth, or consent in the request body.

Request

Response

HTTP 200 returns the result directly:
person returns the identity number and the available person details. Optional fields are null when unavailable. The response does not include provider metadata or a verification decision. The reference is FossaPay’s identifier for the request. When no usable person details are returned, the full response has the same shape with person: null:
Both responses represent a charged lookup attempt. Your business decides how to handle the returned details or their absence.

Idempotency

  • An identical completed request with the same key returns the original result and its original fee without another charge, even if the current price has changed.
  • Reusing the key with a different request body returns 409.
  • A request still processing may return 409 or 503. Retry only with the same key and body. If it remains unresolved, contact support with the idempotency key and any returned reference.
  • If a request was rejected before verification and no charge was made, correct the issue and use a new key for the new request.

Errors

See the Identity Verification Guide for pricing examples and integration steps.

Authorizations

x-api-key
string
header
required

Headers

X-Idempotency-Key
string
required

Unique key for this verification request. Maximum 255 characters.

Required string length: 1 - 255

Body

application/json
method
enum<string>
required
Available options:
NIN,
BVN
identityNumber
string
required

11-digit NIN or BVN; retain leading zeros.

Pattern: ^[0-9]{11}$

Response

Identity lookup attempt completed and charged

reference
string<uuid>
required
method
enum<string>
required
Available options:
NIN,
BVN
charged
boolean
required
feeAmount
string
required

New NIN attempts cost 120.00 NGN and new BVN attempts cost 70.00 NGN. Idempotent replays retain the original fee, including earlier prices.

currency
string
required
Allowed value: "NGN"
person
object | null
required