---
title: "Lookup an address based on a key."
method: POST
path: "/address/lookup/v1"
tags: ["Address Validation"]
---

# Lookup an address based on a key.

`POST /address/lookup/v1`

## Headers

- `Reference-Id` string
- `Timeout-Seconds` integer

## Request body

- AddressLookupV1Request — Address lookup V1 request.
  - `country_iso` string, required — The country ISO3 code.
  - `datasets` string[], required — The datasets for address lookup.
  - `key` AddressLookupKey, required — The address lookup key.
    - `type` string, nullable — The type of the lookup key.
    - `value` string, required — The value of the lookup key.

## Response `200`

OK

- AddressSearchV1Response — Response model for AddressSearchV1 endpoint.
  - `error` ResponseError — Error model containing the error details.
    - `type` string, nullable — A link to documentation that provides more details about the error you’ve encountered.
    - `title` string, nullable — The title of the error.
    - `detail` string, nullable — A description of the error.
    - `instance` string, nullable — The endpoint that returned the error.
  - `result` AddressSearchV1Result — Address search V1 result.
    - `more_results_available` boolean — To indicate that there are more suggestions available than the results provided.
    - `confidence` string, nullable — The outcome (confidence level) of the validation.
    - `suggestions_key` string, nullable — The suggestions key for address suggestion refinement.
    - `suggestions_prompt` string, nullable — The prompt to display to the user, indicating what information they should enter next.
    - `suggestions` AddressSuggestion[], nullable — The collection of the suggestions that match the address search input.
      - `global_address_key` string, nullable — The ID of the address received as part of a validation.
      - `text` string, nullable — The suggestion that should be presented to the user as a possible match to their input.
      - `matched` array[], nullable — A collection of the characters in the suggestion that have been matched. Integrators can use this information to highlight matched text.
        - integer[]
      - `format` string, nullable — The format URL of the suggested address.
      - `stepin` string, nullable — The stepin URL of the cluster of addresses.
      - `number_of_addresses` integer — The stepin URL of the cluster of addresses.
      - `dataset` string, nullable — The dataset of the suggestion.
      - `additional_attributes` AddressNameValuePair[], nullable — The additional attributes of the suggestion.
        - `name` string, nullable — The name of the pair.
        - `value` string, nullable — The value of the pair.
      - `names` string[], nullable — The additional attributes of the suggestion.
      - `uprn` string, nullable — The UPRN of the suggestion.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `406` — Not Acceptable
- `408` — Request Timeout
- `415` — Unsupported Media Type
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.dev/experianaperture/apis/aperture-rest-api.md) · [All operations](https://skmtc.dev/experianaperture/apis/aperture-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/experianaperture/aperture-rest-api/revisions/f17d329b4892/schema)