AddressFinder

Search Australian addresses by partial text and return ranked completions, each with its `full_address`, its `id` and the `canonical_address_id` of the official address behind it. This is the lookup the Australian metadata and verification tools take their `id` from -- call it first when an address arrives as free text. `q` is required by this integration. AddressFinder itself accepts its absence and answers 200 with an EMPTY completions array (measured 2026-09-23), which is indistinguishable from a genuine no-match -- so an empty result from this tool always means the search really found nothing, never that an argument was left out. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The full structured record for ONE Australian address: street number, unit and level, locality, state, postcode, the assembled address lines, latitude and longitude, the G-NAF id, the Australia Post DPID, meshblock, SA1/SA2 and local-government area. SUPPLY EXACTLY ONE IDENTIFIER -- `id` (from the autocomplete tool), `gnaf_id` or `dpid`. Measured 2026-09-23, a call with none of them answers 400 'Specify an id, a gnaf_id, or a dpid'. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Match one free-text Australian address against the official datasets in a single call and return `matched` plus the full structured record when it matches -- the tool for cleaning an address you already hold, where the autocomplete/metadata pair is for one a person is typing. AT LEAST ONE DATASET MUST BE NAMED: measured 2026-09-23, a call with neither `gnaf` nor `paf` answers 400 'Supply at least one of gnaf=1 or paf=1, to specify the dataset to verify against', although AddressFinder's spec marks both as defaulting to 1. Agentic Fabriq sends `gnaf=1&paf=1` when you name neither, so the call works either way; set one of them to search that dataset alone. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Search Australian LOCATIONS rather than street addresses -- localities, streets, postcodes and states -- and return completions with `full_location`, `location_type`, `state_territory` and the `id` the Australian location metadata tool reads. Use this when the answer is an area ('Carlton VIC 3053') rather than a delivery point. `q` is required by this integration. AddressFinder itself accepts its absence and answers 200 with an EMPTY completions array (measured 2026-09-23), which is indistinguishable from a genuine no-match -- so an empty result from this tool always means the search really found nothing, never that an argument was left out. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The structured record for ONE Australian location: its `full_location`, `location_type`, locality, state or territory, postcode, street parts where it is a street, and its latitude and longitude. `id` comes from the Australian location autocomplete tool. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Search addresses in one of AddressFinder's INTERNATIONAL countries by partial text and return completions with `full_address` and the `id` the international metadata tool reads. THIS IS NOT THE AUSTRALIAN OR NEW ZEALAND PRODUCT: `country` accepts be, ca, cz, de, dk, es, fr, gb, ie, nl, pt, se, sg, us and REFUSES `au` and `nz` (measured 2026-09-23 -- 400 'Country contains an unsupported country code', although AddressFinder's own specs page lists both). Use the dedicated Australian and New Zealand tools for those two. `q` is required by this integration. AddressFinder itself accepts its absence and answers 200 with an EMPTY completions array (measured 2026-09-23), which is indistinguishable from a genuine no-match -- so an empty result from this tool always means the search really found nothing, never that an argument was left out. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The structured record for ONE international address: an `address` object with the assembled lines, locality, region and postcode, and a per-country `metadata` object. `id` comes from the international autocomplete tool and `country` must be the SAME country it was searched in. Refuses `au` and `nz` exactly as the autocomplete tool does; supported: be, ca, cz, de, dk, es, fr, gb, ie, nl, pt, se, sg, us. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Check one email address and report `is_verified`, `deliverability`, whether the domain is disposable, a role address (`support@`, `info@`), a public mailbox provider or a catch-all, plus `not_verified_code`/`not_verified_reason` when it fails. THIS TOOL DOES NOT TAKE `q` -- the argument is `email`. Measured 2026-09-23, omitting it answers 400 'Email can't be blank' although AddressFinder's spec marks it optional, and sending `q` instead answers the same 400, which reads like an auth or routing failure and is neither. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Search New Zealand addresses by partial text and return ranked completions, each with its display string `a` and its `pxid` -- the identifier the New Zealand metadata tool reads. Call this first when an address arrives as free text. `q` is required by this integration. AddressFinder itself accepts its absence and answers 200 with an EMPTY completions array (measured 2026-09-23), which is indistinguishable from a genuine no-match -- so an empty result from this tool always means the search really found nothing, never that an argument was left out. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The full structured record for ONE New Zealand address: street, suburb, mailtown, postcode, the three postal lines, latitude and longitude, the LINZ AIMS id and SUFI, the NZ Post DPID, territorial authority, ward, constituency, meshblock and SA1/SA2. SUPPLY ONE IDENTIFIER -- `pxid` (from the autocomplete tool) or `dpid`. Measured 2026-09-23, a call with neither answers 400 'Specify a pxid or dpid'. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The New Zealand addresses nearest a longitude/latitude pair, nearest first, each with its display string `a` and its `pxid`. `x` is LONGITUDE and `y` is LATITUDE -- that order, and New Zealand latitudes are negative. Measured 2026-09-23, omitting either answers 400 'X is not a number; Y is not a number'. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Match one free-text New Zealand address against the official dataset in a single call and return the full structured record with `matched` -- the tool for cleaning an address you already hold, where the autocomplete/metadata pair is for one a person is typing. `q` is required: measured 2026-09-23, a call without it answers 400 'Raw query can't be blank'. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Search New Zealand LOCATIONS rather than street addresses -- streets, suburbs, cities and regions -- and return completions with their display string `a` and the `pxid` the New Zealand location metadata tool reads. The four boolean switches choose which kinds of place are searched; omit them all to search every kind. `q` is required by this integration. AddressFinder itself accepts its absence and answers 200 with an EMPTY completions array (measured 2026-09-23), which is indistinguishable from a genuine no-match -- so an empty result from this tool always means the search really found nothing, never that an argument was left out. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The structured record for ONE New Zealand location: its display string, suburb, city, region, postcode and its longitude (`x`) and latitude (`y`). `pxid` comes from the New Zealand location autocomplete tool. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Search New Zealand POINTS OF INTEREST by name -- buildings, complexes and named places -- and return completions with `name_and_address` and the `id` the point-of-interest metadata tool reads. This is the tool for 'the address of <a named building>', which the address autocomplete cannot answer. `q` is required by this integration. AddressFinder itself accepts its absence and answers 200 with an EMPTY completions array (measured 2026-09-23), which is indistinguishable from a genuine no-match -- so an empty result from this tool always means the search really found nothing, never that an argument was left out. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

The structured record for ONE New Zealand point of interest: its name, its longitude and latitude, and the full postal address behind it including the `address_pxid` that the New Zealand address metadata tool will expand. `id` comes from the point-of-interest autocomplete tool. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).

Check one phone number and report `is_verified`, `line_type` (mobile, landline, VOIP), `line_status` (connected or not) and the number in national and international formats. THIS TOOL DOES NOT TAKE `q` -- the arguments are `phone_number` and `default_country_code`, and BOTH are required in practice: measured 2026-09-23, omitting the country code answers 400 'Default country code can't be blank' even for a number that resolves. Every response carries `success`; a refusal carries `message` and a numeric `error_code` under HTTP 400 (AddressFinder never answers 401 for a bad key).