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. A selection may also carry "temporary": true. That marks a TP-… code minted for a building with no postcode yet, so segments and names are entirely null and the code resolves to the real postcode through /v1/lookup once one is assigned. The field is absent on an ordinary selection. Only SDKs with the request flow turned on can return one — today that is Android, from 0.2.0, and only when the host sets allowPostcodeRequest.

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.