Skip to main content

​
API keys

Authenticate by sending your key in the X-API-Key header: 
curl "https://api.postcode.gov.ng/v1/lookup?code=EK-01-A03-FK-01&level=2" \
  -H "X-API-Key: nipost_live_xxx"
Keys are created in the dashboard (Settings → API Keys). The secret is shown once at creation. Keys come in two environments:
PrefixEnvironment
nipost_test_…Test
nipost_live_…Live (requires verified KYB)

​
Scopes & access levels

Each key carries scopes (search, lookup) and a max lookup level (1–5). A key can never exceed the level granted to your organization — request higher access under Settings → KYB & Access.
ResourceRequirement
Search, AssemblyPublic (no key)
Lookup L1Public (no key)
Lookup L2–L4Key with lookup scope + sufficient level (credits)
Lookup L5Restricted (granted on review)

​
Rate limits

Requests are rate-limited per key. Each response includes: 
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
Exceeding the limit returns 429 Too Many Requests.

​
Errors

Errors use a consistent envelope: 
{ "error": { "code": "insufficient_credits", "message": "not enough credits; top up to continue" } }
StatusMeaning
401Missing/invalid API key, or auth required for the requested level
403Key lacks the scope or level for this request
402Insufficient credits
429Rate limit exceeded