canonical: https://jentic.com/apis/addressfinder.com/addressfinder

# AddressFinder API

Jentic publishes the only available OpenAPI specification for AddressFinder API, keeping it validated and agent-ready. AddressFinder provides address autocomplete, verification, and metadata lookup tuned specifically for Australian and New Zealand postal addresses, plus an email verification endpoint. Each country has dedicated address search, address-info detail, location (suburb/postcode) search, and location-info endpoints, so agents can drive both type-ahead UX and back-end data quality checks. Authentication uses an API key passed as the key query parameter.

## For AI agents

Search and verify Australian and New Zealand addresses, look up suburbs and postcodes, and verify email addresses. Used by AU/NZ-focused checkout, signup, and CRM hygiene agents.

## Scope

Does not validate addresses outside Australia and New Zealand, calculate routes, or render maps - use for AU/NZ address autocomplete, verification, and email checks only.

## Capabilities

- Search Australian addresses with type-ahead matching to power autocomplete fields
- Retrieve full metadata for a specific Australian address including DPID and geocode
- Search New Zealand addresses with the same autocomplete pattern
- Look up suburb and postcode metadata for both AU and NZ locations
- Verify whether an email address is deliverable via the email verification endpoint
- Use the v2 Australian address endpoint for refined results when v1 returns ambiguous matches

## Use cases

### Address autocomplete on AU/NZ checkout

E-commerce stores shipping to Australia or New Zealand integrate AddressFinder's /au/address and /nz/address endpoints to power type-ahead address fields. As the shopper types, the API returns ranked candidates so the user picks a verified address in two or three keystrokes. This reduces invalid-address shipping errors and shortens checkout time noticeably.

Example prompt: On each keystroke after three characters, GET /au/address with q set to the partial input and return the top five candidates as suggestions.

### CRM address hygiene

Sales operations periodically clean their CRM by re-validating customer addresses. For each AU or NZ record, the agent calls /au/address/info or /nz/address/info to confirm the address still maps to a known DPID and to standardise formatting. Records that fail validation are flagged for manual review, while passes are upgraded with the canonical address string and geocode.

Example prompt: For each customer with country AU, GET /au/address/info with the existing address; if it returns a valid DPID, write the canonical formatted_address back to the CRM.

### Email verification on signup

Marketing teams want to suppress disposable, mistyped, or undeliverable emails before they reach the email service provider. The /email/v1/verification endpoint returns a deliverability verdict and metadata so signup forms can reject obvious bad inputs and the back-end can defer marketing sends for risky ones. This keeps sender reputation higher and reduces wasted credits.

Example prompt: On signup form submit, GET /email/v1/verification with the entered email and reject the form if the response status is 'undeliverable' or 'invalid'.

### AI agent address validation via Jentic

An AI agent in a contact-centre app uses Jentic to validate an Australian address dictated over the phone. The agent searches 'verify australian address', loads the GET /au/address/info schema, fills the address string from the transcript, and confirms the DPID match back to the operator. The AddressFinder API key never enters the agent's context - Jentic adds it from your Jentic One instance.

Example prompt: Use Jentic to search 'verify an australian address', load the GET /au/address/info schema, and execute with q set to the dictated address.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /au/address | Search Australian addresses |
| GET | /au/address/info | Get detailed Australian address information |
| GET | /nz/address | Search New Zealand addresses |
| GET | /nz/address/info | Get detailed New Zealand address information |
| GET | /au/location | Search Australian locations |
| GET | /nz/location | Search New Zealand locations |
| GET | /email/v1/verification | Verify an email address |

## Key resources

- **Australian Addresses** — Search and detail endpoints for Australian postal addresses, including a refined v2 search.
- **New Zealand Addresses** — Search and detail endpoints for New Zealand postal addresses.
- **Australian Locations** — Suburb and postcode search and metadata for Australia.
- **New Zealand Locations** — Suburb and postcode search and metadata for New Zealand.
- **Email Verification** — Single-call email deliverability check returning a status and metadata.

## Why Jentic

- **Setup:** Wiring the AddressFinder API by hand means appending the key query parameter on every call and juggling separate AU and NZ address and location endpoints without a published spec. Through Jentic you install once, import the AddressFinder API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** These endpoints are read-only lookups that take the key and query in the URL rather than a resource id in the path, so limit the agent to the operations it needs, such as autocompleting an Australian address. You choose the operations it may call, so New Zealand lookups or email verification are not included unless you add them.
- **Credential handling:** Your AddressFinder API key is stored once, encrypted, by your own Jentic One instance and appended to the key parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'autocomplete an australian address', and Jentic returns the matching AddressFinder operation with its input schema so the agent calls the right endpoint without browsing the reference docs, which matters because AddressFinder does not publish a public OpenAPI spec.

## Related APIs

- **HERE Maps API** — Global geocoding and mapping API covering many more countries than AU/NZ.
- **Geocodio API** — Address verification and geocoding focused on US and Canadian addresses.
- **Melissa Data API** — Global data quality suite covering address, name, email, and phone validation.

## FAQ

### Why is there no official OpenAPI spec for AddressFinder API?

AddressFinder does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AddressFinder API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AddressFinder API use?

AddressFinder uses an API-key scheme: a key issued in the AddressFinder dashboard is sent as the key query parameter. Jentic keeps the key in your Jentic One instance and appends it at execute time so it never appears in agent context, even though it travels on the URL.

### Can I look up Australian and New Zealand addresses with the same API key?

Yes. The /au/address and /nz/address endpoints share authentication - one key works for both countries. Use /au/address/v2 when v1 returns ambiguous matches and you want the refined ranking.

### How do I validate an address through Jentic?

Search Jentic for 'verify australian address' or 'verify new zealand address', load the GET /au/address/info or /nz/address/info schema, and execute with q set to the address string. The response includes the DPID, formatted address, and geocode.

### Are there rate limits on the AddressFinder API?

AddressFinder applies per-account credit and rate limits scaled to plan; the spec does not declare a fixed RPS value. When 429 responses occur Jentic surfaces them so retry logic can read the Retry-After header.

### Does this API support countries other than Australia and New Zealand?

No. The address-related endpoints are scoped to AU and NZ datasets only. For US, UK, or global address validation, use a competing provider such as Smarty, Loqate, or HERE.

### Can I limit what my agent is allowed to do with the AddressFinder API?

Yes. Because you run Jentic One self-hosted, your own rules decide which AddressFinder operations and credentials the agent may use. These endpoints are read-only lookups that pass the key and query in the URL, so you can allow just the ones the agent needs, such as autocompleting an Australian address through /au/address, while withholding New Zealand lookups or the /email/v1/verification endpoint. The API key is held by your Jentic One instance and appended only for the operations you have permitted.