# API Reference - OpenAPI Reference

Version: 4.1.1

Complete machine-readable reference for every API operation, generated from the OpenAPI specification.


---

## GET /keys/{key}

**Availability**

Returns public information on an API Key: whether it can be used right now (`available`), the search contexts the key is licensed for (`contexts`) and the context that best matches the caller's IP address (`context`).

The endpoint accepts API Keys (beginning `ak_`) and sub-licensed keys (beginning `sl_`), and needs no Management Key.

A key that exists but cannot be used, because it has no lookups left or has breached a limit, returns `200` with `"available": false`. An unknown or malformed key returns an error.

Supply a valid Management Key and the endpoint returns the key's private details instead, as `GET /keys/{key}/details` does. A Management Key that does not own the key is rejected.


**Undefined parameters**

- `undefined` (string)

**Response (200)**

- `result` (ApiKey, required)
  - `contexts` (AvailableContexts, required) - A list of available contexts for a key
    - `iso_3` (string, required) - 3 letter ISO code
    - `iso_2` (string, required) - 2 letter ISO code
    - `description` (string, required) - Country descriptor to show in Address Finder
    - `emoji` (string, required) - Emoji text icon
    - `rgeo` (boolean, required) - Indicates availability of reverse geolocation search
  - `context` (oneOf, required) - Returns current context if it is in the list of available contexts for this key.
    - one of: Context, NoContext
  - `available` (boolean, required) - Determines whether the key can be used by the requesting agent.
- `message` (string, required)
- `code` (integer, required)

---

## GET /keys/{key}/details

**Details**

Returns private data on a key: remaining lookups, licensed datasets, usage limits, notification settings and the search contexts the key can serve.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (ApiKeyDetails, required)
  - `name` (string, required) - A name for the key
  - `contexts` (AvailableContexts, required) - A list of available contexts for a key
    - `iso_3` (string, required) - 3 letter ISO code
    - `iso_2` (string, required) - 2 letter ISO code
    - `description` (string, required) - Country descriptor to show in Address Finder
    - `emoji` (string, required) - Emoji text icon
    - `rgeo` (boolean, required) - Indicates availability of reverse geolocation search
  - `lookups_remaining` (integer, required)
  - `daily_limit` (ApiKeyDailyLimit, required)
    - `limit` (integer, required) - `number` or `null`. The daily lookup limit currently set on your key.
    - `consumed` (integer, required) - Number of lookups performed today which count towards your daily limit.
  - `monthly_limit` (ApiKeyMonthlyLimit, required)
    - `limit` (integer, required) - `number` or `null`. The monthly lookup limit currently set on your key.
    - `consumed` (integer, required) - Number of lookups performed this month which count towards your monthly limit.
  - `individual_limit` (ApiKeyIndividualLimit, required)
    - `limit` (integer, required) - `number` or `null` Limit set on the number of lookups that can be
  - `allowed_urls` (array<string>, required) - A list of allowed URLs. An empty list disables the check.
  - `redact_days` (integer, required) - Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage
  - `notifications` (ApiKeyNotifications, required)
    - `emails` (array<string>, required) - A list of email addresses designated by you to receive notifications about this key.
    - `enabled` (boolean, required) - Indicates whether email notifications are enabled.
    - `balance_threshold` (integer, required) - Balance threshold that triggers a reminder email. null means disabled.
    - `no_balance` (boolean, required) - Send notice when balance hits zero.
    - `limit_reached` (boolean, required) - Send notice when rate limit is reached.
  - `datasets` (ApiKeyDatasets, required) - Indicates which datasets are available and added by default to the address responses
    - `paf` (boolean, required) - UK Main Address File (Postcode Address File)
    - `pafa` (boolean, required) - UK Property Alias dataset
    - `pafw` (boolean, required) - UK Welsh Language Dataset
    - `mr` (boolean, required) - UK Multiple Residence Dataset
    - `nyb` (boolean, required) - UK Not Yet Built Dataset
    - `ab` (boolean, required) - UK AddressBase dataset
    - `abp` (boolean) - UK AddressBase Premium dataset
    - `nip` (boolean, required) - Northern Ireland Pointer Dataset
    - `usps` (boolean, required) - US Address Dataset
    - `ecad` (boolean, required) - Republic of Ireland: Eircode Address Database
    - `ecaf` (boolean, required) - Republic of Ireland: Eircode Address File
    - `gnaf` (boolean, required) - Australia: Geocoded National Address File
    - `hereap` (boolean, required) - Asia Pacific Address File
    - `herehk` (boolean, required) - Hong Kong Address File
    - `herei` (boolean, required) - India Address File
    - `herem` (boolean, required) - Macau Address File
    - `heremea` (boolean, required) - Middle East and Africa Address File
    - `heremeas` (boolean, required) - Middle East and Africa Standalone Intermediate Maps Address File
    - `herena` (boolean, required) - North America Address File
    - `hereo` (boolean, required) - Oceania Address File
    - `heresa` (boolean, required) - South America Address File
    - `heret` (boolean, required) - Taiwan Address File
    - `hereee` (boolean, required) - Eastern Europe Address File
    - `herewe` (boolean, required) - Western Europe Address File
    - `phone` (boolean, required) - Phone validation is enabled
    - `email` (boolean, required) - Email validation is enabled
    - `kadaster` (boolean, required) - Netherlands: Kadaster BAG 2.0 Address File
    - `kartverket` (boolean, required) - Norway: Kartverket Address File
    - `mois` (boolean, required) - South Korea: MOIS Address File
    - `sdfi` (boolean, required) - Denmark: Danmarks Adresseregister (DAR)
    - `cannar` (boolean, required) - Canada: Statistics Canada National Address Register
    - `fodbosa` (boolean, required) - Belgium: FOD BOSA Address File
    - `upujp` (boolean, required) - Japan: UPU Address File
    - `bev` (boolean, required) - Austria: BEV Address File
    - `ban` (boolean, required) - France: BAN (Base Adresse Nationale)
    - `swt` (boolean, required) - Switzerland and Liechtenstein: Swisstopo Address File
    - `gbrcleanse` (boolean, required) - UK GBR Cleanse
    - `uspscleanse` (boolean, required) - US CASS Cleanse
  - `automated_topups` (ApiKeyAutomatedTopup, required) - Automated topup status
    - `enabled` (boolean, required) - Indicates whether automated top-ups are enabled
  - `current_purchases` (array<ApiKeyCurrentPurchase>, required) - Current balance purchases attached to key.
    - `expires` (string, required) - `string` or `null` The date when this purchase will expire in simplified
    - `purchased` (integer, required) - Number of procured lookups from this purchase.
    - `consumed` (integer, required) - Number of consumed lookups off this purchase.
  - `ip_forwarding` (boolean, required) - Accept IP addresses forwarded in the `AZ-Source-IP` header
  - `premier_support` (boolean, required) - Whether the key is enrolled in the premier support program and monitored closely by our devops team. Read-only; managed by our team.
- `code` (integer, required)
- `message` (string, required)

---

## PUT /keys/{key}/details

**Update Details**

Updates a key's settings and returns its private details. Only the fields you send change. A key on an unlimited plan ignores changes to `datasets`, `daily_limit` and `monthly_limit`.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Request body**

- `name` (string) - A name for the key
- `daily_limit` (object)
  - `limit` (integer) - `number` or `null`. The daily lookup limit currently set on your key.
- `monthly_limit` (object)
  - `limit` (integer) - `number` or `null`. The monthly lookup limit currently set on your key.
