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 search/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 bookmark or searches for a postcode.
  4. The widget closes and delivers a PostcodeSelection to your app.

​
SDKs

​
The selection payload

Every SDK delivers the same JSON shape (version 1):
segments/names fields below the selection’s level are null. latitude/longitude are present only when your key’s lookup level permits point geometry. source is "bookmark" or "search"; label is set for bookmarks only.

​
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.