# API Reference - OpenAPI Reference Version: 5.1.1 Complete machine-readable reference for every API operation, generated from the OpenAPI specification. --- ## GET /postcodes/{postcode} **Lookup Postcode** Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive. Each request looks up one postcode. To extract the addresses for several postcodes, send one request per postcode. Use it to power postcode driven address searches, like [Postcode Lookup](/docs/postcode-lookup/). Postcode lookup covers the United Kingdom, the Republic of Ireland, the Netherlands and Singapore. The API detects the format of the postcode you submit. UK and Irish postcodes are searched by default. For a Dutch or Singapore postcode, set `context` to `NLD` or `SGP`, or to `GLOBAL` to accept any supported format. UK postcodes need PAF, Multiple Residence, Not Yet Built, PAF Alias, PAF Welsh, AddressBase or AddressBase Premium on your key. Eircodes need ECAD or ECAF. Dutch postcodes need Kadaster. Singapore postcodes need HERE Asia Pacific. Without a matching licence the request is rejected. An unfound postcode costs no lookup. A postcode that returns addresses costs one. ## Postcode Not Found Invalid postcodes do not affect your lookup balance. The API returns a `404` response with this body: ```json { "code": 4040, "message": "Postcode not found", "suggestions": ["SW1A 0AA"] } ``` ### Suggestions If a postcode cannot be found, the API returns up to 5 of the closest matching postcodes. It corrects common errors first (e.g. mixing up `O` and `0` or `I` and `1`). If the suggestion list is small (fewer than 3), the correct postcode is likely to be among them. Notify the user or trigger new searches immediately. The suggestion list is empty if the postcode has deviated too far from a valid postcode format. ## Multiple Residence A small number of postcodes return more than 100 premises. The API returns 100 addresses per page, so use `page` to paginate the result set. **Path parameters** - `postcode` (string, required) - Postcode to retrieve **Undefined parameters** - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) **Response (200)** - `result` (array, required) - All addresses listed at the postcode. - `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) - `line_1` (string, required) - First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second address line. Often contains thoroughfare and locality information. May be empty. - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `post_town` (string, required) - The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. - `postcode` (string, required) - Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. - `county` (string, required) - Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. - `county_code` (string, required) - Short code representing the county or province. May be empty (`""`) - `uprn` (string, required) - UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property. - `udprn` (oneOf, required) - UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. - one of: integer, string - `umprn` (oneOf, required) - A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant. - one of: string, number - `postcode_outward` (string, required) - The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. 'PO1', 'SW1A' or 'B23'. - `postcode_inward` (string, required) - The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. - `dependant_locality` (string, required) - A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. - `double_dependant_locality` (string, required) - Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. - `thoroughfare` (string, required) - Also known as the street or road name. May be empty. - `dependant_thoroughfare` (string, required) - Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. - `building_number` (string, required) - Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. - `building_name` (string, required) - Name of a residential or commercial premise. May be empty. - `sub_building_name` (string, required) - Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B. May be empty. - `po_box` (string, required) - PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. - `department_name` (string, required) - Supplements organisation name to identify a department within the organisation. May be empty. - `organisation_name` (string, required) - Name of the business or organisation at this address. May be empty. - `postcode_type` (object, required) - Royal Mail postcode user type. UK addresses only. - `su_organisation_indicator` (string, required) - `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. - `delivery_point_suffix` (string, required) - Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. - `premise` (string, required) - A pre-computed string which sensibly combines building_number, building_name and sub_building_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. May be empty. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `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 - `eastings` (Eastings, required) - Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `northings` (Northings, required) - Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `native` (oneOf) - The raw dataset record backing this address. On these two endpoints it is returned for AddressBase (`ab`, `abp`) and non-UK datasets only, never for the PAF family. Use any other endpoint for a PAF native record. - one of: AbAddress, AbpAddress, UspsAddress, EcadAddress, EcafAddress, HereAddress, GnafAddress, KadasterAddress, KartverketAddress, SdfiAddress, CannarAddress, FodbosaAddress, MoisAddress, UpujpAddress, BevAddress, BanAddress, SwtAddress - `id` (ID, required) - Global unique internally generated identifier for an address - `country_iso` (string, required) - 3 letter country code (ISO 3166-1) - `dataset` (string, required) - Indicates the provenance of an address - `language` (Language, required) - Language represented by 2 letter ISO Code (639-1) - `line_1` (string, required) - First Address Line. Often contains premise and thoroughfare information. In the case of a commercial premise, the first line is always the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `premise` (string, required) - A pre-computed string which sensibly combines the building name, sub-building and building number fields into a single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using the address lines. - `uprn` (string, required) - Unique Property Reference Number (UPRN) assigned by the LLPG Custodian or Ordnance Survey. - `udprn` (integer, required) - Royal Mail's Unique Delivery Point Reference Number (UDPRN). `0` where the record has no matching PAF delivery point. - `parent_uprn` (string, required) - UPRN of the parent record where a parent-child relationship exists. Empty where the record has no parent. - `usrn` (integer, required) - Unique Street Reference Number assigned by the Street Name and Numbering Custodian or by Ordnance Survey, depending on the address record. - `toid` (string, required) - The Topographic Identifier taken from OS MasterMap Topography Layer. This TOID is assigned to the UPRN by performing a spatial intersection between the two identifiers. It consists of the letters 'osgb' followed by up to sixteen digits. May be empty. - `classification_code` (string, required) - A code that describes the classification of the address record to a maximum of a secondary level. The first letter is the primary class (e.g. `R` residential, `C` commercial, `L` land), the second the secondary class (e.g. `RD` dwelling). - `eastings` (number, required) - A value in metres defining the x location in accordance with the British National Grid. - `northings` (number, required) - A value in metres defining the y location in accordance with the British National Grid. - `latitude` (number, required) - A value defining the Latitude location in accordance with the ETRS89 coordinate reference system. - `longitude` (number, required) - A value defining the Longitude location in accordance with the ETRS89 coordinate reference system. - `single_address_line` (string, required) - A single attribute containing text concatenation of the address elements separated by a comma. - `street_name` (string, required) - Street / Road name for the address record. - `locality` (string, required) - A locality defines an area or geographical identifier within a town, village or hamlet. Locality represents the lower level geographical area. The locality field should be used in conjunction with the town name and street description fields to uniquely identify geographic area where there may be more than one within an administrative area. - `town_name` (string, required) - Geographical town name assigned by the Local Authority. Note this can differ from the post town assigned by Royal Mail. - `delivery_point_suffix` (string, required) - A two-character code uniquely identifying an individual delivery point within a postcode, assigned by Royal Mail. May be empty. - `post_town` (string, required) - The town or city in which the Royal Mail sorting office servicing this address record is located. - `gss_code` (string, required) - The Office for National Statistics Governmental Statistical Service (GSS) code representing the contributing Local Authority. - `rpc` (integer, required) - Representative Point Code describes the accuracy of the coordinate that has been allocated to the UPRN as indicated by the Local Authority and enhanced using large scale OS data. - `last_update_date` (string, required) - The latest date on which any of the attributes on this record were last changed. - `island` (string, required) - Third level of geographic area name to record island names where appropriate. May be empty. - `change_code` (string, required) - The type of change last applied to the record. `I` insert, `U` update, `D` delete. - `building_name` (string, required) - The building name is a description applied to a single address or a group of addresses. May be empty. - `building_number` (string, required) - The building number is a number or range of numbers given to a single address or a group of addresses. May be empty. - `sub_building` (string, required) - The sub-building name and/or number for the address record. May be empty. - `postcode` (string, required) - A postcode assigned by Royal Mail for the address record. - `po_box` (string, required) - Text concatenation of 'PO BOX' and the Post Office Box (PO Box) number or 'BFPO' and the British Forces Post Office number. May be empty. - `organisation` (string, required) - The organisation name is the business name given, when appropriate, to an address record. May be empty. - `country` (string, required) - Full country names (ISO 3166) - `county` (string, required) - Since postal, administrative or traditional counties may not apply to some addresses, the county field is designed to return whatever county data is available. Normally, the postal county is returned. If this is not present, the county field will fall back to the administrative county. If the administrative county is also not present, the county field will fall back to the traditional county. May be empty in cases where no administrative, postal or traditional county present. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `code` (integer, required) - `message` (string, required) - `page` (integer, required) - `limit` (integer, required) - `total` (integer, required) Example response: ```json { "result": [ { "postcode": "SW1A 2AA", "postcode_inward": "2AA", "postcode_outward": "SW1A", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Prime Minister & First Lord Of The Treasury", "line_2": "10 Downing Street", "line_3": "", "premise": "10", "longitude": -0.12767, "latitude": 51.503541, "eastings": 530047, "northings": 179951, "country": "England", "traditional_county": "Greater London", "administrative_county": "", "postal_county": "London", "county": "London", "district": "Westminster", "ward": "St. James's", "uprn": "100023336956", "id": "paf_23747771", "country_iso": "GBR", "country_iso_2": "GB", "county_code": "", "language": "en", "umprn": "", "dataset": "paf" } ], "code": 2000, "message": "Success", "limit": 100, "page": 0, "total": 1 } ``` --- ## GET /udprn/{udprn} **Retrieve by UDPRN** Returns the full address for a Unique Delivery Point Reference Number (UDPRN). Storing the UDPRN lets you retrieve the most recent information for an address, and test whether an address has been deleted. UDPRNs are an eight digit unique numeric code (e.g. `25962203`) for any premise on the Postcode Address File, Royal Mail's database of UK addresses. The API searches PAF first, then Not Yet Built if your key is licensed for it. A UDPRN on neither dataset returns `404`. Each address returned costs a lookup. ## Testing We provide test UDPRNs that yield both successful and unsuccessful responses. They are: - `0` Returns a successful UDPRN lookup response `2000` - `-1` Returns "UDPRN not found", error `4044` - `-2` Returns "no lookups remaining", error `4020` - `-3` Returns "daily (or individual) lookup limit breached", error `4021` Test requests undergo the usual authentication and restriction rules. They surface any issues during implementation and do not cost you a lookup. **Path parameters** - `udprn` (string, required) - UDPRN to retrieve **Undefined parameters** - `undefined` (string) - `undefined` (string) **Response (200)** - `result` (Address, required) - The standard Ideal Postcodes address, which maps both UK and International addresses. - `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) - `line_1` (string, required) - First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second address line. Often contains thoroughfare and locality information. May be empty. - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `post_town` (string, required) - The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. - `postcode` (string, required) - Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. - `county` (string, required) - Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. - `county_code` (string, required) - Short code representing the county or province. May be empty (`""`) - `uprn` (string, required) - UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property. - `udprn` (oneOf, required) - UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. - one of: integer, string - `umprn` (oneOf, required) - A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant. - one of: string, number - `postcode_outward` (string, required) - The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. 'PO1', 'SW1A' or 'B23'. - `postcode_inward` (string, required) - The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. - `dependant_locality` (string, required) - A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. - `double_dependant_locality` (string, required) - Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. - `thoroughfare` (string, required) - Also known as the street or road name. May be empty. - `dependant_thoroughfare` (string, required) - Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. - `building_number` (string, required) - Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. - `building_name` (string, required) - Name of a residential or commercial premise. May be empty. - `sub_building_name` (string, required) - Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B. May be empty. - `po_box` (string, required) - PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. - `department_name` (string, required) - Supplements organisation name to identify a department within the organisation. May be empty. - `organisation_name` (string, required) - Name of the business or organisation at this address. May be empty. - `postcode_type` (object, required) - Royal Mail postcode user type. UK addresses only. - `su_organisation_indicator` (string, required) - `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. - `delivery_point_suffix` (string, required) - Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. - `premise` (string, required) - A pre-computed string which sensibly combines building_number, building_name and sub_building_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. May be empty. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `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 - `eastings` (Eastings, required) - Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `northings` (Northings, required) - Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `native` (NativeRecord, required) - 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) - `code` (integer, required) - `message` (string, required) Example response: ```json { "result": { "postcode": "SW1A 2AA", "postcode_inward": "2AA", "postcode_outward": "SW1A", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Prime Minister & First Lord Of The Treasury", "line_2": "10 Downing Street", "line_3": "", "premise": "10", "longitude": -0.12767, "latitude": 51.503541, "eastings": 530047, "northings": 179951, "country": "England", "traditional_county": "Greater London", "administrative_county": "", "postal_county": "London", "county": "London", "district": "Westminster", "ward": "St. James's", "uprn": "100023336956", "id": "paf_23747771", "country_iso": "GBR", "country_iso_2": "GB", "county_code": "", "language": "en", "umprn": "", "dataset": "paf", "native": { "dataset": "paf", "postcode": "SW1A 2AA", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A" } }, "code": 2000, "message": "Success" } ``` --- ## GET /umprn/{umprn} **Retrieve by UMPRN** Returns the address for a multiple occupancy household, identified by its UMPRN (Multiple Residence Unique ID). UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset. Your key needs that dataset enabled. Without it, and for any UMPRN we cannot find, the API returns `404`. ## Pricing Per lookup charges apply. We do not charge for empty responses. ## Testing We provide test UMPRNs that yield both successful and unsuccessful responses. They are: - `0` Returns a successful UMPRN lookup response `2000` - `-1` Returns "UMPRN not found", error `4046` - `-2` Returns "no lookups remaining", error `4020` - `-3` Returns "daily (or individual) lookup limit breached", error `4021` Test requests undergo the usual authentication and restriction rules. They surface any issues during implementation and do not cost you a lookup. **Path parameters** - `umprn` (string, required) - UMPRN to retrieve **Undefined parameters** - `undefined` (string) - `undefined` (string) **Response (200)** - `result` (Address, required) - The standard Ideal Postcodes address, which maps both UK and International addresses. - `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) - `line_1` (string, required) - First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second address line. Often contains thoroughfare and locality information. May be empty. - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `post_town` (string, required) - The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. - `postcode` (string, required) - Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. - `county` (string, required) - Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. - `county_code` (string, required) - Short code representing the county or province. May be empty (`""`) - `uprn` (string, required) - UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property. - `udprn` (oneOf, required) - UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. - one of: integer, string - `umprn` (oneOf, required) - A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant. - one of: string, number - `postcode_outward` (string, required) - The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. 'PO1', 'SW1A' or 'B23'. - `postcode_inward` (string, required) - The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. - `dependant_locality` (string, required) - A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. - `double_dependant_locality` (string, required) - Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. - `thoroughfare` (string, required) - Also known as the street or road name. May be empty. - `dependant_thoroughfare` (string, required) - Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. - `building_number` (string, required) - Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. - `building_name` (string, required) - Name of a residential or commercial premise. May be empty. - `sub_building_name` (string, required) - Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B. May be empty. - `po_box` (string, required) - PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. - `department_name` (string, required) - Supplements organisation name to identify a department within the organisation. May be empty. - `organisation_name` (string, required) - Name of the business or organisation at this address. May be empty. - `postcode_type` (object, required) - Royal Mail postcode user type. UK addresses only. - `su_organisation_indicator` (string, required) - `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. - `delivery_point_suffix` (string, required) - Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. - `premise` (string, required) - A pre-computed string which sensibly combines building_number, building_name and sub_building_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. May be empty. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `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 - `eastings` (Eastings, required) - Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `northings` (Northings, required) - Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `native` (NativeRecord, required) - 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) - `code` (integer, required) - `message` (string, required) Example response: ```json { "result": { "postcode": "CV4 7AL", "postcode_inward": "7AL", "postcode_outward": "CV4", "post_town": "Coventry", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Gibbet Hill Road", "dependant_thoroughfare": "", "building_number": "", "building_name": "Block 1 Arthur Vick", "sub_building_name": "Room 249a", "po_box": "", "department_name": "", "organisation_name": "", "udprn": 5770157, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Room 249a, Block 1 Arthur Vick", "line_2": "Gibbet Hill Road", "line_3": "", "premise": "Room 249a, Block 1 Arthur Vick", "longitude": -1.5648072, "latitude": 52.3858227, "eastings": 429716, "northings": 276509, "country": "England", "traditional_county": "Warwickshire", "administrative_county": "", "postal_county": "West Midlands", "county": "West Midlands", "district": "Coventry", "ward": "Wainbody", "uprn": "200001572050", "id": "mr_50906058", "country_iso": "GBR", "country_iso_2": "GB", "county_code": "", "language": "en", "umprn": 50906058, "dataset": "mr", "native": { "dataset": "mr", "postcode": "CV4 7AL", "post_town": "Coventry", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Gibbet Hill Road", "dependant_thoroughfare": "", "building_number": "", "building_name": "Block 1 Arthur Vick", "sub_building_name": "Room 249a", "department_name": "", "organisation_name": "", "udprn": 5770157, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "umprn": 50906058 } }, "code": 2000, "message": "Success" } ``` --- ## 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, 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, 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, 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 `IDPC-Source-IP` header - `premier_support` (boolean, required) - Whether the key is enrolled in the premier support programme 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) - 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) - 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 `IDPC-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, 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, 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, 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 `IDPC-Source-IP` header - `premier_support` (boolean, required) - Whether the key is enrolled in the premier support programme 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, 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 paid lookups made on a key, with the information recorded against each one. This method requires your Management Key, which can be found on your [accounts page](https://account.ideal-postcodes.co.uk/account). You can request a maximum interval of 90 days. Without a start or end date, the interval defaults to the last 21 days. The `Content-Type` returned is CSV (text/csv). For a non-200 response it 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 `IDPC-Source-IP` header. It is only recorded 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 (including IP, source IP, search term and URL data) weekly. By default we redact PII older than 28 days. You can change this period from your dashboard. Set the interval to `0` days to prevent PII collection altogether. **Undefined parameters** - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) --- ## POST /cleanse/addresses **Cleanse Address** Returns the closest matching address for a freeform address input, with Match Level indicators describing how closely each element of the suggested address matches the input. The more impaired the input address, the harder it is to cleanse. A cleanse that returns a match costs a lookup. A no-match response is free. ## Countries Cleanse defaults to the UK. Pass `context` with an ISO 3166-1 alpha-3 country code to cleanse an address elsewhere, e.g. `context=USA` or `context=FRA`. The address datasets your key is licensed for decide which countries it can cleanse. The response shape is the same for every country: a standardised address in `match`, the raw source record in `match.native`, and the same confidence, fit and Match Level indicators. The Match Levels and confidence score are at their most discriminating for the UK, where cleanse runs against purpose-built indexes; elsewhere they are computed from the country's address dataset. ## Confidence Score Each incorrect, missing or misspelled element subtracts from the overall confidence score. ### Deciding on an Acceptable Confidence Score Threshold Inputs differ widely between address cleanse projects. Within a project, though, they tend to repeat the same errors. Some datasets are keyed in by hand and prone to typos. Others have a persistently missing datapoint such as organisation name or postcode. There is no absolute Confidence Score threshold. Set the acceptable score project by project, based on the systematic errors in the data and your business goals. To set a threshold, load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top to bottom shows matches from best to worst. As you reach the lower quality searches you can judge roughly: - Which confidence scores indicate ambiguous matches (i.e. up to building level only) - Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address) Depending on your business goals, you can also use the Match Levels to determine an acceptable match. You may need to match only up to the thoroughfare or building name, or accurate organisation names may matter. **Undefined parameters** - `undefined` (string) - `undefined` (string) **Query parameters** - `context` (string) - Identify the country of the address to cleanse. Defaults to UK (GBR) **Request body** - `query` (string, required) - Freeform address input to cleanse - `postcode` (string) - Optionally specify the postal code for the address. - `post_town` (string) - Optionally specify the city or town of the address. - `county` (string) - Optionally specify the county of the address. **Response (200)** - `code` (integer, required) - `message` (string, required) - `result` (oneOf, required) - one of: GbrCleanseMatch, GbrCleanseNoMatch - `query` (string, required) - Originally submitted query - `match` (object, required) - Nearest matching address - `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) - `line_1` (string, required) - First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second address line. Often contains thoroughfare and locality information. May be empty. - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `post_town` (string, required) - The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. - `postcode` (string, required) - Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. - `county` (string, required) - Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. - `county_code` (string, required) - Short code representing the county or province. May be empty (`""`) - `uprn` (string, required) - UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property. - `udprn` (oneOf, required) - UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. - one of: integer, string - `umprn` (oneOf, required) - A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant. - one of: string, number - `postcode_outward` (string, required) - The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. 'PO1', 'SW1A' or 'B23'. - `postcode_inward` (string, required) - The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. - `dependant_locality` (string, required) - A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. - `double_dependant_locality` (string, required) - Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. - `thoroughfare` (string, required) - Also known as the street or road name. May be empty. - `dependant_thoroughfare` (string, required) - Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. - `building_number` (string, required) - Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. - `building_name` (string, required) - Name of a residential or commercial premise. May be empty. - `sub_building_name` (string, required) - Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B. May be empty. - `po_box` (string, required) - PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. - `department_name` (string, required) - Supplements organisation name to identify a department within the organisation. May be empty. - `organisation_name` (string, required) - Name of the business or organisation at this address. May be empty. - `postcode_type` (object, required) - Royal Mail postcode user type. UK addresses only. - `su_organisation_indicator` (string, required) - `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. - `delivery_point_suffix` (string, required) - Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. - `premise` (string, required) - A pre-computed string which sensibly combines building_number, building_name and sub_building_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. May be empty. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `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 - `eastings` (Eastings, required) - Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `northings` (Northings, required) - Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `native` (NativeRecord, required) - 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) - `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. 12 Pye Green Road) will have a fit of 1 even though it is missing post town and postcode. 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. - `organisation_match` (string, required) - Match indicator for the organisation - `premise_match` (string, required) - Match indicator for the premise - `postcode_match` (string, required) - Match indicator for the postcode - `thoroughfare_match` (string, required) - Match indicator for the street - `locality_match` (string, required) - Match indicator for the locality - `post_town_match` (string, required) - Match indicator for the post_town --- ## GET /autocomplete/addresses **Find Address** Returns address suggestions for a partial address, ordered by relevance. Use it to power real-time address autofill. Consider our address autocomplete JavaScript libraries, which add address lookup to a form without calling this API directly. ## API Usage Implementing our Address Autocomplete API involves: 1. Fetch address suggestions with `/autocomplete/addresses` 2. Acquire the complete address using the ID from the suggestion Step 2 decrements your lookup balance. Step 1 is not a free standalone resource. We rate limit and then suspend integrations that repeatedly make autocomplete requests without a paid Step 2 request. ## Context `context` limits the search, usually to a single country. It defaults to `GBR`, and an unrecognised context falls back to that default. If your key is not licensed for the datasets covering the context, the request is rejected. Querying a full postcode within a supported context returns the entire address list for that postcode. ## Query Filters Refine results by appending filters to your querystring, e.g. `postcode=sw1a2aa` for postcode `SW1A 2AA`. Invalid filters return an empty set without affecting your lookup count. To apply multiple filter terms, use a comma-separated list, e.g. `postcode_outward=e1,e2,e3` combines result sets for E1, E2 and E3. Unless otherwise specified, all filters support multiple terms. Filters combine with `AND` logic, for instance `su_organisation_indicator=Y&postcode_area=n`. The maximum is **8** filter terms. ## Address Bias Preface bias searches with `bias_` to boost certain address results. Unlike filters, biasing allows unmatched addresses to appear with lower priority. For example, use `bias_postcode_area=SW,SE` to favour addresses in the `SW` and `SE` postcode areas. Invalid bias terms have no effect. Multiple bias terms are allowed unless stated otherwise, with a combined maximum of **5**. ## Suggestion Format The suggestion format is subject to change. We recommend using the suggestion as-is to avoid integration issues. ## Rate Limiting and Cost The default rate limit is 3,000 requests per 5 minutes, counted per key and IP address. The `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers report where you stand. Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may lead to rate limiting or suspension. **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) - `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, required) - one of: AddressSuggestion, UkAddressSuggestion - `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": [ { "id": "paf_23747771", "suggestion": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A", "udprn": 23747771, "urls": { "udprn": "/v1/udprn/23747771" } }, { "id": "paf_26245117", "suggestion": "Flat 10, Downing Court, Grenville Street, London, WC1N", "udprn": 26245117, "urls": { "udprn": "/v1/udprn/26245117" } } ] }, "code": 2000, "message": "Success" } ``` --- ## GET /autocomplete/addresses/{address}/gbr **Resolve Address** Returns the complete address for an autocomplete suggestion, identified by its address ID. This is the step of the autocomplete flow that costs a lookup. Fetching suggestions is free. The API returns resolved addresses, including addresses outside the UK, in a UK format (up to 3 address lines) using UK nomenclature such as postcode and county. An ID that matches no address returns `404`. **Path parameters** - `address` (string, required) - **ID of address suggestion** **Undefined parameters** - `undefined` (string) - `undefined` (string) **Response (200)** - `code` (integer, required) - `message` (string, required) - `result` (Address, required) - The standard Ideal Postcodes address, which maps both UK and International addresses. - `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) - `line_1` (string, required) - First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second address line. Often contains thoroughfare and locality information. May be empty. - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `post_town` (string, required) - The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. - `postcode` (string, required) - Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. - `county` (string, required) - Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. - `county_code` (string, required) - Short code representing the county or province. May be empty (`""`) - `uprn` (string, required) - UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property. - `udprn` (oneOf, required) - UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. - one of: integer, string - `umprn` (oneOf, required) - A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant. - one of: string, number - `postcode_outward` (string, required) - The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. 'PO1', 'SW1A' or 'B23'. - `postcode_inward` (string, required) - The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. - `dependant_locality` (string, required) - A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. - `double_dependant_locality` (string, required) - Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. - `thoroughfare` (string, required) - Also known as the street or road name. May be empty. - `dependant_thoroughfare` (string, required) - Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. - `building_number` (string, required) - Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. - `building_name` (string, required) - Name of a residential or commercial premise. May be empty. - `sub_building_name` (string, required) - Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B. May be empty. - `po_box` (string, required) - PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. - `department_name` (string, required) - Supplements organisation name to identify a department within the organisation. May be empty. - `organisation_name` (string, required) - Name of the business or organisation at this address. May be empty. - `postcode_type` (object, required) - Royal Mail postcode user type. UK addresses only. - `su_organisation_indicator` (string, required) - `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. - `delivery_point_suffix` (string, required) - Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. - `premise` (string, required) - A pre-computed string which sensibly combines building_number, building_name and sub_building_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. May be empty. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `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 - `eastings` (Eastings, required) - Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `northings` (Northings, required) - Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `native` (NativeRecord, required) - 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 /addresses **Extract Addresses** Returns a list of UK addresses matching the query, ordered by relevance score. `limit` defaults to 10 and caps at 100. `page` defaults to 0. You may only extract a single address from each request. To extract multiple addresses, you must perform an individual request for each address. If the query is a valid postcode, the API returns the whole address list for that postcode and raises the limit to 100. Use `page` to reach the rest of a postcode holding more than 100 premises. You cannot page beyond 10,000 results. Your key needs at least one of PAF, Multiple Residence, Not Yet Built, PAF Alias, PAF Welsh, AddressBase or AddressBase Premium. Without one the request is rejected. A request that returns at least one address costs a lookup. Empty result sets are free. ## Reverse Geocoding Return the addresses around a point with the `lon=` and `lat=` querystring arguments. The search radius is 100m and the API sorts addresses by distance from the point. ## Filters Narrow your results by adding filters to your query string that correspond with an address attribute. For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`. If a filter term is invalid, e.g. `postcode=SW1A2AAA`, the API returns an empty result set and charges no lookup. You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined. All filters can accept multiple terms unless stated otherwise below. Multiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set. A combined maximum of 8 terms is allowed across all filters. ## Biases You can boost address results that correspond with a given address attribute. All bias searches are prefixed with `bias_`. Biased searches, unlike filtered searches, still allow unmatched addresses to appear. They rank lower. For instance, you can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`. If a bias term is invalid, e.g. `bias_postcode=SW1A2AAA`, no bias is applied. You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Prefer results in the `E1`, `E2` and `E3` outward codes: `bias_postcode_outward=e1,e2,e3`. All biases can accept multiple terms unless stated otherwise below. A combined maximum of 5 terms is allowed across all biases. ## Search by Postcode and Building Name or Number Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" `/v1/addresses?postcode=sw1a2aa&q=prime minister`. Using a filter means a postcode mismatch returns no results and costs no lookup. ### Search by UPRN Search by UPRN using the `uprn` filter and excluding the query argument. E.g. `/v1/addresses?uprn=100`. **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) - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) - `undefined` (string) **Query parameters** - `query` (string) - Specifies the address to query. **Response (200)** - `code` (integer, required) - `message` (string, required) - `result` (object, required) - `hits` (array, required) - List of matching addresses - `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) - `line_1` (string, required) - First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second address line. Often contains thoroughfare and locality information. May be empty. - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `post_town` (string, required) - The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. - `postcode` (string, required) - Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. - `county` (string, required) - Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. - `county_code` (string, required) - Short code representing the county or province. May be empty (`""`) - `uprn` (string, required) - UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property. - `udprn` (oneOf, required) - UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires. - one of: integer, string - `umprn` (oneOf, required) - A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant. - one of: string, number - `postcode_outward` (string, required) - The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. 'PO1', 'SW1A' or 'B23'. - `postcode_inward` (string, required) - The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. - `dependant_locality` (string, required) - A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. - `double_dependant_locality` (string, required) - Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. - `thoroughfare` (string, required) - Also known as the street or road name. May be empty. - `dependant_thoroughfare` (string, required) - Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. - `building_number` (string, required) - Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. - `building_name` (string, required) - Name of a residential or commercial premise. May be empty. - `sub_building_name` (string, required) - Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B. May be empty. - `po_box` (string, required) - PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. - `department_name` (string, required) - Supplements organisation name to identify a department within the organisation. May be empty. - `organisation_name` (string, required) - Name of the business or organisation at this address. May be empty. - `postcode_type` (object, required) - Royal Mail postcode user type. UK addresses only. - `su_organisation_indicator` (string, required) - `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. - `delivery_point_suffix` (string, required) - Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. - `premise` (string, required) - A pre-computed string which sensibly combines building_number, building_name and sub_building_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. May be empty. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `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 - `eastings` (Eastings, required) - Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `northings` (Northings, required) - Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). - one of: string, number - `native` (oneOf) - The raw dataset record backing this address. On these two endpoints it is returned for AddressBase (`ab`, `abp`) and non-UK datasets only, never for the PAF family. Use any other endpoint for a PAF native record. - one of: AbAddress, AbpAddress, UspsAddress, EcadAddress, EcafAddress, HereAddress, GnafAddress, KadasterAddress, KartverketAddress, SdfiAddress, CannarAddress, FodbosaAddress, MoisAddress, UpujpAddress, BevAddress, BanAddress, SwtAddress - `id` (ID, required) - Global unique internally generated identifier for an address - `country_iso` (string, required) - 3 letter country code (ISO 3166-1) - `dataset` (string, required) - Indicates the provenance of an address - `language` (Language, required) - Language represented by 2 letter ISO Code (639-1) - `line_1` (string, required) - First Address Line. Often contains premise and thoroughfare information. In the case of a commercial premise, the first line is always the full name of the registered organisation. Never empty. - `line_2` (string, required) - Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` (string, required) - Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. - `premise` (string, required) - A pre-computed string which sensibly combines the building name, sub-building and building number fields into a single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using the address lines. - `uprn` (string, required) - Unique Property Reference Number (UPRN) assigned by the LLPG Custodian or Ordnance Survey. - `udprn` (integer, required) - Royal Mail's Unique Delivery Point Reference Number (UDPRN). `0` where the record has no matching PAF delivery point. - `parent_uprn` (string, required) - UPRN of the parent record where a parent-child relationship exists. Empty where the record has no parent. - `usrn` (integer, required) - Unique Street Reference Number assigned by the Street Name and Numbering Custodian or by Ordnance Survey, depending on the address record. - `toid` (string, required) - The Topographic Identifier taken from OS MasterMap Topography Layer. This TOID is assigned to the UPRN by performing a spatial intersection between the two identifiers. It consists of the letters 'osgb' followed by up to sixteen digits. May be empty. - `classification_code` (string, required) - A code that describes the classification of the address record to a maximum of a secondary level. The first letter is the primary class (e.g. `R` residential, `C` commercial, `L` land), the second the secondary class (e.g. `RD` dwelling). - `eastings` (number, required) - A value in metres defining the x location in accordance with the British National Grid. - `northings` (number, required) - A value in metres defining the y location in accordance with the British National Grid. - `latitude` (number, required) - A value defining the Latitude location in accordance with the ETRS89 coordinate reference system. - `longitude` (number, required) - A value defining the Longitude location in accordance with the ETRS89 coordinate reference system. - `single_address_line` (string, required) - A single attribute containing text concatenation of the address elements separated by a comma. - `street_name` (string, required) - Street / Road name for the address record. - `locality` (string, required) - A locality defines an area or geographical identifier within a town, village or hamlet. Locality represents the lower level geographical area. The locality field should be used in conjunction with the town name and street description fields to uniquely identify geographic area where there may be more than one within an administrative area. - `town_name` (string, required) - Geographical town name assigned by the Local Authority. Note this can differ from the post town assigned by Royal Mail. - `delivery_point_suffix` (string, required) - A two-character code uniquely identifying an individual delivery point within a postcode, assigned by Royal Mail. May be empty. - `post_town` (string, required) - The town or city in which the Royal Mail sorting office servicing this address record is located. - `gss_code` (string, required) - The Office for National Statistics Governmental Statistical Service (GSS) code representing the contributing Local Authority. - `rpc` (integer, required) - Representative Point Code describes the accuracy of the coordinate that has been allocated to the UPRN as indicated by the Local Authority and enhanced using large scale OS data. - `last_update_date` (string, required) - The latest date on which any of the attributes on this record were last changed. - `island` (string, required) - Third level of geographic area name to record island names where appropriate. May be empty. - `change_code` (string, required) - The type of change last applied to the record. `I` insert, `U` update, `D` delete. - `building_name` (string, required) - The building name is a description applied to a single address or a group of addresses. May be empty. - `building_number` (string, required) - The building number is a number or range of numbers given to a single address or a group of addresses. May be empty. - `sub_building` (string, required) - The sub-building name and/or number for the address record. May be empty. - `postcode` (string, required) - A postcode assigned by Royal Mail for the address record. - `po_box` (string, required) - Text concatenation of 'PO BOX' and the Post Office Box (PO Box) number or 'BFPO' and the British Forces Post Office number. May be empty. - `organisation` (string, required) - The organisation name is the business name given, when appropriate, to an address record. May be empty. - `country` (string, required) - Full country names (ISO 3166) - `county` (string, required) - Since postal, administrative or traditional counties may not apply to some addresses, the county field is designed to return whatever county data is available. Normally, the postal county is returned. If this is not present, the county field will fall back to the administrative county. If the administrative county is also not present, the county field will fall back to the traditional county. May be empty in cases where no administrative, postal or traditional county present. - `district` (string, required) - The current district/unitary authority to which the postcode has been assigned. - `ward` (string, required) - The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `traditional_county` (string, required) - Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `administrative_county` (string, required) - The current administrative county to which the postcode has been assigned. - `postal_county` (string, required) - Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty. - `total` (integer, required) - `limit` (integer, required) - `page` (integer, required) --- ## 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, 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, 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, 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 cancelled licensees. The key must be enabled for sublicensing. **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) - `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) - 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 sublicensing. **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) - 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) - 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 cancelled 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) - 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) - 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) - 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) - 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, 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 serialised 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 serialised 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, 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) - Organisation 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.