Verify Address

Overview

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.

Top-Level Response Fields

Field	Type	Description
type	String	Always "verify" for this endpoint. Identifies the operation performed.
action	Enum	Recommended course of action. One of Accept, Suggest, Confirm, Reject.
form	Object	Contains any informational or error messages relevant to the request.
information	Object	Provides summary details about the match and address status.
input	Object	The address details exactly as they were sent to the API.
address	Object	The matched/standardized address returned by the API.
data	Object	Additional data such as geolocation, administrative boundaries, and building details. Returned fields based on data settings set for your integration in the Account Centre.
links	Array	Related API resource links (self-referencing and others if available).

action

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.

form

Field	Type	Description
language	String	Language code of the message.
message	Object	Contains an `id`, `severity`, and `value` describing a note, warning, or error.

Example:

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

information

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

Field	Type	Description
addressAmended	Boolean	Indicates if the matched address differs from the input.
complete	Boolean	Indicates true if the address is considered complete, even when no full match is found.
matchLevel	String	The granularity of the match (e.g., `"Building"`, `"Street"`, `"Locality"`).
postcodeAmended	Boolean	Whether the postcode was changed during matching.
subBuilding	String	Information about sub-building details if present, `"None"` if absent.
status	String	Status of the address (e.g., `"Verified"`).

input

Represents exactly what was sent to the API.

Field	Type	Description
lines	Array	Key-value pairs of each address line.
city	Object	Contains the city/town value.
region	Object	Contains the state, county, or province.
postcode	Object	Contains the Eircode, postcode or ZIP code.
country	Object	Contains the country value, language, and ISO code.
label	Array	Full address formatted as an array of strings.

address

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.

Field	Type	Description
id	String	Unique ID for the address.
language	String	Language code of the address.
charset	String	Character set used.
variation	String	Address variation indicator.
lines	Array	Key-value pairs of each address line.
city	Object	City/town value.
region	Object	State, county, or province.
postcode	Object	Contains the Eircode, postcode or ZIP code.
country	Object	Country value, language, and ISO code.
label	Array	Full address formatted as an array of strings.
highlights	Array	An array of arrays showing differences from the input address. Maps to the structure of label.

data

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