- `individual_limit` (object)
  - `limit` (integer) - `number` or `null` Limit set on the number of lookups that can be
- `allowed_urls` (array<string>) - A list of allowed URLs. An empty list disables the check. Up to 10 allowed.
- `redact_days` (integer) - Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage
- `notifications` (object)
  - `emails` (array<string>) - A list of email addresses designated by you to receive notifications about this key. Up to 5 allowed.
  - `enabled` (boolean) - Indicates whether email notifications are enabled.
  - `balance_threshold` (integer) - Balance threshold that triggers a reminder email. null to disable.
  - `no_balance` (boolean) - Send notice when balance hits zero.
  - `limit_reached` (boolean) - Send notice when rate limit is reached.
- `ip_forwarding` (boolean) - Accept IP addresses forwarded in the `AZ-Source-IP` header
- `datasets` (object) - Indicates which datasets are available and added by default to the address responses
  - `pafa` (boolean) - UK Property Alias dataset
  - `pafw` (boolean) - UK Welsh Language Dataset
  - `usps` (boolean) - US Address Dataset
  - `hereap` (boolean) - Asia Pacific Address File
  - `herehk` (boolean) - Hong Kong Address File
  - `herei` (boolean) - India Address File
  - `herem` (boolean) - Macau Address File
  - `heremea` (boolean) - Middle East and Africa Address File
  - `heremeas` (boolean) - Middle East and Africa Extended File
  - `herena` (boolean) - North America Address File
  - `hereo` (boolean) - Oceania Address File
  - `heresa` (boolean) - South America Address File
  - `heret` (boolean) - Taiwan Address File
  - `hereee` (boolean) - Eastern Europe Address File
  - `herewe` (boolean) - Western Europe Address File
  - `phone` (boolean) - Phone validation is enabled
  - `email` (boolean) - Email validation is enabled
  - `gnaf` (boolean) - Australia: Geoscape Geocoded National Address File
  - `kadaster` (boolean) - Netherlands: Kadaster BAG 2.0 Address File
  - `kartverket` (boolean) - Norway: Kartverket Address File
  - `sdfi` (boolean) - Denmark: SDFI Address File
  - `cannar` (boolean) - Canada: Statistics Canada National Address Register
  - `fodbosa` (boolean) - Belgium: FOD BOSA Address File
  - `mois` (boolean) - South Korea: MOIS Address File
  - `upujp` (boolean) - Japan: UPU Address File
  - `bev` (boolean) - Austria: BEV Address File
  - `ban` (boolean) - France: BAN (Base Adresse Nationale)
  - `swt` (boolean) - Switzerland and Liechtenstein: Swisstopo Address File
  - `ab` (boolean) - UK AddressBase dataset
  - `abp` (boolean) - UK AddressBase Premium dataset
  - `nip` (boolean) - Northern Ireland Pointer Dataset
  - `gbrcleanse` (boolean) - UK GBR Cleanse
  - `uspscleanse` (boolean) - US CASS Cleanse

**Response (200)**

- `result` (ApiKeyDetails, required)
  - `name` (string, required) - A name for the key
  - `contexts` (AvailableContexts, required) - A list of available contexts for a key
    - `iso_3` (string, required) - 3 letter ISO code
    - `iso_2` (string, required) - 2 letter ISO code
    - `description` (string, required) - Country descriptor to show in Address Finder
    - `emoji` (string, required) - Emoji text icon
    - `rgeo` (boolean, required) - Indicates availability of reverse geolocation search
  - `lookups_remaining` (integer, required)
  - `daily_limit` (ApiKeyDailyLimit, required)
    - `limit` (integer, required) - `number` or `null`. The daily lookup limit currently set on your key.
    - `consumed` (integer, required) - Number of lookups performed today which count towards your daily limit.
  - `monthly_limit` (ApiKeyMonthlyLimit, required)
    - `limit` (integer, required) - `number` or `null`. The monthly lookup limit currently set on your key.
    - `consumed` (integer, required) - Number of lookups performed this month which count towards your monthly limit.
  - `individual_limit` (ApiKeyIndividualLimit, required)
    - `limit` (integer, required) - `number` or `null` Limit set on the number of lookups that can be
  - `allowed_urls` (array<string>, required) - A list of allowed URLs. An empty list disables the check.
  - `redact_days` (integer, required) - Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage
  - `notifications` (ApiKeyNotifications, required)
    - `emails` (array<string>, required) - A list of email addresses designated by you to receive notifications about this key.
    - `enabled` (boolean, required) - Indicates whether email notifications are enabled.
    - `balance_threshold` (integer, required) - Balance threshold that triggers a reminder email. null means disabled.
    - `no_balance` (boolean, required) - Send notice when balance hits zero.
    - `limit_reached` (boolean, required) - Send notice when rate limit is reached.
  - `datasets` (ApiKeyDatasets, required) - Indicates which datasets are available and added by default to the address responses
    - `paf` (boolean, required) - UK Main Address File (Postcode Address File)
    - `pafa` (boolean, required) - UK Property Alias dataset
    - `pafw` (boolean, required) - UK Welsh Language Dataset
    - `mr` (boolean, required) - UK Multiple Residence Dataset
    - `nyb` (boolean, required) - UK Not Yet Built Dataset
    - `ab` (boolean, required) - UK AddressBase dataset
    - `abp` (boolean) - UK AddressBase Premium dataset
    - `nip` (boolean, required) - Northern Ireland Pointer Dataset
    - `usps` (boolean, required) - US Address Dataset
    - `ecad` (boolean, required) - Republic of Ireland: Eircode Address Database
    - `ecaf` (boolean, required) - Republic of Ireland: Eircode Address File
    - `gnaf` (boolean, required) - Australia: Geocoded National Address File
    - `hereap` (boolean, required) - Asia Pacific Address File
    - `herehk` (boolean, required) - Hong Kong Address File
    - `herei` (boolean, required) - India Address File
    - `herem` (boolean, required) - Macau Address File
    - `heremea` (boolean, required) - Middle East and Africa Address File
    - `heremeas` (boolean, required) - Middle East and Africa Standalone Intermediate Maps Address File
    - `herena` (boolean, required) - North America Address File
    - `hereo` (boolean, required) - Oceania Address File
    - `heresa` (boolean, required) - South America Address File
    - `heret` (boolean, required) - Taiwan Address File
    - `hereee` (boolean, required) - Eastern Europe Address File
    - `herewe` (boolean, required) - Western Europe Address File
    - `phone` (boolean, required) - Phone validation is enabled
    - `email` (boolean, required) - Email validation is enabled
    - `kadaster` (boolean, required) - Netherlands: Kadaster BAG 2.0 Address File
    - `kartverket` (boolean, required) - Norway: Kartverket Address File
    - `mois` (boolean, required) - South Korea: MOIS Address File
    - `sdfi` (boolean, required) - Denmark: Danmarks Adresseregister (DAR)
    - `cannar` (boolean, required) - Canada: Statistics Canada National Address Register
    - `fodbosa` (boolean, required) - Belgium: FOD BOSA Address File
    - `upujp` (boolean, required) - Japan: UPU Address File
    - `bev` (boolean, required) - Austria: BEV Address File
    - `ban` (boolean, required) - France: BAN (Base Adresse Nationale)
    - `swt` (boolean, required) - Switzerland and Liechtenstein: Swisstopo Address File
    - `gbrcleanse` (boolean, required) - UK GBR Cleanse
    - `uspscleanse` (boolean, required) - US CASS Cleanse
  - `automated_topups` (ApiKeyAutomatedTopup, required) - Automated topup status
    - `enabled` (boolean, required) - Indicates whether automated top-ups are enabled
  - `current_purchases` (array<ApiKeyCurrentPurchase>, required) - Current balance purchases attached to key.
    - `expires` (string, required) - `string` or `null` The date when this purchase will expire in simplified
    - `purchased` (integer, required) - Number of procured lookups from this purchase.
    - `consumed` (integer, required) - Number of consumed lookups off this purchase.
  - `ip_forwarding` (boolean, required) - Accept IP addresses forwarded in the `AZ-Source-IP` header
  - `premier_support` (boolean, required) - Whether the key is enrolled in the premier support program and monitored closely by our devops team. Read-only; managed by our team.
