DOCS
HomeFor logistics providers Suggest and validate addresses

Suggest and validate addresses

Complete addresses as customers type, and confirm an address before you ship to it.

GraphQL

Use locationSuggest to offer complete addresses while a customer types, and locationValidate to check an address and get it back in a standardized form. When an address validates, you can pass the result to partyCreate or partyCreateWorkflow so the address is recorded as verified.

Suggest addresses as customers type 

Send the partial address the customer has typed and the country to search in. locationSuggest returns complete addresses that match, in the same shape as the location input on partyCreate, so you can fill in the rest of the address form from the one the customer picks.

1query LocationSuggest($input: LocationSuggestInput!) {
2 locationSuggest(input: $input) {
3 line1
4 line2
5 locality
6 administrativeArea
7 administrativeAreaCode
8 postalCode
9 countryCode
10 latitude
11 longitude
12 }
13}

Suggestion input fields

Field↕Required↕Description↕
countryCodeThe ISO 3166-1 alpha-2 code of the country to search in.
limitThe maximum number of suggestions to return, from 1 to 20. Defaults to 10.
queryThe partial, free-form address the customer has typed, such as 22382 Avenida Emp.

Suggestions are a starting point, not a verified address. Validate the address the customer ends up with before you create a party with it.

Validate an address 

Send the full address to locationValidate. It returns how well the address verified, the address in its standardized form, and a verificationToken when the address is verified.

1query LocationValidate($input: LocationValidateInput!) {
2 locationValidate(input: $input) {
3 status
4 verificationToken
5 address {
6 line1
7 line2
8 locality
9 administrativeArea
10 administrativeAreaCode
11 postalCode
12 countryCode
13 latitude
14 longitude
15 propertyType
16 }
17 }
18}

Validation input fields

Field↕Required↕Description↕
administrativeAreaThe name of the state, province, or region.
administrativeAreaCodeThe code for the state, province, or region, such as CA.
countryCodeThe ISO 3166-1 alpha-2 code of the country.
line1The first line of the address.
line2 – line4Additional address lines, if applicable.
localityThe city, town, or village.
postalCodeThe postal or ZIP code.

Send as much of the address as you have. A postal code, or a locality with an administrative area, gives the best results.

Validation statuses

Status↕Meaning↕Suggested next step↕
VERIFIEDThe address was verified to the building or the exact unit.Use the standardized address.
PARTIALLY_VERIFIEDOnly part of the address was verified, such as the street or the city, but not the building.Ask the customer to check details like the house or unit number.
UNVERIFIEDThe address could not be verified. address is null.Ask the customer to check the address.

The standardized address

When the address is VERIFIED or PARTIALLY_VERIFIED, address holds its standardized form. It can differ from what you sent: missing details such as the city may be filled in, the postal code may be completed, and capitalization and abbreviations are corrected. Show the standardized address to the customer, or use it in place of what they typed.

  • latitude and longitude are included when available.
  • propertyType is RESIDENTIAL or COMMERCIAL when the address is verified and its type is known, and null otherwise. It is not applied for you. Pass it in the location input when you create the party if you want to use it.

Record a verified address on a party 

A VERIFIED result includes a verificationToken. Pass it in the location input of partyCreate or partyCreateWorkflow, along with the standardized address exactly as locationValidate returned it. The party's location is then recorded as verified, without the address being checked again.

1mutation PartyCreate($input: PartyCreateInput!) {
2 partyCreate(input: $input) {
3 id
4 type
5 location {
6 id
7 line1
8 locality
9 administrativeAreaCode
10 postalCode
11 countryCode
12 propertyType
13 }
14 }
15}

Keep these rules in mind when you pass a token:

  • A token is valid for one day. An expired token is ignored, and the party is still created.
  • The address fields must match the standardized address. If the customer edits the address after validating it, the token is ignored and the party is still created. Validate the edited address to get a new token.
  • latitude, longitude, propertyType, and metadata can be changed without affecting the token.
  • Treat the token as an opaque value. Don't parse or change it. A token that was altered, or that was issued to another organization, fails the request.

Errors 

Message↕Cause↕What to do↕
Address verification is unavailableSuggestions or validation couldn't be completed right now.Retry later. Let the customer continue with the address they entered.
Invalid location verification tokenThe verificationToken was altered or was issued to another organization.Pass the token exactly as locationValidate returned it, or leave it out.
limit must be between 1 and 20The limit passed to locationSuggest was outside the allowed range.Pass a limit from 1 to 20, or leave it out to get 10 suggestions.
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

LocationSuggestInput LocationValidateInput PartyCreateInput PartyCreateWorkflowInput

MUTATIONS

partyCreate partyCreateWorkflow

Was this page helpful?

Get support·Legal docs·© 2026 Zonos
On this page:
  • Suggest and validate addresses
  • Suggest addresses as customers type
  • Validate an address
  • Record a verified address on a party
  • Errors