Verify API Quickstart
Use this guide to validate your first Australian address, then try Mailpoint, phone, or email validation.
Before you begin
You need:
- A Geoscape Hub account and an API key with access to the Verify products you will use
- A terminal with
curlandjqinstalled. The first example usesjqto read the JSON response
Plan access depends on the operation:
- Address validation, geocoding, reverse geocoding, info, and autocomplete are available on Free and paid plans
- Mailpoint, phone validation, and email validation require paid-plan access
See Verify access for the access rules.
If you do not have an API key, follow Authentication first.
Verify base URL: https://api.geoscape.com.au. Endpoint paths start with /v1/verify. Use this base URL for every request below.
1. Set your API key
Store the Consumer Key outside source code. Replace the placeholder below with your application's key:
Code
The header name is Authorization and its value is the Consumer Key directly. Do not prefix it with Bearer.
2. Validate an Australian address
Send the address as a JSON request body. Content-Type: application/json tells the API how to parse it; JSON-aware clients set this header automatically, while raw-body requests must set it explicitly.
Code
AUselects Australian coverage, the only supported address coverage valuequeryis required and accepts 1–200 characters- Send request fields in the JSON body. Unsupported body fields return
400
A successful request returns 200 OK. This illustrative exact-match response shows the address decision. Live results can differ:
Code
3. Read the address decision
Use nextAction before accepting an address:
ACCEPT: the first candidate has Exact match qualityACCEPT_WITH_CHANGES: the first candidate has Confident match quality. Ask the user to confirm the returned addressDENY: ask for a correction or review. A denied result can still include a lower-quality candidate'sidandformatted
A 200 response means the check completed, not that the address was accepted. Fields unavailable from a candidate are omitted.
4. Try another Verify check
Each endpoint checks one record and accepts JSON. Choose the operation you need.
Match a postal address with Mailpoint
Code
query is required and accepts 1–200 characters. Read matchScore, properties.dpid, and the returned postal address. A no-match response uses matchScore: 0 and properties.dpid: "00000000". Do not accept that sentinel DPID.
Validate and format a phone number
Code
The number is masked. Replace the x characters with a number you are authorised to validate before testing.
phone is required and accepts 1–40 characters. This fictional US number has an explicit country code. Numbers without a country code are interpreted as Australian numbers.
Use format.e164 for storage and comparison. valid checks the numbering range and does not confirm ownership or a live connection.
Check an email address
Code
email is required and accepts 1–320 characters. example.com publishes a null MX record, indicating that it accepts no email. Expect 200 with valid: false, syntax.valid: true, and domain.has_mx: false.
A true verdict confirms syntax and usable mail servers. It does not confirm mailbox existence. Role, consumer-provider, and disposable-email flags help you set your own acceptance policy.
See Interpreting Results for check definitions, omitted fields, and further examples. Address autocomplete, geocoding, and reverse geocoding are covered under Other address operations.
5. Retrieve address details (optional)
After an accepted result provides an ID, retrieve its details. This command reads the ID from the saved validation response and builds the JSON body:
Code
If this command succeeds, run:
Code
The response is a Feature containing address properties and geometry when available. An unknown ID returns 200 with empty properties.
Credit usage and request rates
| Operation | Credits per processed request |
|---|---|
| Address autocomplete | 0.1 |
| Address validation, geocoding, reverse geocoding, or info | 1 |
| Email or phone validation | 1 |
| Mailpoint | 2 |
Read x-attr-basicTransaction for the credit cost. Processed invalid or no-match results still incur these costs. An access refusal is not charged.
Request-rate limits are separate from credit usage. Follow your subscription's allowance and see Rate Limiting for throttling and retry guidance.
If a request fails
| Status | What to check |
|---|---|
400 | Required fields, input lengths, JSON syntax, and unsupported body fields. Email and phone endpoints also reject query parameters. Correct the request |
401 | Consumer Key and application access |
403 | Product access. Mailpoint, phone, and email validation require a paid plan |
429 | Request rate. Follow your subscription allowance and retry with backoff |
500 | Service or lookup failure. Retry transient failures with backoff and contact support if they persist |
Verify service errors contain error_count, a structured errors array, echoed input, attribution, timestamp, and requestDateTime. Success responses use requestTimeStamp instead of timestamp. Gateway errors can have a different body. Inspect the HTTP status first and keep API keys and contact data out of your logs. See Verify errors for the error example and recovery guidance.
Next steps
- Interpret address and contact results
- Choose a Verify operation
- Handle errors and retries
- Apply request-rate limits