- `code` (integer, required)
- `message` (string, required)

---

## GET /keys/{key}/usage

**Usage Stats**

Reports the number of lookups a key consumed over a date range, as a total and a daily breakdown.

The range defaults to the last 21 days. `start` and `end` take UNIX timestamps in milliseconds, and `end` defaults to the current time. The maximum range is 90 days.

Query at most three tags at once.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (KeyUsageResult, required)
  - `start` (string, required) - Start date in ISO 8601 format.
  - `end` (string, required) - End date in ISO 8601 format.
  - `total` (integer, required) - Total of paid lookups performed in specified period.
  - `dailyCount` (array<object>, required) - An array of objects representing number of paid lookups made on specific days, ordered by date. Each object contains a `date` attribute, which represents the day and a `count` attribute, which represents the number of paid lookups made on that day.
    - `date` (string, required)
    - `count` (integer, required)
- `code` (integer, required)
- `message` (string, required)

---

## GET /keys/{key}/lookups

**Logs (CSV)**

Returns a CSV of the charged lookups made on a key, one row per request.

Requires the account Management Key. The maximum interval is 90 days. Without a start or end date the interval is the last 21 days.

The response is `text/csv` and downloads as an attachment. A non-200 response reverts to JSON, with the error code and message in the body.

## CSV format

The CSV has no header row. Columns, in order:

1. Timestamp (ISO 8601)
2. IP address the request was received from
3. Search term
4. URL the request originated from
5. Lookup type
6. Tags
7. Lookups consumed
8. Licensee name (sublicensing keys only)
9. Source IP address

The source IP column carries the address forwarded in the `AZ-Source-IP` header. We record it only for keys with IP address forwarding enabled, and only when the header holds a valid IP address. It is empty otherwise.

## Data redaction

We redact personally identifiable data (PII) in your usage log weekly, covering the IP, source IP, search term and URL columns.

The default retention is 28 days. Change the period from your dashboard. Set it to `0` days to stop collecting PII altogether.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

---

## POST /verify/addresses

**Verify Address**

Verifies an address against the USPS Coding Accuracy Support System (CASS) and returns it standardized and corrected.

Submit the whole address in `query`, or the first address line in `query` with either `zip_code`, or `city` and `state`. A freeform `query` is parsed into those components before the search runs.

A match returns the standardized address lines, city, state and ZIP+4, scored by `fit` and `confidence`. It also carries the CASS record behind the match: delivery point, DPV flags, carrier route, eLOT, county, congressional district, RDI, time zone and coordinates. No match returns `200` with a `count` of `0`, a `null` `match` and empty address fields.

Only a match draws on your balance. A key without address verification enabled returns `401`. A verification still running after 9.5 seconds aborts with `429`.

## Countries

Verify defaults to the United States, where it is CASS certified. Pass `context` with an ISO 3166-1 alpha-3 country code to verify an address elsewhere, e.g. `context=GBR` or `context=FRA`. The address datasets your key is licensed for decide which countries it can verify.

Outside the United States there is no CASS record to return, so `match` carries the standardized address from that country's dataset instead. The top-level fields (`address_line_one`, `city`, `state`, `zip_code`, `country_iso_2`) are populated for every country, along with `confidence` and `fit`.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Query parameters**

- `context` (string) - Identify the country of the address to verify. Defaults to United States (USA)

**Request body**

- `query` (string, required) - Address input to verify.
- `zip_code` (string) - Specify the ZIP code of an address. The following formats are accepted: `81073-1119`, `810731119`, `81073`.
- `city` (string) - City of an address.
- `state` (string) - State of an address. For the US, use the 2 letter state abbreviation.

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (oneOf, required)
  - one of: UsaVerifyMatch, UsaVerifyNoMatch
  - `query` (string, required) - Submitted query
  - `query_city` (string, required) - Submitted city
  - `query_state` (string, required) - Submitted state
  - `query_zip_code` (string, required) - Submitted zip_code
  - `match` (object, required) - Nearest matching address
    - `address1` (string, required) - Primary delivery address
    - `address2` (string, required) - Secondary address information
    - `address3` (string, required) - Additional secondary address information
    - `area_code` (string, required) - Area code. Also known as Numbering Plan Area (NPA) https://en.wikipedia.org/wiki/List_of_North_American_Numbering_Plan_area_codes
    - `carrier_route` (string, required) - Data required to perform a Carrier Route sort
    - `check_digit` (string, required) - Character following the 5 or 9 digit ZIP Code. Part of the 11-digit barcode
    - `city` (string, required) - City name
    - `city_abbreviation` (string, required) - City Abbreviation. Empty string if not present
    - `congressional_district` (string, required) - Identifies the Congressional District. Empty string if not present
    - `country_code` (string, required) - ISO3166 country code. Empty string if not present
    - `county` (string, required) - Name of the county
    - `day_light_savings` (boolean, required) - Daylight saving time indicator
    - `delivery_point` (string, required) - Last 2 digits of the primary street address number or Post Office box
    - `dpv` (string, required) - Delivery Point Validation (DPV) Confirmation code.
    - `dpv_cmra` (string, required) - Delivery Point Validation (DPV) CMRA code.
    - `dpv_footnotes` (string, required) - Delivery Point Validation (DPV) Footnotes. Empty string if not present
    - `dpv_no_stat` (string, required) - Delivery Point Validation (DPV) NoStat code.
    - `dpv_vacant` (string, required) - Delivery Point Validation (DPV) Vacant code.
    - `elot` (string, required) - Enhanced Line of Travel. For arranging records in the order that a route is served by a carrier. eLOT sequencing, when combined with Carrier Route codes, may allow Enhanced Carrier Route (ECR) discounts to be claimed.
    - `finance_number` (string, required) - Internal accounting number used by the USPS® when Post Offices or ZIP Codes are discontinued and reassigned. The finance number reflects the geographic grouping of ZIP + 4 areas in which these changes can be made.
    - `fips_county_code` (string, required) - Federal Information Processing Standard code for a county. Empty string if not present
    - `firm` (string, required) - Company name in a business address
    - `footnotes` (string, required) - Letter codes returned by ZIP+4 encoding. Empty string if not present
    - `geo_coded` (boolean, required) - Indicates whether the address was geo-coded
    - `lacs_indicator` (string, required) - Indicates whether a record may benefit from LACS processing.
    - `lacs_link_footnote` (string, required) - LACSLink Footnote. Return Code returned by the LACSLink process when an accurate address match could not be made. These codes help identify the type of move and the type of deficiency in the record which prevents a match.
    - `lacs_link_indicator` (string, required) - LACSLink Indicator. Indicates whether the input address matched a record in the LACSLink database.
    - `latitude` (string, required) - Latitude of the encoded address. Empty string if not present
    - `longitude` (string, required) - Longitude of the encoded address. Empty string if not present
    - `parsed_pmb_designator` (string, required) - Information if a Private Mail Box (PMB) is found in an address. Empty string if not present
    - `parsed_pmb_number` (string, required) - Information if a Private Mail Box (PMB) is found in an address. Empty string if not present
    - `parsed_post_directional` (string, required) - Notation following the street name indicating street direction. Empty string if not present
    - `parsed_pre_directional` (string, required) - Notation preceding the street name indicating street direction. Empty string if not present
    - `parsed_primary_number` (string, required) - Number preceding the street name. Empty string if not present
    - `parsed_street_name` (string, required) - Street name. Empty string if not present
    - `parsed_suffix` (string, required) - Part of the delivery address line following the street name. Empty string if not present
    - `parsed_unit_designator` (string, required) - Identification of the secondary address unit. Empty string if not present
    - `parsed_unit_number` (string, required) - Apartment or suite number. Empty string if not present
    - `rdi` (string, required) - Residential Delivery Indicator (RDI). Indicates whether USPS classifies the delivery point as residential. Empty string if not present
    - `record_type` (string, required) - Type of address record.
    - `state` (string, required) - Standard two-letter state abbreviation
    - `suite_link_footnote` (string, required) - Results of the SuiteLink lookup.
    - `time_zone` (string, required) - Time zone. Empty string if not present
    - `urbanization` (string, required) - Urban name required in the address of all mail being delivered to Puerto Rico. Empty string if not present
    - `zip_code` (string, required) - 5-digit ZIP Code and the four additional digits
  - `count` (number, required) - The number of addresses we matched to the input. We return the closest match by default.
  - `fit` (number, required) - A score represented as number between 1 and 0. Fit compares the address elements present in your query against the matching address elements. It does not incorporate elements you have not presented in the score. A partial address (e.g. 123 Main St) will have a fit of 1 even though it is missing city and zip code. Its confidence score will be less than 1 however because it is missing some crucial elements.
  - `confidence` (number, required) - A confidence score represented as number between 1 and 0. 1 indicates a full match. 0 indicates no complete matching elements.
  - `match_information` (string, required) - Additional information about the match.
  - `address_line_one` (string, required) - Primary delivery address
  - `address_line_two` (string, required) - Secondary address information
  - `city` (string, required) - City name
  - `state` (string, required) - State name
  - `zip_code` (string, required) - Zip code
  - `country_iso_2` (string, required) - 2 letter ISO country code

