A plain-text reference for the AddressBrain REST API, version v1. The interactive OpenAPI documentation and downloadable spec are at api.addressbrain.com/docs and api.addressbrain.com/openapi.json. Base URL for all requests: https://api.addressbrain.com
Every request carries your API key as a Bearer token in the Authorization header: Authorization: Bearer YOUR_API_KEY. Keys are created in your account dashboard. There is no OAuth flow and no SDK required. Create a free account to get a key: 30 lookups a day for 30 days, no card needed.
Searches UK addresses and returns a list of matching results. Use it for postcode lookup (pass a postcode as the search term), for as-you-type autocomplete (pass a partial address) or to find a business by name. Parameters: SearchTerm (required, string) is the postcode, partial address or business name; Limit (optional, integer) is the maximum number of results, default 10, maximum 100; GroupId (optional, string) restricts results to a previously returned group such as a postcode, street or town.
The response is a JSON object with an items array. Each item has an id, a text description, a type of Address, Postcode, Street or Town, and for group types a numberOfAddresses count. For an Address result, pass its id to the details endpoint. For a Postcode, Street or Town result, pass its id back to this endpoint as GroupId to list every address inside that group. This is how a postcode-first checkout works: search the postcode, then expand the postcode group to show the customer the full list of addresses to pick from.
curl "https://api.addressbrain.com/api/v1/addresses/search?SearchTerm=SW1A%201AA" \
-H "Authorization: Bearer YOUR_API_KEY"
# Expand a postcode group returned by the first call
curl "https://api.addressbrain.com/api/v1/addresses/search?SearchTerm=SW1A%201AA&GroupId=GROUP_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# Response shape
{
"items": [
{ "id": "...", "text": "SW1A 1AA, London", "type": "Postcode", "numberOfAddresses": 1 },
{ "id": "...", "text": "Buckingham Palace, London, SW1A 1AA", "type": "Address" }
]
}Returns the complete, formatted address for an Address result from the search endpoint. The response fields are: id; line1 (building number and street); line2 (additional street information); line3 (building names and sub-buildings); line4; line5; company; department; city; province (county, where applicable); postalCode (full UK postcode); countryIso3 (ISO 3166-1 alpha-3 country code); deliveryPointSuffix; and barcode (the Royal Mail delivery barcode used for sorting). Retrieving address details is what counts as a lookup against your plan allowance.
curl "https://api.addressbrain.com/api/v1/addresses/ADDRESS_ID/details" \
-H "Authorization: Bearer YOUR_API_KEY"
# Response shape
{
"id": "...",
"company": "",
"department": "",
"line1": "10 Downing Street",
"line2": "",
"line3": "",
"line4": "",
"line5": "",
"city": "London",
"province": "",
"postalCode": "SW1A 2AA",
"countryIso3": "GBR",
"deliveryPointSuffix": "...",
"barcode": "..."
}Successful calls return HTTP 200 with JSON. Errors return plain text: 400 for an invalid parameter value, 401 for a missing or invalid API key, 404 when an address id is not found, 429 when the rate limit is exceeded, and 500 for an unexpected server error. Typical UK response times are under 50ms.
All address data comes from Royal Mail's Postcode Address File (PAF) under an official Royal Mail licence held by AddressBrain, covering around 32 million UK delivery addresses across 1.8 million postcodes plus 1.4 million business names, with new-build addresses added as Royal Mail releases them. Because the licence sits with AddressBrain, you do not need your own PAF agreement to use the API in a checkout, onboarding flow, internal tool or AI agent.
The API is a plain REST service with a published OpenAPI spec, so any agent framework that can register an OpenAPI document as a tool can call it: register the spec URL, supply the bearer token, and expose the search and details operations. Have the agent write back the exact address returned by the details endpoint rather than a version it regenerates itself, so that validation is preserved end to end.