Detailed Examples
Check Address Overview
This section provides an example of the Check API and the response returned.
The response returned is a simple check response which is used to collect statistics for the Reports page on the Account Centre. There is no cost associated with calling this endpoint.
Sample Request
curl --location 'https://api.autoaddress.com/3.0/check?addressLine=8+silver+birches&city=Dunboyne®ion=Co.+Meath&country=IE&language=en&token=YOUR_TOKEN'Sample Response
{
"type": "check"
}Verify Address Overview
This following section provides full examples of the Verify API in action for each possible action type returned by the endpoint:
Accept
Suggest
Confirm
Reject
Each example includes:
Sample request in cURL.
Sample response in JSON.
Recommended handling guidance for developers.
Implementation Tips Across All Actions
Always check the action field first—it determines the handling flow.
Use highlights, returned in the address, to point out the differences.
Use the respective label array when displaying the address or input details.
The address.highlights array maps to the address.label array.
Examples by Action
The examples here assume you have already obtained a valid token. See the Authentication page for details.
1. Accept Example
When it happens
The input address matches a known address and is valid. Minor adjustments (like formatting changes) may still be applied by the API.
Developer Guidance
Accept the address as valid.
If form.addressAmended is true, you may want to display the amended address to the user for transparency.
You can safely store and use the returned address object.
Sample Request
curl --location 'https://api.autoaddress.com/3.0/verify?addressLine=8+silver+birches&city=Dunboyne&country=IE&language=en®ion=Co.+Meath&token=YOUR_TOKEN'Sample Response
{
"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®ion=Co.+Meath&token=YOUR_TOKEN",
"title": "self"
}
]
}2. Suggest Example
When it happens
A similar address was found, but there is a significant difference from the input address.
The API returns the suggested address along with highlights showing the differences.
Developer Guidance
Display both the input and suggested address to the user using the label objects from input and address.
The highlights array maps to the label object.
Use the highlights array to point out the differences visually and allow them to select which address they would like to continue with.
If the user chooses the suggested address, update your stored address to match the returned address object.
Sample Request
curl --location 'https://api.autoaddress.com/3.0/verify?addressLine=8+silver+birches&city=Dunboyne&country=IE&language=en&token=YOUR_TOKEN'Sample Response
{
"type": "verify",
"action": "Suggest",
"form": {
"language": "en",
"message": {
"id": 2000,
"severity": "Warning",
"value": "We found a close match, 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": ""
},
"postcode": {
"value": ""
},
"country": {
"language": "en",
"value": "Ireland",
"iso": "IE"
},
"label": [
"8 silver birches",
"Dunboyne",
"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
],
[],
[
4,
9
],
[
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&token=YOUR_TOKEN",
"title": "self"
}
]
}3. Confirm Example
When it happens
The input may have been only partially matched or not matched at all.
Developer Guidance
Show the warning message from form.message.value to inform them specifically what was not found.
Display the address object to the user using the label.
The highlights array maps to the label object.
Use the highlights array to point out the differences visually and allow them to select which address they would like to continue with.
Provide options to:
Correct or add missing details.
Proceed with the address as is.
Sample Request
curl --location 'https://api.autoaddress.com/3.0/verify?addressLines=Flat+5&addressLines=82+Capel+Street&city=Dublin&country=IE&language=en®ion=Dublin+1&token=YOUR_TOKEN'Sample Response
{
"type": "verify",
"action": "Confirm",
"form": {
"language": "en",
"message": {
"id": 3020,
"severity": "Warning",
"value": "Could not find 'Flat 5'. Please check the address is correct."
}
},
"information": {
"addressAmended": true,
"complete": true,
"matchLevel": "Building",
"postcodeAmended": true,
"subBuilding": "UnmatchedOptional",
"status": "Building"
},
"input": {
"lines": [
{
"key": "AddressLine1",
"value": "Flat 5"
},
{
"key": "AddressLine2",
"value": "82 Capel Street"
}
],
"city": {
"value": "Dublin"
},
"region": {
"value": "Dublin 1"
},
"postcode": {
"value": ""
},
"country": {
"language": "en",
"value": "Ireland",
"iso": "IE"
},
"label": [
"Flat 5",
"82 Capel Street",
"Dublin",
"Dublin 1",
"IRELAND"
]
},
"address": {
"id": "IE1900007065",
"language": "en",
"charset": "Latn",
"variation": "V",
"lines": [
{
"key": "AddressLine1",
"value": "Flat 5"
},
{
"key": "AddressLine2",
"value": "82 Capel Street"
}
],
"city": {
"value": "Dublin 1"
},
"region": {
"value": "Co. Dublin"
},
"postcode": {
"value": "D01 WC04"
},
"country": {
"language": "en",
"value": "Ireland",
"iso": "IE"
},
"label": [
"Flat 5",
"82 Capel Street",
"Dublin 1",
"D01 WC04",
"IRELAND"
],
"highlights": [
[0, 6],
[],
[],
[0, 8],
[]
]
},
"data": {
"location": {
"latitude": 53.350909,
"longitude": -6.269693,
"crs": "EPSG:4258",
"accuracy": "BUILDING"
}
},
"links": [
{
"rel": "self",
"href": "https://api.autoaddress.com/3.0/verify?addressLine=Flat+5&addressLine=82+Capel+Street&city=Dublin&country=IE&language=en®ion=Dublin+1&token=wYOUR_TOKEN",
"title": "self"
}
]
}
4. Reject Example
When it happens
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.
For example, this can occur if PO Box addresses are disabled in your account settings.
Developer Guidance
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.
Ask the user to provide an alternative address.
Sample Request
curl --location 'https://api.autoaddress.com/3.0/verify?addressLines=MIKES+PO+BOX&addressLines=PO+Box+1216&city=HARROW&country=GB&language=en&postcode=HA3+3LP&token=YOUR_TOKEN'Sample Response
{
"type": "verify",
"action": "Reject",
"form": {
"language": "en",
"message": {
"id": 4000,
"severity": "Error",
"value": "We can't deliver to this address, please provide an alternative."
}
},
"information": {
"addressAmended": true,
"complete": true,
"matchLevel": "SubBuilding",
"postcodeAmended": false,
"subBuilding": "Matched",
"status": "Rejected"
},
"input": {
"lines": [
{
"key": "AddressLine1",
"value": "MIKES PO BOX"
},
{
"key": "AddressLine2",
"value": "PO Box 1216"
}
],
"city": {
"value": "HARROW"
},
"region": {
"value": ""
},
"postcode": {
"value": "HA3 3LP"
},
"country": {
"language": "en",
"value": "United Kingdom",
"iso": "GB"
},
"label": [
"MIKES PO BOX",
"PO Box 1216",
"HARROW",
"HA3 3LP",
"UNITED KINGDOM"
]
},
"address": {
"id": "GB11839148",
"language": "en",
"charset": "Latn",
"variation": "P",
"lines": [
{
"key": "AddressLine1",
"value": "PO Box 1216"
},
{
"key": "AddressLine2",
"value": "MIKES PO BOX"
}
],
"city": {
"value": "HARROW"
},
"region": {
"value": ""
},
"postcode": {
"value": "HA3 3LP"
},
"country": {
"language": "en",
"value": "United Kingdom",
"iso": "GB"
},
"label": [
"PO Box 1216",
"MIKES PO BOX",
"HARROW",
"HA3 3LP",
"UNITED KINGDOM"
],
"highlights": [
[],
[0, 12],
[],
[],
[]
]
},
"data": {
"location": {
"latitude": 51.5852294,
"longitude": -0.3296639,
"crs": "EPSG:4258",
"accuracy": "BUILDING"
}
},
"links": [
{
"rel": "self",
"href": "https://api.autoaddress.com/3.0/verify?addressLine=MIKES+PO+BOX&addressLine=PO+Box+1216&city=HARROW&country=GB&language=en&postcode=HA3+3LP&token=YOUR_TOKEN",
"title": "self"
}
]
}