NDAS API v1.0.0

Resolve a coordinate to a structured address

Public tier. Walks the admin hierarchy (Region → … → Village), returns the standardized physical block, the official postcode (or an explicit `pending_allocation` status — never a placeholder), and a confidence score. Response contains location/status data only.

Request body — ResolveRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/resolve' \
  -H 'X-API-Key: <your sandbox key>' \
  -H 'Content-Type: application/json' \
  -d '{ "point": { "lat": 0.3355, "lon": 32.5555 }, "gps_accuracy_m": 4 }'

Register an address (allocate a digital address code)

Partner/agent scoped. Allocates the next sequential premise number in the resolved parish and mints the canonical digital address. In a `pending_allocation` parish the capture is stored and `201` returns the record with `status: pending_allocation` and `digital_address`, `postcode`, and `premise` all `null` (the schema enforces this coherence); issuance happens when MoICT allocates the postcode — the partner is notified and can re-fetch via its `unique_reference`. **Requires `Idempotency-Key`, scoped per principal.** The replay ledger key is (authenticated principal, Idempotency-Key): replays by the same principal return the original result; a different principal using the same key string hits its own independent ledger — it can neither read another partner's result nor cause a cross-tenant `409`.

Parameters

Request body — RegisterAddressRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/addresses' \
  -H 'X-API-Key: <your sandbox key>' \
  -H 'Content-Type: application/json' \
  -d '{ "point": { "lat": 0.3355, "lon": 32.5555 }, "gps_accuracy_m": 6.5, "street": "Kafu Road", "house_number": "24", "unique_reference": "partner-abc-000123" }'

Look up an address by digital address code

Accepts the canonical frozen format **and any superseded or legacy alias shape** (grandfathered System-A codes included — issued codes resolve forever). The registry, not the URL pattern, decides validity: unknown codes are `404`; only over-length input is structurally rejected (`422`). The response's `digital_address` is **always the canonical current code**; when the query was an alias, `queried_code` echoes what was asked. Anonymous lookups draw from the strict per-IP anti-enumeration budget (`x-ndas-rate-limit-tiers`); bulk lookup requires keyed access. Audience shaping: unauthenticated and public keys receive `PublicAddress`; partner scopes receive `PartnerAddress`.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/addresses/{digital_address}' \
  -H 'X-API-Key: <your sandbox key>'

Look up an address by partner reference (crosswalk)

The sync join key: a partner passes its own `unique_reference` (supplied at registration) and receives the canonical record. Scoped to the owning partner — references are tenant-isolated.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/addresses/reference/{unique_reference}' \
  -H 'X-API-Key: <your sandbox key>'

Standardize messy address input into the canonical block

Accepts free text and/or partial components and returns the canonical physical address block (what Posta and partners use to clean their data). Returns candidate interpretations ranked by confidence.

Request body — StandardizeRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/standardize' \
  -H 'X-API-Key: <your sandbox key>' \
  -H 'Content-Type: application/json' \
  -d '{ "raw_text": "plot 24 kafu rd bwaise kawempe kampala" }'

List administrative units (drill-down)

The Region → District → County → Sub-county → Parish → Village drill-down. Filter by `level` and/or `parent_id`; omit both to list regions. Paginated.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/reference/admin-units' \
  -H 'X-API-Key: <your sandbox key>'

List the direct children of an administrative unit

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/reference/admin-units/{admin_unit_id}/children' \
  -H 'X-API-Key: <your sandbox key>'

Look up a postcode (current, superseded, or legacy alias)

Returns the official record for a postcode query. Accepts canonical 5-digit codes, superseded codes, and **legacy alias shapes** (e.g. grandfathered System-A placeholders) — the registry decides validity; unknown queries are `404`, only over-length input is `422`. Superseded 5-digit codes resolve forever: the record carries `status: superseded` plus the canonical successor in `canonical_code`. For legacy-shaped aliases the returned record **is** the canonical target (its `code` keeps the frozen 5-digit format) and `queried_code` echoes the original query.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/reference/postcodes/{code}' \
  -H 'X-API-Key: <your sandbox key>'

