# Verify API

Use this page to choose a Verify operation, prepare your first request, and find guidance on interpreting contact and address checks.

## When to use this API

Validate Australian addresses, match postal addresses with Mailpoint, and check phone numbers and email addresses before accepting contact data.

Start with the [Verify Quickstart](/guides/verify/quickstart) to validate an address, then try Mailpoint, phone, or email validation.

| You want to… | Use |
| --- | --- |
| Suggest addresses as someone types | [Autocomplete](/reference/verify-v1-autocomplete#autocomplete) |
| Decide whether to accept, confirm changes to, or review an Australian address | [Address validation](/reference/verify-v1-address#validate-3) |
| Match an Australian postal address and retrieve its DPID and available barcode | [Mailpoint validation](/reference/verify-v1-mailpoint#validate-4) |
| Check a phone number's numbering range and retrieve standard formats | [Phone validation](/reference/verify-v1-phone#validate-2) |
| Check email syntax, mail servers, and mailbox or domain categories | [Email validation](/reference/verify-v1-email#validate) |
| Find address candidates and coordinates from address text | [Geocode](/reference/verify-v1-address#geocode) |
| Find addresses near latitude and longitude | [Reverse Geocode](/reference/verify-v1-address#reverse-geocode) |
| Retrieve details for a known address ID | [Info](/reference/verify-v1-address#info) |

## Access

Use a Geoscape Hub application with access to the Verify products you need. Send its Consumer Key directly in the `Authorization` header. See [Authentication](/guides/authentication) for application and tester setup.

| Operation or data | Access required |
| --- | --- |
| Address validation, geocoding, reverse geocoding, and info | Free or paid plan |
| Autocomplete | Free or paid plan |
| Mailpoint | Paid-plan access |
| Phone or email validation | Paid-plan access |

## API conventions

- **Base URL:** use `https://api.geoscape.com.au`. Endpoint paths start with `/v1/verify`
- **Requests:** submit one record as a JSON object in the `POST` body with `Content-Type: application/json`. JSON-aware clients set this header for you; if you send a raw body, set it explicitly. Address operations support `AU` coverage. Phone numbers can use international numbering ranges when a country code is supplied
- **Address decisions:** read `nextAction` for an acceptance recommendation
- **Postal no-match results:** Mailpoint returns the sentinel DPID `00000000`. Treat this as no match
- **Service errors:** read `error_count` and `errors` objects containing `type`, `description`, and an optional `field`. Errors use `timestamp` instead of the success field `requestTimeStamp`, alongside echoed `input`, attribution, and `requestDateTime`. Gateway authentication and rate-limit errors can have a different body. See [Verify errors](/guides/verify/interpreting-results#verify-errors)

## Responses

- Each operation accepts one JSON request body. Unsupported body fields return `400`. Email and phone endpoints also reject query parameters
- `200` means the check completed. It can include a denied address, invalid contact detail, or no match
- Address validation returns `nextAction`. Email and phone validation return `valid` and individual check results
- Email validation does not confirm mailbox existence. Phone validation does not confirm connection, ownership, or live location
- Address geometry uses GDA94 (EPSG:4283), with point coordinates in `[longitude, latitude]` order
- Retain the `attribution`. Credit costs vary by operation and are reported in `x-attr-basicTransaction`

## Further guidance

- [Interpreting Results](/guides/verify/interpreting-results): handle address, Mailpoint, phone, and email validation results
- [Error Handling](/guides/errors), [Rate Limiting](/guides/rate-limiting), and [Attribution](/guides/attribution): apply shared integration requirements

## Versions

| Version | Reference |
| --- | --- |
| v1 (current) | [Endpoint reference](/reference/verify-v1-address) |