# Postal Address Matching

Use this guide to match postal addresses with MailPoint, interpret DPID diagnostics, and request a barcode.

MailPoint matches an Australian postal address against the Australia Post Postal Address File (PAF). A match can return a Delivery Point Identifier (DPID), a postal address, and a 4-State barcode for mail preparation. Use this workflow when you need postal matching rather than a location alone.

The Address Matching Approval System (AMAS) is Australia Post's certification program for address-matching software. Postal discount eligibility also depends on Australia Post's mailing requirements. A returned DPID alone does not establish eligibility. See the [Australia Post Data Guide](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf).

## Before you begin

Use a Geoscape Hub application with Addresses API access on an eligible paid plan. Send the Consumer Key directly in the `Authorization` header.

## Match a postal address

```shell
curl --fail-with-body --get \
  "https://api.psma.com.au/v2/addresses/mailPoint" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "address=113 Canberra Ave Griffith ACT 2603" \
  --data-urlencode "matchType=address" \
  --data-urlencode "barcodeFormat=67Bar"
```

Choose an input format:

- A single-line `address`.
- Multi-line input starting with `addressLine1`, with optional `addressLine2` and `addressLine3`.
- Structured address components. For postal delivery input, use `postalDeliveryTypeCode` and `postalDeliveryIdentifier`, such as `PO BOX` and its number.

See the [MailPoint parameter reference](/reference/addresses-v2-address-search#mailpoint/query-parameters) for the full input contract.

## Choose the accepted postal match level

For delivery-address matching, use `matchType=address` to require an address-level DPID match. MailPoint accepts a single value, unlike the geocoder's comma-separated category filter. Broader levels allow less detailed matches. See the [MailPoint parameter reference](/reference/addresses-v2-address-search#mailpoint/query-parameters).

Read the returned `matchType` to see the actual level. A street or locality match does not confirm a specific delivery address.

## Read the response

A processed request returns `200` and a JSON GeoJSON `Feature`. Check these fields:

| Field | Meaning |
| --- | --- |
| `properties.dpid` | Australia Post Delivery Point Identifier. Keep it as a string. |
| `properties.formattedAddress` | Matched postal address label |
| `properties.barcode` | String of bar-state digits `0`–`3`, rather than a barcode image |
| `matchType` | Actual postal match level: `address`, `street`, or `locality` |
| `matchDiagnostic` | Diagnostic code for the match |
| `matchDiagnosticMessage` | Human-readable explanation of the diagnostic |
| `matchScore` | Postal match score (`0` for no match) |
| `pafVersion` and `pafExpiry` | PAF release and expiry date |

Review the formatted address, match level, and diagnostics before using the DPID. MailPoint scores are postal-matching metadata. Do not apply the geocoder's quality labels or score assumptions to them.

By default, a no-match result has:

- `matchScore: 0`.
- `messages: ["No address could be matched"]`.
- No matched `properties`, `geometry`, or postal match diagnostics.

Handle missing fields before reading a DPID or barcode. A `200` response means the request was processed, not that a postal address matched.

## Choose a barcode format

Choose `37Bar` when you need the DPID alone, or a longer format when you need to encode customer data. The default is `67Bar`. Customer data beyond the selected format’s capacity is truncated. See the [barcode parameters](/reference/addresses-v2-address-search#mailpoint/query-parameters) for lengths and input limits.

Barcode generation does not turn an unmatched postal address into a valid DPID match.

## Geometry and related attributes

Geometry is added when the postal address can be linked to a physical address. Postal-only addresses, such as PO boxes, can have a valid postal match without geometry. Do not use geometry presence as the success test for MailPoint.

When geometry is available, `additionalProperties` can retrieve linked attributes. Premium properties require paid-plan access and can incur surcharges. See [Additional Properties](/guides/addresses/additional-properties). Use `Accept-Crs` to select the response geometry's CRS. The default is GDA94.

## Costs and failures

MailPoint uses `2` base credits per processed MailPoint request, including no-match results. Returned solar, parcel, or property bundles can add credit costs. See [Additional Properties](/guides/addresses/additional-properties) for surcharge calculations.

Follow [Error Handling](/guides/errors) for request failures and retries, [Rate Limiting](/guides/rate-limiting) for request rates, and [Attribution](/guides/attribution) for data notices.

## Next steps

- [Review the MailPoint endpoint](/reference/addresses-v2-address-search#mailpoint)
- [Use geocoding for physical address matches](/guides/addresses/quickstart)