Consented person–address match (KYC product)

The monetized verification product for banks/immigration/MDAs. Requires the `kyc.match` scope (OAuth2 bearer — API keys alone do not carry it) **and** a valid consent reference (Uganda DPPA 2019). Consent is bound to the specific check: **(subject, purpose, address-bounded)**. The server MUST reject with `403` (`consent_scope_invalid`) any consent whose scope does not cover the queried `digital_address` — a single consent can never be replayed across arbitrary addresses to discover where a person lives. The response is a match boolean with consent/audit references — **raw PII is never echoed back**. Every lookup is written to the immutable audit trail (who queried whose address, under which consent).

Request body — KycMatchRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/kyc/address-match' \
  -H 'X-API-Key: <your sandbox key>' \
  -H 'Content-Type: application/json' \
  -d '{ "digital_address": "UG-0007-10201", "subject": { "full_name": "Synthetic Party 001", "nin_token": "tok_sandbox_5f2a9c" }, "consent_reference": "consent-2026-000042" }'

Service health and data versions

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/health' \
  -H 'X-API-Key: <your sandbox key>'

List addresses for moderation (NDAS Staff)

Moderation-oriented listing. Carries NO owner/party data.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/addresses' \
  -H 'X-API-Key: <your sandbox key>'

Staff address detail (owner block included — the read is audited)

The only endpoint family that shapes owner data into a response (blueprint §9 — staff see more, but everything is audited): each call emits an `admin.address_viewed` audit event naming the staff principal. The NIN token hash never leaves the registry.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/addresses/{digital_address}' \
  -H 'X-API-Key: <your sandbox key>'

Moderate an address (verify / reject / retire)

Lifecycle transitions: `verify` (unverified → verified), `reject` (stays unverified; the rejection is recorded as a verification event), `retire` (unverified|verified → retired — the code stays resolvable forever and is never reused). Disallowed transitions are `409` `moderation_action_invalid`. Audited.

Parameters

Request body — ModerationRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/admin/addresses/{digital_address}/moderate' \
  -H 'X-API-Key: <your sandbox key>'

The verification queue (unverified addresses + evidence)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/verification/queue' \
  -H 'X-API-Key: <your sandbox key>'

The dispute / claim-conflict queue

Summaries only — claimant contact (PII) appears in detail.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/disputes' \
  -H 'X-API-Key: <your sandbox key>'

Open a dispute against a registered address

Request body — DisputeCreateRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/admin/disputes' \
  -H 'X-API-Key: <your sandbox key>'

Dispute detail (claimant contact included — the read is audited)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/disputes/{dispute_id}' \
  -H 'X-API-Key: <your sandbox key>'

Decide a dispute (evidence-based; audited)

Allowed from `open`, `under_review`, or `appealed`; the case becomes `resolved`. Decisions move the *claim*, never the code (permanence).

Parameters

Request body — DisputeAdjudicateRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/admin/disputes/{dispute_id}/adjudicate' \
  -H 'X-API-Key: <your sandbox key>'

Appeal a resolved dispute (reopens the case; audited)

Parameters

Request body — DisputeAppealRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/admin/disputes/{dispute_id}/appeal' \
  -H 'X-API-Key: <your sandbox key>'

The field network — per-agent activity and trust scores

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/agents' \
  -H 'X-API-Key: <your sandbox key>'

List field-agent assignments

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/field-tasks' \
  -H 'X-API-Key: <your sandbox key>'

Assign a field agent to an area (audited)

Request body — FieldTaskCreateRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/admin/field-tasks' \
  -H 'X-API-Key: <your sandbox key>'

Move a field task along its lifecycle (audited)

Parameters

Request body — FieldTaskStatusRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/admin/field-tasks/{task_id}/status' \
  -H 'X-API-Key: <your sandbox key>'

Verification coverage per district (or per parish of one district)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/reports/coverage' \
  -H 'X-API-Key: <your sandbox key>'

