Data Quality

Address Verification

Validate shipping addresses before they reach the carrier. Catch empty fields, character limit violations, postcode-suburb mismatches, and formatting issues to reduce failed deliveries and carrier rejections.

How It Works

Step 01

Submit Address

Send the address to the verification endpoint before or during shipment creation.

Step 02

Instant Validation

Engine runs 8+ checks: empty fields, character limits, postcode-suburb match, state validation, and more.

Step 03

Get Results

Receive a structured response with pass/fail/warning per field, with suggested corrections.

Validation Rules

Each address passes through the following checks. Rules are evaluated in order; errors block shipment creation, warnings flag for review.

Carrier Character Limits

Each carrier enforces different maximum character lengths. The verification engine validates against the specific carrier's limits when a carrier is specified, or uses the strictest limits across all carriers as a safe default.

Carrier	Line 1	Line 2	Suburb	Name	Phone
Australia Post	40	40	30	40	15
StarTrack	40	40	30	40	10
Team Global Express	35	35	30	35	15
Allied Express	35	35	30	35	15

Australian Postcode-State Mapping

The first digit of an Australian postcode indicates the state or territory. This mapping is used for quick postcode-state validation before checking the full suburb-postcode database.

Postcode Range	State	Note
1000–1999	NSW	PO Boxes only
2000–2599	NSW
2600–2618	ACT
2619–2899	NSW
2900–2920	ACT
2921–2999	NSW
3000–3999	VIC
4000–4999	QLD

Postcode Range	State	Note
5000–5799	SA
5800–5999	SA	PO Boxes only
6000–6797	WA
6800–6999	WA	PO Boxes only
7000–7799	TAS
7800–7999	TAS	PO Boxes only
0800–0899	NT
0900–0999	NT	PO Boxes only

Interactive Validator

Try the address verification engine. Enter an address below and click Validate to see the results in real-time.

POST /api/v1/addresses/verify — Live Demo

Recipient Name

Phone

Address Line 1 *14/40 characters

Address Line 20/40 characters

Suburb *

State *

Postcode *

Verification Flow

Address Verification Pipeline

┌─────────────────────────────────────────────────────────────┐
│                  Address Submitted                          │
│          POST /api/v1/addresses/verify                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
              ┌────────────────┐
              │  Required      │
              │  Fields Check  │──── FAIL ──▶ Return errors[]
              │  (empty/blank) │             "name is required"
              └───────┬────────┘
                      │ PASS
                      ▼
              ┌────────────────┐
              │  Character     │
              │  Length Check  │──── FAIL ──▶ Return errors[]
              │  (per carrier) │             "address_line_1 exceeds 40 chars"
              └───────┬────────┘
                      │ PASS
                      ▼
              ┌────────────────┐
              │  Postcode      │
              │  Format Check  │──── FAIL ──▶ Return errors[]
              │  (4 digits)    │             "postcode must be 4 digits"
              └───────┬────────┘
                      │ PASS
                      ▼
              ┌────────────────┐
              │  Postcode ↔    │
              │  State Match   │──── FAIL ──▶ Return errors[]
              │                │             "postcode 3000 is VIC, not QLD"
              └───────┬────────┘
                      │ PASS
                      ▼
              ┌────────────────┐
              │  Postcode ↔    │
              │  Suburb Match  │──── FAIL ──▶ Return errors[]
              │  (AusPost DB)  │             + suggested suburbs[]
              └───────┬────────┘
                      │ PASS
                      ▼
              ┌────────────────┐
              │  Character     │
              │  Quality Check │──── WARN ──▶ Return warnings[]
              │  (ASCII, etc)  │             "non-ASCII chars detected"
              └───────┬────────┘
                      │ PASS
                      ▼
              ┌────────────────┐
              │   ✓ VERIFIED   │
              │                │──────────▶ Return { verified: true }
              └────────────────┘

API Endpoint

POST/api/v1/addresses/verify

Request Body

{
  "address": {
    "name": "John Smith",
    "company": "Acme Pty Ltd",
    "address_line_1": "42 Wallaby Way",
    "address_line_2": "Unit 4",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country": "AU",
    "phone": "0400000000",
    "email": "[email protected]"
  },
  "carrier": "australia_post",     // optional — validates against carrier-specific limits
  "suggest_corrections": true      // optional — returns suburb suggestions on mismatch
}

Success Response (200)

{
  "verified": true,
  "errors": [],
  "warnings": [],
  "normalized": {
    "suburb": "SYDNEY",
    "state": "NSW",
    "postcode": "2000"
  }
}

Failure Response (200)

{
  "verified": false,
  "errors": [
    {
      "field": "postcode",
      "code": "POSTCODE_SUBURB_MISMATCH",
      "message": "Postcode 2000 does not match suburb Melbourne",
      "suggestions": [
        { "suburb": "SYDNEY", "state": "NSW", "postcode": "2000" },
        { "suburb": "HAYMARKET", "state": "NSW", "postcode": "2000" },
        { "suburb": "THE ROCKS", "state": "NSW", "postcode": "2000" }
      ]
    }
  ],
  "warnings": [
    {
      "field": "address_line_1",
      "code": "NEAR_CHAR_LIMIT",
      "message": "Address line 1 is 38/40 characters — close to carrier limit"
    }
  ]
}

Integration with Shipment Flow

Address verification can be used standalone or integrated into the shipment creation pipeline. When enabled, shipments with invalid addresses are automatically blocked or flagged.

Pre-Shipment (Recommended)

Call /addresses/verify before creating a shipment. Fix issues before they reach the carrier.

POST /api/v1/addresses/verify
→ verified: true
POST /api/v1/shipments

Inline Validation

Add validate_address: true to the shipment creation request. The engine validates before processing.

POST /api/v1/shipments
{ validate_address: true, ... }
→ 422 if address invalid

Error Codes

Code	Severity	Description
REQUIRED_FIELD_MISSING	error	A required field (name, address_line_1, suburb, state, postcode) is empty
CHAR_LIMIT_EXCEEDED	error	Field exceeds the carrier's maximum character length
INVALID_POSTCODE_FORMAT	error	Postcode is not exactly 4 digits
POSTCODE_STATE_MISMATCH	error	Postcode does not belong to the specified state
POSTCODE_SUBURB_MISMATCH	error	Suburb is not valid for the given postcode
INVALID_STATE	error	State is not a valid Australian state/territory abbreviation
NON_ASCII_CHARS	warning	Address contains non-ASCII characters that may cause carrier rejection
EXCESSIVE_SPECIAL_CHARS	warning	Unusual pattern of special characters detected
PO_BOX_UNSUPPORTED	warning	PO Box address detected but carrier does not support PO Box delivery
NEAR_CHAR_LIMIT	warning	Field is within 5 characters of the carrier's maximum limit