Verify an address

Overview

We aggregate worldwide data from best-in-class providers to create a comprehensive international network. It learns over time, continuously improving delivery accuracy to ensure your shipments are going to the right place.

This guide describes how you can create an address verification and how to interpret the results returned.

Get our GraphQL Playground running

To follow along the the steps in this guide we'll provide an interactive environment for Ruby, Python and Node. You can also use GraphQL directly with our GraphQL Playground.

Validate an address

All addresses submitted must have non-blank values for all of the following fields:

• line1

• city

• postal_code

• country

Here is an example of how to validate an address:

GraphQL

mutation addressValidate($input: AddressValidateInput!) {
  addressValidate(input: $input) {
    address {
      id
      line1
      line2
      city
      state
      country
      postalCode
      verification {
        status
        precision
      }
    }
    addressUserErrors {
      code
      field
      message
    }
  }
}

GraphQL Query Variables

{
  "input": {
    "line1": "Articulo 123",
    "line2": "2417",
    "city": "Monterrey",
    "country": "México",
    "postalCode": "64420"
  }
}

{
  "data": {
    "addressValidate": {
      "address": {
        "id": "gid://kublau/Address/21c35bf2-fb89-4b23-8a0b-0432387db734",
        "line1": "Articulo 123",
        "line2": "2417",
        "city": "Monterrey",
        "state": null,
        "country": "México",
        "postalCode": "64420",
        "verification": {
          "status": "VERIFIED",
          "precision": "PREMISE"
        }
      },
      "addressUserErrors": []
    }
  }
}

How to interpret the validation

The validation will give you back the address and a verification object which contains the following fields:

Field Name	Definition
status	Indicates the verification status of the address. NONE— Status not known, possibly because the address is invalid. PARTIAL — Parts of the address were matched, at the indicated precision level. Better input might result in a better match. AMBIGUOUS — The input address has more than one match within our dataset, at the indicated precision level. VERIFIED — The address was verified, at the indicated precision level.
precision	Indicates the precision of the address values. NONE — Address not known, possibly because this address is invalid. STATE — Address is only verified down to the administrative area. (e.g., typically a state or province) CITY — Address is only verified down to the locality. (e.g., typically a city or town) STREET — Address is only verified down to the thoroughfare level. (e.g., typically a street) PREMISE— Address is verified down to the premise level. (e.g., typically an individual property or building)

A verification status of "VERIFIED" does not necessarily indicate the address is valid or deliverable. For the address to be valid, it's precision must be "PREMISE".

The most effective time to perform address verification is when your customer, or the person entering the delivery address, is present. When asking for an address it is recommended to ask the customer for their address and verify it on the spot. If verification fails, ask them to double check their input; if they confirm that their data is correct, assume they know their address more correctly than the verification process.

You must choose what verification level and precision levels trigger a confirmation to your users. We recommend going for full deliver-ability with status VERIFIED and precision PREMISE.