Platform endpoints — address

How to call the address routes. The formal schema is the OpenAPI specification (openapi/source/platform/address/address.yml); this page is the call contract.

Auth

Both routes require a bearer token (B2B JWT) with the CLIENT role. No party context is required — these endpoints are typically called during onboarding flows before a party exists.

Method	Path	Code	Purpose
`GET`	`/v1/address/autocomplete`	`200`	Address suggestions for free text
`GET`	`/v1/address/metadata`	`200`	Full PAF detail for a selected suggestion

`GET /v1/address/autocomplete` — autocomplete search

Returns a list of address suggestions for the query string.

Param	In	Required	Notes
`query`	query	✓	Must contain at least 4 alphabetic characters (pattern `^(.[a-zA-Z]){4,}.$`); rejected with `400` otherwise. Only call again when the input changes.

Response — AutoCompleteResponse:

{
  "data": [
    { "id": "a4c4f26d-…-a354", "canonicalId": "a4c4f26d-…-a354", "address": "Unit 2, 21 Kent Road, DAPTO, NSW, 2530" },
    { "id": "a4c4f26d-…-a355", "canonicalId": "a4c4f26d-…-a355", "address": "Unit 2, 21 Kent Road, DUNBOGAN, NSW, 2443" },
  ],
}

id (= canonicalId) is the record identifier — pass it to /v1/address/metadata.
No matches returns { "data": [] } (not an error).
Known limitation: the result count is not deterministic for a repeated query. The address provider may return a different number of suggestions across calls for the same input. Do not rely on a stable count.

`GET /v1/address/metadata` — address metadata

Resolves a single suggestion to its full structured address (CommonPAFAddress — Australia Post PAF fields).

Param	In	Required	Notes
`id`	query	✓	The `id`/`canonicalId` from an autocomplete result

Response — MetadataResponse:

{
  "data": {
    "dpid": "57146497",
    "addressLine": "Suite 12, 100 George St, Sydney, NSW, 2000",
    "flatUnitType": "Suite",
    "flatUnitNumber": "12",
    "floorLevelType": null,
    "floorLevelNumber": null,
    "streetName": "George",
    "streetType": "Street",
    "localityName": "Sydney",
    "postcode": "2000",
    "state": "NSW",
  },
}

dpid is always present. All other fields are optional. state is normalised to one of ACT, NSW, NT, QLD, SA, TAS, VIC, WA.

Errors

HTTP	Code	When
`400`	`GEN000000`	`query` fails validation (fewer than 4 alphabetic characters)
`404`	`ADR004001`	Metadata: the provider returned no result for the `id`
`422`	`ADR022001`	Metadata: the provider returned a result with no usable record
`500`	`ADR100004` / `ADR100005`	The provider call failed (`ADR100005 ADDRESS_CONNECTOR_ERROR`) or returned an unsupported address type (`ADR100004 UNSUPPORTED_ADDRESS_TYPE`) — these are the only `ADR1xxxxx` codes defined

Auth​

GET /v1/address/autocomplete — autocomplete search​

GET /v1/address/metadata — address metadata​

Errors​

Auth

`GET /v1/address/autocomplete` — autocomplete search

`GET /v1/address/metadata` — address metadata

Errors