Skip to main content
The Postcode Widget is an embeddable flow your app opens when it needs a postcode from a user. It identifies the user by NIN or email (typed by the user or pre-filled by your app), shows their bookmarked postcodes, offers a full map-based discover experience, and hands the final selection back to your app.

​
How it works

  1. Your app opens the widget with your publishable key (nipost_pk_…) and, optionally, a pre-filled identifier.
  2. The widget starts a short-lived session (POST /v1/widget/session) and shows the user’s saved postcodes, if any.
  3. The user picks a saved postcode or finds one on the map.
  4. The widget closes and delivers a PostcodeSelection to your app.

​
SDKs

Every SDK is built and documented; “publication pending” means the package is not yet on its registry, so consume it from the repository until it lands. iOS ships as a compiled XCFramework from a public distribution repository, since the SDK sources are private. That repository’s URL is the one an app adds.

​
The selection payload

Every SDK delivers the same JSON shape (version 1):
segments/names fields beyond the selection’s precision are null. address is the postcode’s recent house address, or null when the server has none on record.

​
Privacy model

The widget intentionally skips OTP verification for a friction-free flow, so treat identifiers with care:
  • Bookmark reads return only {postcode, label} — no names, no contact details, no account data.
  • Session responses are identical whether or not the identifier matched an account, so the API cannot be used to probe which NINs or emails exist.
  • Sessions are rate-limited per key and per IP, metered in credits, and audited with a hashed identifier (the raw NIN or email is never logged).
  • Publishable keys are origin-bound in browsers and instantly revocable.