Interpreting Results
Use this guide to interpret Verify results and decide when to accept a record, ask for a correction, or handle a failed request.
A 200 response means the request was processed. Address validation reports a nextAction. Email and phone validation report valid alongside individual checks. These results do not establish that a person owns the address, mailbox, or phone number.
Address validation
Address decisions
Validation bases nextAction on the first candidate's match quality:
nextAction | Meaning | Suggested handling |
|---|---|---|
ACCEPT | The first candidate has Exact match quality | Accept the address and retain its ID |
ACCEPT_WITH_CHANGES | The first candidate has Confident match quality | Show the returned address and ask the user to confirm changes |
DENY | No candidate was found, or its quality was neither Exact nor Confident | Ask for a correction or send the record for review |
A denied result can still contain id and formatted from a lower-quality candidate. Their presence does not override DENY. These fields are omitted when no candidate provides them.
These response excerpts show the three decisions. They are illustrative, rather than a promise of the result for a particular query:
Code
Code
Code
If no candidate is found, the excerpt is simply {"nextAction":"DENY"}.
Mailpoint validation
Mailpoint matches against the Australia Post Postal Address File (PAF). It returns a Delivery Point Identifier (DPID) and postal attributes when a match is available.
| Field | How to use it |
|---|---|
properties.dpid | Keep the DPID as a string. 00000000 is the no-match sentinel |
properties.formatted | Review the matched postal address |
properties.barcode | A 4-State barcode encoded as bar-state digits 0–3, rather than an image |
matchScore | Postal match score from 0 to 100. It is not a probability. 0 means no match |
matchType | Returned postal match level, when available. A street or locality match does not confirm a specific delivery address |
pafVersion and pafExpiry | PAF release and expiry date |
geometry | Physical location, when available. A postal-only match can have no geometry |
A no-match response includes matchScore: 0 and properties.dpid: "00000000". It omits the barcode and formatted address. Do not treat the sentinel DPID as a successful match.
Mailpoint accepts a single query containing the postal address to validate.
A returned DPID alone does not establish eligibility for postal discounts. See the Australia Post Data Guide for mailing requirements.
Phone validation
Parsing either fails, leaving meta.checks_performed: ["parse"], or succeeds and is followed by validate, format, and location.
Parsing and input formats
Use an explicit country code for international numbers. Numbers without a country code are interpreted as Australian numbers.
Spaces, brackets, dashes, and dots between digits are accepted. The parser also recognises a national trunk prefix, a + country code, and an international dialling prefix such as Australia's 0011.
The following masked examples illustrate input formats and the corresponding format.e164: "+12025xxxxxx". The x characters hide digits and must be replaced before testing:
Code
input.phone echoes the supplied value. The request accepts 1–40 characters. An empty, missing, or over-40-character field returns 400.
A non-empty value such as abc returns 200 with valid: false, an empty format, and only the parse check. The number_details object remains present with type: "unknown", false possible and valid values, and timezones: [].
Possible and valid numbers
number_details.possible | valid | Meaning |
|---|---|---|
true | true | The number has a plausible length and matches a valid numbering range |
true | false | The length is plausible, but the number does not match a valid range |
false | false | The length is not plausible for that country's numbering plan |
A number can parse and still be invalid. The reference illustrates this with a masked Australian number, 1800 xxx xxxx. Its formats are returned because the underlying number parsed successfully.
valid: true does not confirm that the number is connected, reachable, or owned by the user. reachable currently always returns not_checked.
Formats
| Field | Use |
|---|---|
format.e164 | Canonical form for storage and comparison, such as +12025xxxxxx |
format.international | Readable international form, such as +1 202-5xx-xxxx |
format.national | Readable national form, such as (202) 5xx-xxxx |
format.rfc3966 | A tel: URI for links, such as tel:+1-202-5xx-xxxx |
Formats are returned whenever parsing succeeds, including for invalid numbers. Missing values are omitted rather than returned as null.
Number details
country_code,region_code, andcountry_nameidentify the number's country or region when availablelocationdescribes the geographic area associated with the number's prefix. It is not the phone's live location- Australian mobile and non-geographic numbers can omit
location. Check that the field exists before using it timezonescontains IANA timezone names associated with the numbering range. It can contain several zones or be empty
number_details.type | Meaning |
|---|---|
fixed_line | Landline |
mobile | Mobile number |
fixed_line_or_mobile | A range that can contain either fixed lines or mobiles, common in the US |
toll_free | Toll-free number |
premium_rate | Premium-rate number |
shared_cost | Shared-cost number |
voip | Voice over IP number |
personal_number | Personal numbering service |
pager | Pager number |
uan | Universal access number |
voicemail | Voicemail service |
unknown | Type could not be determined, including unparsed input |
Email validation
meta.checks_performed contains syntax, followed by dns only when syntax passes. valid is true only when syntax.valid and domain.has_mx are both true. Mailbox and domain categories do not change that verdict.
Syntax and normalisation
Example mailbox names are masked with xxx. The API trims surrounding whitespace and lowercases the domain. It preserves the local part, which can be case-sensitive under RFC 5321. input.email echoes the supplied value and syntax.normalized shows the value checked.
For example, " Xxx@EXAMPLE.COM " becomes "Xxx@example.com".
The request accepts 1–320 characters. A non-empty value can fit that request limit and still return valid: false because it fails syntax checks:
- The normalised address must be at most 254 characters, with a local part of at most 64 characters
- Both sides of
@must be present. The domain must contain a dot and a supported alphabetic suffix - The local part must not begin or end with a dot, contain consecutive dots, or contain unsupported characters
- Domain labels must not be empty or begin or end with a hyphen
- Internal whitespace, quoted local parts, address literals, and non-ASCII mailbox characters are not accepted by this syntax check
An empty, missing, or over-320-character email is a 400 request error. A non-empty malformed address within the request limit returns 200 with syntax.valid: false. No DNS lookup runs and the domain object is omitted. mailbox.group is still returned.
Domain and mailbox categories
| Field | Meaning |
|---|---|
mailbox.group | The local part matches a recognised role address, such as sales or info. Matching ignores case |
domain.consumer_email_provider | The domain is a known consumer email provider |
domain.disposable | The domain is known to provide disposable email |
Choose your own handling for these categories. A disposable or role address can still have valid: true. A false category flag does not prove that an address belongs to an individual or a particular organisation.
DNS and mail servers
domain.exists | domain.has_mx | Meaning |
|---|---|---|
true | true | At least one usable mail exchanger was found |
true | false | The domain publishes no usable MX record, including a null MX |
false | false | The domain was not found in DNS |
domain.mx_records lists mail exchangers by ascending priority. A lower value is preferred. An empty list accompanies has_mx: false.
A null MX, defined by RFC 7505, is an MX record with priority 0 and target .. It explicitly states that the domain accepts no email. example.com publishes one, so the Quickstart example returns valid: false even though its syntax is valid.
A DNS timeout or lookup failure returns 500. Handle this as a request failure rather than concluding that the domain has no mail server.
The API does not contact a mailbox to confirm it exists or accepts mail. valid: true confirms syntax and usable MX records only.
Other address operations
Suggestions and locations
- Autocomplete returns
resultscontainingid,formatted,type, and a rank starting at1. Use the chosen ID to retrieve address details - Geocoding and reverse geocoding return a
FeatureCollection. Each feature has point geometry, an optional address ID, andproperties.formattedwhen available - Reverse geocoding can include
matchDistance, in metres from the supplied point to the returned address point. A nearby result is not proof that the user intended that address - An empty
resultsorfeaturesarray indicates no match. Ask for a more complete address or check the supplied coordinates
Geometry uses GDA94 (EPSG:4283). Point coordinates use [longitude, latitude] order. These operations do not expose a request CRS selector.
Address details
Use address info with an ID returned by validation, geocoding, or autocomplete. It returns a single Feature with address properties. The address label is named formatted.
- Check for geometry before using it. Some records have no physical location
- An unknown ID returns
200with emptyproperties - An invalid ID format returns
400. Correct the request rather than treating it as an unknown address
Request metadata and failures
Email and phone responses include meta.checks_performed, meta.billable_units, meta.request_id, and meta.processing_ms. Use the check list to see which stages ran. Quote the request ID when contacting support. Processing time is measured in milliseconds and varies by request.
Successful Verify responses include input, attribution, requestTimeStamp, and requestDateTime. requestTimeStamp uses Unix seconds and requestDateTime uses UTC. Error responses use the structure below.
Verify errors
Verify service errors use a structured errors array:
| Field | Meaning |
|---|---|
error_count | Number of entries in errors |
errors | Objects containing a type, description, and an optional field |
input | Submitted body, including invalid values or rejected fields. Malformed JSON can be echoed as a raw string |
attribution | Data attribution notice |
timestamp | Unix timestamp in seconds. Success responses use requestTimeStamp instead |
requestDateTime | UTC date and time of the error |
For example, address validation with an empty body returns 400:
Code
Use errors[].type and errors[].field for application handling. The description can vary. field is omitted when no request field can be identified, such as a JSON syntax error. Nested paths use dot notation, for example items.2.query.
| Error type | Meaning | Handling |
|---|---|---|
validation | A request field or JSON body failed validation | Correct the identified field or JSON syntax |
authentication | Authentication failed | Check the Consumer Key and application access |
authorization | The request is not permitted | Check product access and the operation's plan requirements |
not_found | A route or requested resource was not found | Check the path and identifier |
rate_limit | A request-rate limit was reached | Retry with bounded backoff |
request | Another request error, such as an unsupported query parameter or HTTP method | Check the status and description and correct the request |
server | Service or lookup failure | Retry transient failures with backoff and contact support if they persist |
Local request validation returns 400. Service failures return 500 with errors[].type: "server" and description: "API request failed, please contact support".
Read the HTTP status first. A processed no-match or invalid result is 200 and follows the validation result schema, rather than the error schema. Check the result fields to determine whether a match was found. Keep contact details out of error logs because input can echo them.
Gateway authentication or rate-limit failures may return a different error body. Handle their HTTP status even when the body differs. See Error Handling and Rate Limiting.