---

## GET /autocomplete/addresses

**Find Address**

Returns address suggestions for a partial address, ranked by relevance. Use it to autofill an address form as the user types.

A suggestion is a display label and an `id`, not a full address. Retrieve the address with a second request to `/autocomplete/addresses/{id}/usa`. That second request is the one which decrements your lookup balance.

Autocomplete is not a free standalone resource. We rate limit, then suspend, keys that autocomplete without resolving suggestions.

Our address autocomplete JavaScript libraries add this to a form without calling the API directly.

## Coverage

Each search runs in one country, selected with `context`. A missing or unrecognized `context` falls back to your account default. Results come from the datasets enabled on your key: USPS Zip+4 for the US and its territories, and the country datasets you license elsewhere. Where a key has more than one dataset for a country, `dataset` narrows the search.

## Filters

Filters restrict results, e.g. `state_code=NY` searches New York only. A filter which matches no address returns an empty set. An unrecognized filter name is ignored. Neither affects your lookup balance.

Filters combine with `AND` logic, so `state_code=CA&city=San Francisco` requires both. A comma-separated value combines terms for one filter, e.g. `postal_code_3=11225,11226,11238` accepts any of the three ZIP codes. Unless a parameter states otherwise, every filter takes multiple terms. The maximum is 10 filter terms.

## Address bias

Bias terms carry the `bias_` prefix and promote addresses rather than restricting the set, so unmatched addresses still appear, lower down. For example, `bias_state_code=NY,NJ` favors addresses in New York and New Jersey, `bias_lonlat` favors addresses near a point. Invalid bias terms have no effect. Multiple bias terms are allowed unless stated otherwise, with a combined maximum of 5.

## Suggestion format

The suggestion string is subject to change. Present it to the user as it arrives rather than parsing it.

## Rate limiting and cost

