Skip to main content

​
API keys

Authenticate by sending your key in the X-API-Key header:
Keys are created in the dashboard (Settings → API Keys). The secret is shown once at creation. Keys come in two environments and two kinds: Secret keys must never reach a browser or mobile binary. Publishable keys are built for exactly that: they are capped at lookup level 3, limited to the search, lookup and widget scopes, and in browsers they only work from the origins on the key’s allowlist. See Publishable keys.

​
Test mode

A test key (nipost_test_…) is for building and testing your integration without touching production:
  • Separate sandbox dataset. Test keys resolve a small, curated sample of public places only — not the live postcode database. Production codes will not resolve under a test key, and the sandbox contains no private residential addresses.
  • Free and unmetered. Test calls never consume credits, at any lookup level.
  • One per organization. An organization may hold a single active test key. Revoke the existing one to issue a replacement.
Sandbox postcodes. These always resolve under a test key (and only a test key). Use them to exercise your integration; call search/autocomplete with your test key to discover more. A live key (nipost_live_…, requires verified KYB) resolves the full production dataset and is metered normally. Switching from test to live is just a matter of swapping the key — the endpoints and request shape are identical.

​
Scopes & access levels

Each key carries scopes (search, lookup) and a max lookup level (1–5; publishable keys are capped at 3). A key can never exceed the level granted to your organization. To raise it, request higher access under Settings → KYB & Access. All endpoints require an API key. “Free” below means it consumes no credits — not that it is unauthenticated.

​
Rate limits

Requests are rate-limited per key. Each response includes:
Exceeding the limit returns 429 Too Many Requests.

​
Errors

Errors use a consistent envelope: