How it works
- Your app opens the widget with your publishable key (
nipost_pk_…) and, optionally, a pre-filled identifier. - The widget starts a short-lived session (
POST /v1/widget/session) and shows the user’s saved postcodes, if any. - The user picks a saved postcode or finds one on the map.
- The widget closes and delivers a
PostcodeSelectionto 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.

