Verify Address

The Verify endpoint allows you to send an address for validation. It attempts to match the provided address against our address database and returns:

• Recommended action – guidance on how to handle the address based on the match result.

• Matched address – the standardized address we found.

• Original input address – exactly what was submitted.

• Match quality – how well the input address matches a known address.

This API is designed to help ensure address accuracy, improve user experience, and reduce delivery or service errors. The Verify API is optimized for Irish and UK addresses but it is available for other countries.

The Verify API always returns an address object, which may contain the matched address or the user’s entered address. This object should always be used, regardless of the recommended action, as it can include partially matched elements or corrections such as spelling adjustments.

The action value tells you how the address should be handled. Your application should follow this guidance to decide what happens next.

The address has been confidently matched and verified.

• Use the returned address object.

• The address object will always have an id.

• May have minor amendments (formatting, casing).

A significant change was detected between the input and the matched address.

• Use highlights, returned in the address, to point out the differences.

• Show both the input.label and address.label to the user and allow them to select which address they would like to continue with.

• The address object will always have an id.

The address may have only partially matched the input address or not matched at all.

• Use highlights, returned in the address, to point out the differences.

• Show the address.label and form.message.value to the user and allow them to select whether they wish to continue with this address.

• The address object may or may not have an id depending on how well the input was matched.

The address has been matched but falls outside of your allowed locations or address types as set in your integration settings in the Account Centre.

• The response will contain form.message.value which will describe the reason the address has been rejected. Display this to the user along with the address.label.

• Example: PO Box addresses when PO Boxes are disabled in your settings.

1. Collect the address from the user or your preferred source.

2. Send the address to the Verify endpoint.

3. Read the action value from the response.

4. Follow the guidance above based on the returned action.

5. If action is suggest or confirm, highlight the changes to the user using the address.highlights and address.label.

• Use the information provided in the address object when displaying or saving an address.

• If action is Suggest or Confirm, use the address.highlights to display what has changed to the user.

• Use the address.label to display the address.

• Map the address.highlights to the structure of the label to accurately highlight the differences to the user.

• Provide the country parameter in requests to limit what country to search in.

The verify API is authenticated using our standard authentication method. For details on how to authenticate and create a token, see our Authentication documentation.

The verify API supports both Get and Post requests. The parameters can be sent in the URL or the body.

https://api.autoaddress.com/3.0/verify

Get

curl --location 'https://api.autoaddress.com/3.0/verify?addressLine=8+silver+birches&city=Dunboyne&country=IE&language=en&region=Co.+Meath&token=YOUR_TOKEN'

Post

curl --location 'https://api.autoaddress.com/3.0/verify' -d 'addressLine=8 silver birches&city=Dunboyne&country=IE&language=en&region=Co. Meath&token=YOUR_TOKEN'

In this example, the input address has been successfully verified and the service returns an action of Accept. For more detailed information, see our detailed examples.

{
  "type": "verify",
  "action": "Accept",
  "form": {
    "language": "en",
    "message": {
      "id": 1010,
      "severity": "Information",
      "value": "Address verified, please note differences"
    }
  },
  "information": {
    "addressAmended": true,
    "complete": true,
    "matchLevel": "Building",
    "postcodeAmended": true,
    "subBuilding": "None",
    "status": "Verified"
  },
  "input": {
    "lines": [
      {
        "key": "AddressLine1",
        "value": "8 silver birches"
      }
    ],
    "city": {
      "value": "Dunboyne"
    },
    "region": {
      "value": "Co. Meath"
    },
    "postcode": {
      "value": ""
    },
    "country": {
      "language": "en",
      "value": "Ireland",
      "iso": "IE"
    },
    "label": [
      "8 silver birches",
      "Dunboyne",
      "Co. Co. Meath",
      "IRELAND"
    ]
  },
  "address": {
    "id": "IE1701984269",
    "language": "en",
    "charset": "Latn",
    "variation": "V",
    "lines": [
      {
        "key": "AddressLine1",
        "value": "8 Silver Birches"
      },
      {
        "key": "AddressLine2",
        "value": "Millfarm"
      }
    ],
    "city": {
      "value": "Dunboyne"
    },
    "region": {
      "value": "Co. Meath"
    },
    "postcode": {
      "value": "A86 VC04"
    },
    "country": {
      "language": "en",
      "value": "Ireland",
      "iso": "IE"
    },
    "label": [
      "8 Silver Birches",
      "Millfarm",
      "Dunboyne",
      "Co. Meath",
      "A86 VC04",
      "IRELAND"
    ],
    "highlights": [
      [],
      [
        0,
        8
      ],
      [],
      [],
      [
        0,
        8
      ],
      []
    ]
  },
  "data": {
    "location": {
      "latitude": 53.420761,
      "longitude": -6.466002,
      "crs": "EPSG:4258",
      "accuracy": "BUILDING"
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.autoaddress.com/3.0/verify?addressLine=8+silver+birches&city=Dunboyne&country=IE&language=en&region=Co.+Meath&token=YOUR_TOKEN",
      "title": "self"
    }
  ]
}

When you call the Verify endpoint, the API returns a JSON object containing details about:

• Recommended action.

• The matched and input addresses.

• Any differences found between input and matched data.

• Additional metadata such as geolocation.

• Additional information to show how well the address has matched and a message describing the result for the user.

This page breaks down each field, explains its purpose, and clarifies optional vs. required fields.

The action field is central to how you process the result. It can return with one of the following:

• Accept – The address is valid and can be used as provided.

• Suggest – A different but similar address was found; present both options to the user and point out the differences.

• Confirm – The address appears mostly correct but may have missing or uncertain elements; confirm with the user before proceeding.

• Reject – No valid match found; prompt the user for correction.

Example:

"form": {
  "language": "en",
  "message": {
    "id": 1010,
    "severity": "Information",
    "value": "Address verified, please note differences"
  }
}

Detailed information on the quality of the match for the address object.

Represents exactly what was sent to the API.

The standardized, verified address. The lines, city, region, postcode and country fields are returned as per the settings in My Form in the Account Centre.

Contains additional location, administrative, building, and address reference data. See Data Settings for further information.