The default rate limit is 3,000 requests per 5 minutes, counted per API key and IP address. The `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers report the current window.

Autocomplete requests do not draw on your balance. Resolving a suggestion to a full address does.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Query parameters**

- `query` (string) - **Address Query**

**Response (200)**

- `result` (object, required)
  - `hits` (array<AddressSuggestion>, required)
    - `id` (ID, required) - Global unique internally generated identifier for an address
    - `suggestion` (string, required) - Address Suggestion to be displayed to the user
    - `urls` (object, required) - Always an empty object (`{}`). Retrieve the full address with `id`
- `code` (integer, required)
- `message` (string, required)

Example response:

```json
{
  "result": {
    "hits": [
      {
        "suggestion": "10 Downing St, Montpelier, VT, 05602",
        "urls": {},
        "id": "usps_V210079628|10||3797"
      },
      {
        "suggestion": "10 Ten Downing St, Fountain Inn, SC, 29644",
        "urls": {},
        "id": "usps_X219061579|10||5031"
      },
      {
        "suggestion": "10 Downing St Apt 1, Montpelier, VT, 05602",
        "urls": {},
        "id": "usps_V210079629|10|1|3798"
      },
      {
        "suggestion": "2100 N Downing St Unit 10, Denver, CO, 80205",
        "urls": {},
        "id": "usps_Z125260298|2100|10|5272"
      },
      {
        "suggestion": "10 S Downing St, Denver, CO, 80209",
        "urls": {},
        "id": "usps_Z105732754|10||2411"
      },
      {
        "suggestion": "10 Downing St, Hollister, MO, 65672",
        "urls": {},
        "id": "usps_W112200302|10||5568"
      },
      {
        "suggestion": "10 Downing St, Greensboro, NC, 27410",
        "urls": {},
        "id": "usps_Y127860601|10||2448"
      },
      {
        "suggestion": "1 S Downing St Apt 10, Denver, CO, 80209",
        "urls": {},
        "id": "usps_Z105731302|1|10|2440"
      },
      {
        "suggestion": "1560 N Downing St Apt 10, Denver, CO, 80218",
        "urls": {},
        "id": "usps_Z122881416|1560|10|1538"
      },
      {
        "suggestion": "2202 N Downing St Apt 10, Denver, CO, 80205",
        "urls": {},
        "id": "usps_Z122964113|2202|10|5264"
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}
```

---

## GET /autocomplete/addresses/{address}/usa

**Retrieve Address**

Returns the full address for an autocomplete suggestion id.

This is the charged step of address autocomplete. A successful retrieval decrements your lookup balance. An id which resolves to no address returns `404`.

Every address comes back in one US-shaped format, whatever country or dataset it came from: up to two address lines and US field names such as `zip_code`, `state` and `city`.


**Path parameters**

- `address` (string, required) - **ID of address suggestion**

**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (object, required)
  - `id` (ID, required) - Global unique internally generated identifier for an address
  - `dataset` (Dataset, required) - Indicates the provenance of an address.
  - `country_iso` (CountryISO, required) - 3 letter country code (ISO 3166-1)
  - `country_iso_2` (CountryISO2, required) - 2 letter country code (ISO 3166-1)
  - `country` (Country, required) - Full country names (ISO 3166)
  - `language` (Language, required) - Language represented by 2 letter ISO Code (639-1)
  - `primary_number` (string, required) - Building, house, rural route, contract box or PO Box number. The numeric or alphanumeric component of an address preceding the street name.
  - `secondary_number` (string, required) - Number of the sub unit, apartment, suite etc.
  - `plus_4_code` (string, required) - 4 digit ZIP add-on code. USPS addresses only.
  - `line_1` (string, required) - The primary delivery line (usually the street address) of the address.
  - `line_2` (string, required) - Secondary delivery line of the address. Typically populated if the first line is the firm or building name.
  - `last_line` (string, required) - Final line of the address, comprising city, state or region and postal code.
  - `zip_code` (string, required) - Postal code identifying the delivery area. For US addresses this is the 5 digit ZIP Code.
  - `zip_plus_4_code` (string, required) - Nine-digit code that identifies a small geographic delivery area serviceable by a single carrier; appears in the last line of the address on a mail piece. USPS addresses only.
  - `update_key_number` (string, required) - Key that uniquely identifies the source dataset record. For USPS this is the Update Key Number: a database segment code (V1, V2, W1, W2, X1, X2, Y1, Y2, Z1 or Z2) followed by eight alphanumeric characters. It is fixed for the life of the record and is not used in address matching.
  - `record_type_code` (string, required) - An alphabetic value identifying the type of USPS record backing the address.
  - `carrier_route_id` (string, required) - A 4 character ID identifying the USPS postal route for the address. The first character indicates the route type:
  - `street_pre_directional_abbreviation` (string, required) - A geographic direction that precedes the street name.
  - `street_name` (string, required) - The official name of the street as assigned by the local governing authority. Contains the street name only, without directionals (EAST, WEST, etc.) or suffixes (ST, DR, BLVD, etc.). May also contain literals such as PO BOX, GENERAL DELIVERY, USS, PSC or UNIT.
  - `street_suffix_abbreviation` (string, required) - Standard abbreviation for the trailing designator in a street address.
  - `street_post_directional_abbreviation` (string, required) - A geographic direction that follows the street name.
  - `building_or_firm_name` (string, required) - The name of a company, building, apartment complex, shopping center or other distinguishing secondary address information.
  - `address_secondary_abbreviation` (string, required) - A descriptive code identifying the type of secondary range held in the secondary number field, e.g. apartment, suite or trailer.
  - `base_alternate_code` (string, required) - Code specifying whether the backing USPS record is a base (preferred) or alternate record.
  - `lacs_status_indicator` (string, required) - The Locatable Address Conversion Service (LACS) indicator marks USPS records converted to the LACS system, which lets mailers convert a rural route address to a city-style address so emergency services can locate it.
  - `government_building_indicator` (string, required) - An alphabetic value identifying the type of government agency at the delivery point and/or whether a firm is the only delivery at an address.
  - `state_abbreviation` (string, required) - Abbreviated name of the state, province or region. For US addresses this is the 2 character state, territory or armed forces designation ("AA", "AE" or "AP" for APO/FPO/DPO).
  - `state` (string, required) - Full name of the state, province or region.
  - `municipality_city_state_key` (string, required) - Municipality City State Key. Currently blank.
  - `urbanization_city_state_key` (string, required) - An index to the USPS City State file that provides the urbanization name for this delivery range.
  - `preferred_last_line_city_state_key` (string, required) - An index to the USPS City State product record that provides the preferred last-line name for this address range.
  - `county` (string, required) - Name of the county, parish or equivalent administrative area. Blank for APO/FPO/DPO addresses.
  - `city` (string, required) - City or town name used for mailing; appears in the last line of the address.
  - `city_abbreviation` (string, required) - A standard 13-character abbreviation for a city/state name. Only used for names longer than 13 characters with a city state mailing name indicator of "Y"; blank otherwise.
  - `preferred_city` (string, required) - The default preferred or alternate preferred last-line name for a ZIP Code.
  - `city_state_name_facility_code` (string, required) - The type of locale identified in the city/state name. The facility may be a USPS facility, such as a post office, station or branch, or a non-postal place name.
  - `zip_classification_code` (string, required) - Describes the type of ZIP area a 5-digit ZIP Code serves, e.g. a single educational institution, post office boxes only or a single address with unusually high mail volume.
  - `city_state_mailing_name_indicator` (string, required) - Specifies whether the city state name can be used as the last line of an address on a mail piece.
  - `carrier_route_rate_sortation` (string, required) - Identifies where automation Carrier Route rates are available and where the commingling of automation and non-automation mail, including Enhanced Carrier Routes and 5-digit presort, on the same pallet or in the same container is allowed.
  - `finance_number` (oneOf, required) - A code assigned to USPS facilities (primarily Post Offices) to collect cost and statistical data and compile revenue and expense data.
    - one of: string, number
  - `congressional_district_number` (oneOf, required) - A standard value identifying a geographic area within the United States served by a member of the U.S. House of Representatives. Blank for APO/FPO/DPO addresses. If there is only one member of Congress within a state, the code will be "AL" (at large).
    - one of: string, number
  - `county_number` (oneOf, required) - The Federal Information Processing Standard (FIPS) code assigned to a given county or parish within a state. In Alaska it identifies a region within the state. Blank for APO/FPO/DPO addresses whose record type is "S", "H" or "F".
    - one of: string, number
  - `native` (NativeRecord) - The raw dataset record backing an address, exactly as the dataset supplies it. One schema per dataset; `dataset` on the record says which.
    - one of: PafAddress, MrAddress, NybAddress, PafaAddress, PafwAddress, AbAddress, AbpAddress, UspsAddress, EcadAddress, EcafAddress, HereAddress, GnafAddress, KadasterAddress, KartverketAddress, SdfiAddress, CannarAddress, FodbosaAddress, MoisAddress, UpujpAddress, BevAddress, BanAddress, SwtAddress
    - `dataset` (string, required) - Dataset the record belongs to. The only field not taken from the Royal Mail record
    - `postcode` (string, required) - Postcode, space separated
    - `post_town` (string, required) - Royal Mail post town, title cased
    - `dependant_locality` (string, required) - Dependant locality. Empty string when not present
    - `double_dependant_locality` (string, required) - Double dependant locality. Empty string when not present
    - `thoroughfare` (string, required) - Street name
    - `dependant_thoroughfare` (string, required) - Dependant street name. Empty string when not present
    - `building_number` (string, required) - Building number. Empty string when not present, or when PAF merges it into the building name
    - `building_name` (string, required) - Building name. Empty string when not present
    - `sub_building_name` (string, required) - Sub building name. Empty string when not present
    - `department_name` (string, required) - Department name within an organisation. Empty string when not present
    - `organisation_name` (string, required) - Organisation name. Empty string when not present
    - `udprn` (integer, required) - Unique Delivery Point Reference Number
    - `postcode_type` (string, required) - Postcode type.
    - `su_organisation_indicator` (string, required) - Small user organisation indicator. `Y` where the small user postcode is held by an organisation
    - `delivery_point_suffix` (string, required) - Royal Mail delivery point suffix
    - `po_box` (string, required) - PO Box number. Empty string when not present
    - `dataset` (string)

---

## GET /places

**Find Place**

Returns place suggestions for a query, ranked by relevance. Places cover countries, administrative areas, capitals and other administrative seats.

## Implementing Place Autocomplete

Retrieving a full place takes two requests:

1. Fetch suggestions from `/places`
2. Fetch the place using the `id` on a suggestion

A query returns at most 10 suggestions. An empty query returns an empty result set. Show users the `descriptive_name`. The API drops suggestions that share one, so each name in a response identifies a single place.

## Rate Limiting and Cost

The rate limit is 3,000 requests per 5 minutes.

`/places` does not decrement your lookup balance, but resolving a suggestion to a full place does. We rate limit and then suspend integrations that repeatedly call `/places` without resolving.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Query parameters**

- `query` (string) - Specifies the place to query. Can be shortened to `q=`

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (object, required)
  - `hits` (array<any>, required) - List of up to 10 matching places
    - one of: PlaceSuggestion
    - `id` (place_id, required) - Unique identifier for place
    - `name` (place_name, required) - Place name
    - `descriptive_name` (place_descriptive_name, required) - Longer form description of the place.
    - `country_iso` (place_country_iso, required) - 3 letter country code (ISO 3166-1)

Example response:

```json
{
  "result": {
    "hits": [
      {
        "id": "geonames_2643743",
        "name": "London",
        "descriptive_name": "London, Greater London, England",
        "country_iso": "GBR"
      },
      {
        "id": "geonames_4517009",
        "name": "London",
        "descriptive_name": "London, Madison County, Ohio",
        "country_iso": "USA"
      },
      {
        "id": "geonames_4298960",
        "name": "London",
        "descriptive_name": "London, Laurel County, Kentucky",
        "country_iso": "USA"
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}
```

---

## GET /places/{place}

**Resolve Place**

Returns the full place for a place ID taken from a `/places` suggestion.

On top of the fields carried by the suggestion, the response adds coordinates, language and the underlying dataset record.

Each request decrements your lookup balance. An unknown ID returns `404`.


**Path parameters**

- `place` (string, required) - ID of place suggestion

**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (Place, required) - A geographical place: an administrative division, capital or seat of administration city drawn from GeoNames. `GET /places` returns a suggestion for each match and `GET /places/{place}` resolves a suggestion id to the full place. `native` holds the underlying GeoNames record.
  - `id` (string, required) - Global unique internally generated identifier for a place
  - `dataset` (string, required) - Indicates the provenance of a place.
  - `name` (place_name, required) - Place name
  - `descriptive_name` (place_descriptive_name, required) - Longer form description of the place.
  - `country_iso` (place_country_iso, required) - 3 letter country code (ISO 3166-1)
  - `language` (Language, required) - Language represented by 2 letter ISO Code (639-1)
  - `longitude` (Longitude, required) - The longitude of the address or postcode (WGS84).
    - one of: string, number
  - `latitude` (Latitude, required) - The latitude of the address or postcode (WGS84).
    - one of: string, number
  - `native` (oneOf, required) - Native representation of a place
    - one of: GeonamesPlace
    - `id` (string, required) - Unique place ID
    - `dataset` (string, required) - Indicates the provenance of a place
    - `geonameid` (integer, required) - Unique identifier for GeoNames place
    - `name` (string, required) - Place name (UTF8)
    - `asciiname` (string, required) - Place name (ASCII). Empty string if not available
    - `alternatenames` (array<string>, required) - List of alternate names for the place
    - `language` (Language, required) - Language represented by 2 letter ISO Code (639-1)
    - `latitude` (Latitude, required) - The latitude of the address or postcode (WGS84).
      - one of: string, number
    - `longitude` (Longitude, required) - The longitude of the address or postcode (WGS84).
      - one of: string, number
    - `feature_class` (string, required) - GeoNames single letter feature class (http://www.geonames.org/export/codes.html). Only two are indexed
    - `feature_code` (string, required) - Full GeoNames feature code (http://www.geonames.org/export/codes.html)
    - `country_code` (string, required) - 2 letter ISO country code. Empty string if not available
    - `country_iso` (string, required) - 3 letter ISO country code derived from `country_code`. Empty string if the country cannot be resolved
    - `cc2` (array<string>, required) - List of other country codes mapping to this place
    - `admin1_name` (string, required) - Name of first administrative area. Empty string if not available
    - `admin1_geonameid` (integer, required) - GeoName ID for first administrative area
    - `admin1_code` (string, required) - Fipscode (subject to change to iso code)
    - `admin2_name` (string, required) - Name of second administrative area. Empty string if not available
    - `admin2_geonameid` (integer, required) - GeoName ID for second administrative area
    - `admin2_code` (string, required) - Code for the second administrative division
    - `admin3_code` (string, required) - Code for third level administrative division
    - `admin4_code` (string, required) - Code for fourth level administrative division
    - `population` (string, required) - Population at place. Represented as a string as it can be larger than a 32 bit integer
    - `elevation` (integer, required) - Elevation in metres. `null` if not available
    - `dem` (integer, required) - Digital elevation model (srtm3 or gtopo30), average elevation in metres
    - `timezone` (string, required) - The IANA timezone ID. Empty string if not available
    - `modification_date` (string, required) - Date the GeoNames record was last modified

Example response:

```json
{
  "result": {
    "id": "geonames_2643743",
    "dataset": "geonames",
    "name": "London",
    "descriptive_name": "London, Greater London, England",
    "language": "en",
    "longitude": -0.12574,
    "latitude": 51.50853,
    "country_iso": "GBR",
    "native": {
      "admin1_code": "ENG",
      "admin2_name": "Greater London",
      "geonameid": 2643743,
      "timezone": "Europe/London",
      "latitude": 51.50853,
      "language": "en",
      "dem": 25,
      "admin4_code": "",
      "admin1_geonameid": 6269131,
      "alternatenames": [
        "ILondon",
        "LON",
        "Lakana",
        "Landan",
        "Landen",
        "Ljondan",
        "Llundain",
        "Lodoni",
        "Londain",
        "Londan",
        "Londar",
        "Londe",
        "Londen",
        "Londin",
        "Londinium",
        "Londino",
        "Londn",
        "London",
        "London osh",
        "Londona",
        "Londonas",
        "Londoni",
        "Londono",
        "Londons",
        "Londonu",
        "Londra",
        "Londres",
        "Londrez",
        "Londri",
        "Londro",
        "Londye",
        "Londyn",
        "Londýn",
        "Lonn",
        "Lontoo",
        "Loundres",
        "Luan GJon",
        "Lun-tun",
        "Lunden",
        "Lundra",
        "Lundun",
        "Lundunir",
        "Lundúnir",
        "Lung-dung",
        "Lunnainn",
        "Lunnin",
        "Lunnon",
        "Luân Đôn",
        "Lùn-tûn",
        "Lùng-dŭng",
        "Lûn-tun",
        "Lākana",
        "Lůndůn",
        "Lọndọnu",
        "Ranana",
        "Rānana",
        "ilantan",
        "ladana",
        "landan",
        "landana",
        "leondeon",
        "lndn",
        "london",
        "londoni",
        "lun dui",
        "lun dun",
        "lwndwn",
        "lxndxn",
        "rondon",
        "Łondra",
        "Λονδίνο",
        "Лондан",
        "Лондон",
        "Лондон ош",
        "Лондонъ",
        "Лёндан",
        "Լոնդոն",
        "לאנדאן",
        "לונדון",
        "لأندأن",
        "لندن",
        "لوندون",
        "لەندەن",
        "ܠܘܢܕܘܢ",
        "लंडन",
        "लंदन",
        "लण्डन",
        "लन्डन्",
        "लन्दन",
        "লন্ডন",
        "ਲੰਡਨ",
        "લંડન",
        "ଲ୍ଡନ",
        "இலண்டன்",
        "లండన్",
        "ಲಂಡನ್",
        "ലണ്ടൻ",
        "ලන්ඩන්",
        "ลอนดอน",
        "ລອນດອນ",
        "ལོན་ཊོན།",
        "လန်ဒန်မြို့",
        "ლონდონი",
        "ለንደን",
        "ᎫᎴ ᏗᏍᎪᏂᎯᏱ",
        "ロンドン",
        "伦敦",
        "倫敦",
        "런던"
      ],
      "cc2": [],
      "admin2_code": "GLA",
      "modification_date": "2022-03-09T00:00:00.000Z",
      "asciiname": "London",
      "id": "geonames_2643743",
      "feature_code": "PPLC",
      "country_iso": "GBR",
      "longitude": -0.12574,
      "elevation": null,
      "admin2_geonameid": 2648110,
      "admin1_name": "England",
      "population": "8961989",
      "country_code": "GB",
      "feature_class": "P",
      "name": "London",
      "admin3_code": "",
      "dataset": "geonames"
    }
  },
  "code": 2000,
  "message": "Success"
}
```

---

## GET /keys/{key}/licensees

**List**

Returns a key's licensees, oldest first, up to 100 per request. The list omits canceled licensees. The key must be enabled for sub-licensing.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Query parameters**

- `starting_after` (integer) - ID of the licensee after which to list results
- `query` (string) - Filter results by licensee name. Can be shortened to `q=`

**Response (200)**

- `result` (object, required) - List of licensees
  - `licensees` (array<Licensee>)
    - `name` (string) - Licensee individual or organisation name
    - `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
    - `postcode` (string) - Licensee's postcode
    - `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
    - `daily` (object)
      - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active
    - `id` (string, required) - An immutable ID provided for every licensee. Primarily used for paginated list requests.
    - `key` (string, required) - Uniquely identifies a licensee for a key.
    - `createdAt` (string, required) - Timestamp for when the licensee was created
    - `daily` (object, required)
      - `count` (number, required) - The number of lookups performed by the licensee on the day represented by `licensees.daily.updatedAt`
      - `updatedAt` (string, required) - The timestamp when the limit was last used.
  - `hasMore` (boolean) - Returns true if there are more licensees listed after the maximum number of results as implied by `limit`
- `message` (string, required)
- `code` (integer, required)

---

## POST /keys/{key}/licensees

**Create**

Creates a licensee on a key and returns it with its generated `sl_` key. The key must be enabled for sub-licensing.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Request body**

- `name` (string) - Licensee individual or organisation name
- `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
- `postcode` (string) - Licensee's postcode
- `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
- `daily` (object)
  - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active

**Response (200)**

- `result` (Licensee, required)
  - `name` (string) - Licensee individual or organisation name
  - `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
  - `postcode` (string) - Licensee's postcode
  - `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
  - `daily` (object)
    - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active
  - `id` (string, required) - An immutable ID provided for every licensee. Primarily used for paginated list requests.
  - `key` (string, required) - Uniquely identifies a licensee for a key.
  - `createdAt` (string, required) - Timestamp for when the licensee was created
  - `daily` (object, required)
    - `count` (number, required) - The number of lookups performed by the licensee on the day represented by `licensees.daily.updatedAt`
    - `updatedAt` (string, required) - The timestamp when the limit was last used.
- `code` (integer, required)
- `message` (string, required)

---

## GET /keys/{key}/licensees/{licensee}

**Retrieve**

Returns a licensee by its `sl_` key. A canceled or unknown licensee returns `404`.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (Licensee, required)
  - `name` (string) - Licensee individual or organisation name
  - `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
  - `postcode` (string) - Licensee's postcode
  - `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
  - `daily` (object)
    - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active
  - `id` (string, required) - An immutable ID provided for every licensee. Primarily used for paginated list requests.
  - `key` (string, required) - Uniquely identifies a licensee for a key.
  - `createdAt` (string, required) - Timestamp for when the licensee was created
  - `daily` (object, required)
    - `count` (number, required) - The number of lookups performed by the licensee on the day represented by `licensees.daily.updatedAt`
    - `updatedAt` (string, required) - The timestamp when the limit was last used.
- `code` (integer, required)
- `message` (string, required)

---

## POST /keys/{key}/licensees/{licensee}

**Update**

Updates a licensee's address, postcode, allowed URLs and daily limit. Returns the updated licensee. The name is fixed at creation.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Request body**

- `name` (string) - Licensee individual or organisation name
- `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
- `postcode` (string) - Licensee's postcode
- `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
- `daily` (object)
  - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active

**Response (200)**

- `result` (Licensee, required)
  - `name` (string) - Licensee individual or organisation name
  - `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
  - `postcode` (string) - Licensee's postcode
  - `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
  - `daily` (object)
    - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active
  - `id` (string, required) - An immutable ID provided for every licensee. Primarily used for paginated list requests.
  - `key` (string, required) - Uniquely identifies a licensee for a key.
  - `createdAt` (string, required) - Timestamp for when the licensee was created
  - `daily` (object, required)
    - `count` (number, required) - The number of lookups performed by the licensee on the day represented by `licensees.daily.updatedAt`
    - `updatedAt` (string, required) - The timestamp when the limit was last used.
- `code` (integer, required)
- `message` (string, required)

---

## DELETE /keys/{key}/licensees/{licensee}

**Cancel**

Cancels a licensee. Its key stops working and it drops out of the licensee list. Contact us to reverse it.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (object, required)
  - `deleted` (number, required)
- `code` (integer, required)
- `message` (string, required)

---

## POST /keys/{key}/licensees/{licensee}/regenerate-key

**Regenerate Key**

Regenerates a licensee's key and returns the licensee with the new key. The previous key stops working immediately, so update any integration that uses it.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (Licensee, required)
  - `name` (string) - Licensee individual or organisation name
  - `address` (string) - Licensee's first, second and third line address as well as post town concatenated by commas
  - `postcode` (string) - Licensee's postcode
  - `whitelist` (array<string>) - A list of allowed URLs. An empty list disables the check.
  - `daily` (object)
    - `limit` (number) - The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active
  - `id` (string, required) - An immutable ID provided for every licensee. Primarily used for paginated list requests.
  - `key` (string, required) - Uniquely identifies a licensee for a key.
  - `createdAt` (string, required) - Timestamp for when the licensee was created
  - `daily` (object, required)
    - `count` (number, required) - The number of lookups performed by the licensee on the day represented by `licensees.daily.updatedAt`
    - `updatedAt` (string, required) - The timestamp when the limit was last used.
- `code` (integer, required)
- `message` (string, required)

---

## GET /keys/{key}/configs

**List**

Returns every configuration stored against a key, oldest first.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (object, required) - List of configurations
  - `configs` (array<Config>, required)
    - `updatedAt` (string, required) - Timestamp for when the config was created
    - `createdAt` (string, required) - Timestamp for when the config was updated
    - `name` (string, required) - A unique name to identify the configuration payload
    - `payload` (string, required) - A serialised payload of up to `65536` characters
- `message` (string, required)
- `code` (integer, required)

---

## POST /keys/{key}/configs

**Create**

Creates a named configuration on a key and returns it.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Request body**

- `name` (string, required) - A unique name to identify the configuration payload
- `payload` (string, required) - A serialized payload of up to `65536` characters

**Response (200)**

- `result` (Config, required)
  - `updatedAt` (string, required) - Timestamp for when the config was created
  - `createdAt` (string, required) - Timestamp for when the config was updated
  - `name` (string, required) - A unique name to identify the configuration payload
  - `payload` (string, required) - A serialised payload of up to `65536` characters
- `code` (integer, required)
- `message` (string, required)

---

## GET /keys/{key}/configs/{config}

**Retrieve**

Returns a configuration by name. This request needs no `user_token`, so a browser integration can read its own configuration at runtime.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (Config, required)
  - `updatedAt` (string, required) - Timestamp for when the config was created
  - `createdAt` (string, required) - Timestamp for when the config was updated
  - `name` (string, required) - A unique name to identify the configuration payload
  - `payload` (string, required) - A serialised payload of up to `65536` characters
- `code` (integer, required)
- `message` (string, required)

---

## POST /keys/{key}/configs/{config}

**Update**

Replaces a configuration's payload and returns the updated configuration. The name is fixed at creation.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Request body**

- `payload` (string) - A serialized payload of up to `65536` characters

**Response (200)**

- `result` (Config, required)
  - `updatedAt` (string, required) - Timestamp for when the config was created
  - `createdAt` (string, required) - Timestamp for when the config was updated
  - `name` (string, required) - A unique name to identify the configuration payload
  - `payload` (string, required) - A serialised payload of up to `65536` characters
- `code` (integer, required)
- `message` (string, required)

---

## DELETE /keys/{key}/configs/{config}

**Delete**

Permanently deletes a configuration object.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)
- `undefined` (string)

**Response (200)**

- `result` (object, required)
  - `deleted` (number, required)
- `code` (integer, required)
- `message` (string, required)

---

## GET /emails

**Email Validation**

Validates an email address and reports whether it is deliverable.

Requires an API Key licensed for email validation. A query over 320 characters is rejected.

A validated address decrements your lookup balance. An address the API cannot check returns `unknown` and costs no lookup. An address whose domain does not resolve, or publishes no MX records, returns `not_deliverable` and also costs no lookup. Only those two domain failures populate `suggestions`. Every other response returns an empty list.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Query parameters**

- `query` (string, required) - Specifies the email address to validate

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (oneOf, required)
  - one of: Email, UnknownEmail
  - `result` (string, required)
  - `deliverable` (boolean, required) - Returns `true` if the email can be delivered
  - `disposable` (boolean, required) - Returns `true` if email comes from a disposable email service like temp-mail
  - `free` (boolean, required) - Returns `true` if the email originates from a free service like Outlook or Gmail.
  - `role` (boolean, required) - Returns `true` if email address represents an organisational role like `admin`, `support`, `postmaster` etc
  - `catchall` (boolean, required) - Returns `true` if this domain accepts all emails regardless of username
  - `suggestions` (array<string>, required) - Returns an array of suggested email addresses if the email address is not deliverable. The suggested emails are not validated.

Example response:

```json
{
  "result": {
    "result": "deliverable",
    "deliverable": true,
    "catchall": false,
    "free": false,
    "role": true,
    "disposable": false,
    "suggestions": []
  },
  "code": 2000,
  "message": "Success"
}
```

---

## GET /phone_numbers

**Phone Number Validation**

Validates a phone number and returns its country, its national and international formats, and the network it was originally assigned to.

Requires an API Key licensed for phone validation.

Every query decrements your lookup balance, including a number that fails to parse and a number reported as invalid.


**Undefined parameters**

- `undefined` (string)
- `undefined` (string)

**Query parameters**

- `query` (string, required) - Specifies the phone number to validate. Phone number must include a country code in an acceptable format. For instance, UK phone numbers should be prefixed with `+44`, `44` or `0044`.
- `current_carrier` (string) - When set to `true`, the API retrieves and populates the current network of the phone number.

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (oneOf, required)
  - one of: PhoneNumber, InvalidPhoneNumber
  - `valid` (boolean, required)
  - `national_format` (string, required) - Phone number formatted to local standard
  - `international_format` (string, required) - Phone number formatted to international standard
  - `iso_country` (string, required) - Country code in 3 letter ISO format
  - `iso_country_2` (string, required) - Country code in 2 letter ISO format
  - `country` (string, required) - Full country name
  - `current_carrier` (Carrier, required)
    - `network_code` (string, required) - The [Mobile Country Code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier.
    - `name` (string, required) - The full name of the carrier that number is associated with.
    - `country` (string, required) - Country that number is associated with. In ISO 3166-1 alpha-2 format.
    - `network_type` (string, required) - Type of network that number is associated with.
  - `original_carrier` (Carrier, required)
    - `network_code` (string, required) - The [Mobile Country Code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier.
    - `name` (string, required) - The full name of the carrier that number is associated with.
    - `country` (string, required) - Country that number is associated with. In ISO 3166-1 alpha-2 format.
    - `network_type` (string, required) - Type of network that number is associated with.

Example response:

```json
{
  "result": {
    "valid": true,
    "national_format": "020 7112 8019",
    "international_format": "+44 20 7112 8019",
    "iso_country": "GBR",
    "iso_country_2": "GB",
    "country": "United Kingdom",
    "current_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    },
    "original_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    }
  },
  "code": 2000,
  "message": "Success"
}
```

---

## POST /sign_up

**Mint CLI Signup Token**

Mints a one-shot `cli_token` and returns a prefilled signup URL. The user opens the URL, clears the captcha, accepts the Terms of Service and creates the account. The CLI then polls `GET /sign_up/{cli_token}` until the accounts service has propagated the new user and its first API key, at which point the API returns the credentials exactly once.

The API does not store the `cli_token` when it mints it. The token becomes known to the API only once the accounts service propagates the new user, so the CLI must set its own polling deadline. If the user never completes signup, `GET /sign_up/{cli_token}` returns `202 Accepted` indefinitely.


**Request body**

- `email` (string, required) - Account holder's email address.
- `name` (string, required) - Account holder's full name.
- `org_name` (string, required) - Organization name.
- `org_address_line_one` (string, required)
- `org_address_line_two` (string)
- `org_address_line_three` (string)
- `org_post_town` (string, required)
- `org_postcode` (string, required)
- `org_country_code` (string, required) - ISO 3166-1 alpha-2 country code.

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (object, required)
  - `cli_token` (string, required) - Random URL-safe token (base64url). Used by the CLI to poll for credentials.
  - `signup_url` (string, required) - Prefilled accounts web URL. The user opens this in a browser to complete signup.

---

## GET /sign_up/{cli_token}

**Poll CLI Signup Token**

Returns the account credentials for a minted `cli_token` once signup has completed, and `202 Accepted` until then. The CLI calls this endpoint repeatedly after sending the user to the `signup_url` returned by `POST /sign_up`.

- `202 Accepted`. The accounts service has not propagated the user yet, or has propagated the user but not minted the first API key. Keep polling. An unknown token also returns `202`, because the API does not record a token at mint time, so the CLI must set its own polling deadline.
- `200 OK`. The user and first API key exist. The API returns the credentials once. Later polls return `410 Gone`.
- `410 Gone`. The token has expired or has already been claimed.


**Path parameters**

- `cli_token` (string, required) - The token returned by `POST /sign_up`.

**Response (200)**

- `code` (integer, required)
- `message` (string, required)
- `result` (object, required)
  - `user_token` (string, required) - User-level token used to manage account resources via the api.
  - `test_api_key` (string, required) - Initial test API key for the account.
  - `user_id` (string, required) - Internal api user id.