Usage/audit event volumes (ClickHouse-backed, outbox fallback)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/reports/usage' \
  -H 'X-API-Key: <your sandbox key>'

Query the immutable audit trail (who did what)

Queries the ClickHouse audit store; when it is unreachable the response falls back to the transactional outbox and says so in `source` — a partial view is never silently presented as the trail.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/audit-events' \
  -H 'X-API-Key: <your sandbox key>'

NDAS Staff users & roles (Keycloak-backed view; NDAS Admins only)

A read-only projection of the Keycloak `ndas-staff` realm (users + realm roles). Provisioning stays in Keycloak. Requires the `ndas-admin` role; the read is audited. `503` when the identity provider view is unavailable or unconfigured.

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/admin/users' \
  -H 'X-API-Key: <your sandbox key>'

List boundary changes (draft → review → publish pipeline)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/boundary/changes' \
  -H 'X-API-Key: <your sandbox key>'

Draft a boundary change (hand-drawn or dissolve-from-children)

`geometry_edit` takes a GeoJSON Polygon/MultiPolygon drawn in the editor. `dissolve_from_children` computes the geometry server-side as the union of the unit's current children — the standard way to fill missing upper-level (region/county/subcounty) polygons — and rejects a supplied geometry. Both create a reviewable, audited draft; nothing touches the live map until publish.

Request body — BoundaryChangeCreateRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/boundary/changes' \
  -H 'X-API-Key: <your sandbox key>'

Boundary change detail (with geometry + validation report)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/boundary/changes/{change_id}' \
  -H 'X-API-Key: <your sandbox key>'

Submit a draft for review (topology validation gates it)

Re-runs topology validation and stores the report on the change. A failing report blocks review (`422 geometry_invalid`, status stays `draft`); a passing one moves the change to `in_review`. Audited.

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/boundary/changes/{change_id}/submit' \
  -H 'X-API-Key: <your sandbox key>'

Publish a reviewed change (NDAS Admins; four-eyes; versioned)

Requires the `ndas-admin` role AND a reviewer different from the author. Re-runs topology validation inside the publish transaction (a neighbouring boundary may have changed since review — TOCTOU guard), then applies the geometry, snapshots the prior geometry on the change, advances the unit's version, and bumps the live boundary data version (cache invalidation). `409` when: not in review, the draft is stale (the unit's version moved since drafting), or topology no longer validates against the current map.

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/boundary/changes/{change_id}/publish' \
  -H 'X-API-Key: <your sandbox key>'

Reject a change in review (audited)

Parameters

Request body — BoundaryRejectRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/boundary/changes/{change_id}/reject' \
  -H 'X-API-Key: <your sandbox key>'

Ad-hoc topology validation for the editor

Validates a proposed geometry for a unit against its level's invariants — OGC validity (with an auto-repaired geometry offered back), no sibling overlap (borders may touch, interiors may not), containment within the parent. PostGIS/GEOS-backed.

Request body — BoundaryValidateRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/boundary/validate' \
  -H 'X-API-Key: <your sandbox key>'

Coverage intelligence — the heatmap + the fix-next list

Where the map is missing or wrong: per-level geometry coverage, the capped list of units without polygons, registered addresses falling OUTSIDE every parish polygon (per district), parishes awaiting an official postcode, and duplicate admin codes.

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/boundary/coverage' \
  -H 'X-API-Key: <your sandbox key>'

One unit's editable geometry (GeoJSON) for the editor

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/boundary/admin-units/{admin_unit_id}/geometry' \
  -H 'X-API-Key: <your sandbox key>'

Postcode registry oversight (search + paginate)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/boundary/postcodes' \
  -H 'X-API-Key: <your sandbox key>'

The pending_allocation queue (parishes without official codes)

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/boundary/pending-parishes' \
  -H 'X-API-Key: <your sandbox key>'

Record an official MoICT allocation for a pending parish

