Skip to content
Comms.ID
Esc
↑↓navigate↵open⌘Jpreview

POST /address/v1/validate

Check one typed address against the supported source. Not proof that mail can be delivered there.

  • Authentication: a short-lived signed token, Authorization: Bearer <token>. The audience is address-search and the scope is address.
  • Safe to repeat: yes. The client retries it after a retryable failure.
  • Agent tool: address.validate
POST/address/v1/validate
Request body
requiredapplication/json
addressstringrequired
Responses
200

Success

outcomestringrequired

match: one supported address equals the input; ambiguous: candidates exist but none equals it; no-match: nothing found.

Allowed:matchambiguousno-match
addressobject
Show properties
idstringrequired
min length 1 · max length 128
displayAddressstringrequired
min length 1
buildingNamestring
min length 1
lotobject
Show properties
prefixstring
min length 1
numberstringrequired
min length 1
suffixstring
min length 1
flatobject
Show properties
typestring
min length 1
numberstringrequired
min length 1
levelobject
Show properties
typestring
min length 1
numberstringrequired
min length 1
numberobject
Show properties
firstobjectrequired
Show properties
prefixstring
min length 1
valueintegerrequired
min 0
suffixstring
min length 1
lastobject
Show properties
prefixstring
min length 1
valueintegerrequired
min 0
suffixstring
min length 1
streetobject
Show properties
namestringrequired
min length 1
typestring
min length 1
suffixstring
min length 1
localitystringrequired
min length 1
statestringrequired
Allowed:ACTNSWNTQLDSATASVICWA
postcodestringrequired
countryCodestringrequired
Allowed:AU
candidatesobject[]required

Up to three candidates, for an ambiguous result.

max items 3
Show properties
Array of object
idstringrequired
min length 1 · max length 128
labelstringrequired
min length 1
secondaryLabelstring
min length 1
unitLabelstring
min length 1
matchedRangesany[][]required
400

The request body is not valid for this operation.

codestringrequired
Allowed:INVALID_INPUT
messagestringrequired
retryablebooleanrequired
requestIdstringrequired

The request's id, for support.

401

The request carries no identified caller (ADR-0018).

codestringrequired
Allowed:UNAUTHORIZED
messagestringrequired
retryablebooleanrequired
requestIdstringrequired

The request's id, for support.

410

This major version is retired (ADR-0050).

codestringrequired
Allowed:VERSION_RETIRED
messagestringrequired
retryablebooleanrequired
requestIdstringrequired

The request's id, for support.

429

The fair-use ceiling is reached; retry after Retry-After.

codestringrequired
Allowed:FAIR_USE_CEILING
messagestringrequired
retryablebooleanrequired
requestIdstringrequired

The request's id, for support.

503

The source is unavailable or the index is not ready.

codestringrequired
Allowed:UNAVAILABLE
messagestringrequired
retryablebooleanrequired
requestIdstringrequired

The request's id, for support.

Request
curl -sS -X POST https://api.comms.id/address/v1/validate \
  -H "Authorization: Bearer $COMMS_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"100 Harris St, Pyrmont NSW 2009"}' \
  -H "Accept: application/json"
Response
{
  "outcome": "match",
  "address": {
    "id": "GANSW710292212",
    "displayAddress": "100 HARRIS ST, PYRMONT NSW 2009",
    "number": {
      "first": {
        "value": 100
      }
    },
    "street": {
      "name": "HARRIS",
      "type": "ST"
    },
    "locality": "PYRMONT",
    "state": "NSW",
    "postcode": "2009",
    "countryCode": "AU"
  },
  "candidates": []
}