Kleber connector — endpoints

How to call the connector. The formal schema is the OpenAPI specification (Address, openapi/source/connector/address/address.yml); this page covers the call contract and examples. Internal processing is in the architecture; caveats are in the connector notes.

Authentication

Both /v1/address/* endpoints require a bearer token (OAuth2 client-credentials JWT). Health endpoints are unauthenticated probes.

Method	Path	Auth	Purpose
`GET`	`/v1/address/autocomplete?query=`	✓	Address suggestions for free text
`GET`	`/v1/address/metadata?id=`	✓	Full PAF detail for a selected suggestion
`GET`	`/health` · `/health/readiness` · `/health/liveness`	—	Probes (see architecture)

`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 Kleber record id — pass it to /v1/address/metadata.
No matches returns { "data": [] } (not an error).
The result count is not deterministic for a repeated query — see the connector notes.

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

Resolves a single suggestion to its full structured address (CommonPAFAddress — Australia Post PAF fields: dpid, thoroughfare numbers, unit/level, street, locality, state, postcode, …).

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

Response — MetadataResponse:

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

state is normalised to one of ACT, NSW, NT, QLD, SA, TAS, VIC, WA.

Errors

HTTP	Code	When
`400`	`GEN000000`	`query` / `id` fails validation (e.g. fewer than 4 alphabetic characters)
`404`	`ADR004001`	Metadata: Kleber returned no result for the `id`
`422`	`ADR022001`	Metadata: Kleber returned a result with no usable record, or the address has a state code outside the supported AU set
`500`	`ADR100005`	Any Kleber call failed (the connector wraps downstream errors)

See the connector notes for how downstream failures are collapsed.

Authentication​

GET /v1/address/autocomplete — autocomplete search​

GET /v1/address/metadata — address metadata​

Errors​

Authentication

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

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

Errors