NDAS never mints postcodes — this RECORDS what MoICT allocated (blueprint §3.3), and is fail-closed on authenticity and permanence: - **Four-eyes:** `ndas-admin` only (not a lone boundary-editor). - **Authenticity:** the code MUST be in the official MoICT allocation (the complete April-2019 schedule plus any loaded refresh master). A well-formed but unofficial code is rejected `422 code_not_official` — a fabricated code can never become a permanent digital address. - **Permanence / one-code-per-parish:** `409 postcode_conflict` if the code is already registered OR the parish already holds a code. On success the code enters the registry (bound to the parish admin-unit by id), the parish leaves the queue, the registry data version bumps (engine + caches reload), and the allocation is audited with the MoICT source reference.

Parameters

Request body — PostcodeAllocateRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/boundary/pending-parishes/{pending_id}/allocate' \
  -H 'X-API-Key: <your sandbox key>'

The signed-in partner user's tenant, role, and environment

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/partner/me' \
  -H 'X-API-Key: <your sandbox key>'

List the tenant's API keys and production key requests

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/partner/keys' \
  -H 'X-API-Key: <your sandbox key>'

Issue a sandbox key instantly, or file a production key request

partner-admin only. `sandbox: true` (default) mints immediately and returns the plaintext ONCE. `sandbox: false` files a request that NDAS Staff approve; the partner then claims the approved request (the plaintext is minted in the partner's own session — staff never see it). Sandbox deployments always mint sandbox keys regardless of the flag. `kyc.match` can never be carried by an API key.

Request body — CreatePartnerKeyRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/keys' \
  -H 'X-API-Key: <your sandbox key>'

Rotate a key (revoke + mint a successor with the same scopes)

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/keys/{key_id}/rotate' \
  -H 'X-API-Key: <your sandbox key>'

Revoke a key immediately

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/keys/{key_id}/revoke' \
  -H 'X-API-Key: <your sandbox key>'

Claim an approved production key request (mints the key once)

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/key-requests/{request_id}/claim' \
  -H 'X-API-Key: <your sandbox key>'

List the tenant's team members

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/partner/users' \
  -H 'X-API-Key: <your sandbox key>'

Add a team member (partner-admin invites partner-clerk)

Request body — AddPartnerUserRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/users' \
  -H 'X-API-Key: <your sandbox key>'

Remove a team member (cannot remove yourself)

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/users/{user_id}/remove' \
  -H 'X-API-Key: <your sandbox key>'

List webhook endpoints (signing secrets are never re-shown)

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/partner/webhooks' \
  -H 'X-API-Key: <your sandbox key>'

Register a webhook endpoint (HMAC secret shown once)

Deliveries are signed with `X-NDAS-Signature` (HMAC-SHA256 over the raw body using the returned secret). HTTPS destinations only.

Request body — CreateWebhookRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/webhooks' \
  -H 'X-API-Key: <your sandbox key>'

Delete a webhook endpoint

Parameters

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/webhooks/{webhook_id}/delete' \
  -H 'X-API-Key: <your sandbox key>'

Usage aggregates (per day / per key / per endpoint)

Served from the ClickHouse metering store; when it is unreachable the endpoint fails SOFT to daily Postgres rollups (`source: rollup`) with calls only — error/latency fields are null.

Parameters

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/partner/usage' \
  -H 'X-API-Key: <your sandbox key>'

The tenant's invoices, newest first

Responses

Try it (sandbox)

curl -X GET \
  'https://sandbox.n.das.ug/v1/partner/invoices' \
  -H 'X-API-Key: <your sandbox key>'

Record an explicitly captured consent (clerk verification tool)

The clerk attests the data subject granted consent for an address verification of the named address (Uganda DPPA 2019). The record stores hashed/normalized subject identifiers only — a raw NIN is rejected before any processing. The returned `consent_reference` is quoted by the subsequent `/v1/kyc/address-match` call, which enforces BOTH the address-bounded and subject-bounded scope of the consent. Recording is audited.

Request body — RecordConsentRequest

Responses

Try it (sandbox)

curl -X POST \
  'https://sandbox.n.das.ug/v1/partner/consents' \
  -H 'X-API-Key: <your sandbox key>'