Unique Delivery Point Reference Number (UDPRN) API

A UDPRN is a unique numeric code (e.g. 25962203) for any premise on the Postcode Address File. They are unique identifiers for every address in the UK that Royal Mail has in its database.

For a more detailed explanation, you may wish to view our guide on UDPRN.

Lookup a UDPRN

GET /udprn/:udprn

Returns an address identified via its Unique Delivery Point Reference Number (UDPRN).

You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a "decommissioned" address.

Query Parameters

Property Description
api_key Required unless authenticating with Authorization HTTP Header
filter Comma separated whitelist of address elements to return. E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response



 # Or in your terminal
curl -k -G https://api.ideal-postcodes.co.uk/v1/udprn/0 \
    -d "api_key=iddqd"


    "result": {
        "postcode": "ID1 1QD",
        "postcode_inward": "1QD",
        "postcode_outward": "ID1",
        "post_town": "LONDON",
        "dependant_locality": "",
        "double_dependant_locality": "",
        "thoroughfare": "Barons Court Road",
        "dependant_thoroughfare": "",
        "building_number": "2",
        "building_name": "",
        "sub_building_name": "",
        "po_box": "",
        "department_name": "",
        "organisation_name": "",
        "udprn": 0,
        "umprn": "",
        "postcode_type": "S",
        "su_organisation_indicator": "",
        "delivery_point_suffix": "1G",
        "line_1": "2 Barons Court Road",
        "line_2": "",
        "line_3": "",
        "premise": "2",
        "country": "England",
        "county": "Greater London",
        "administrative_county": "",
        "postal_county": "",
        "traditional_county": "Greater London",
        "district": "Hammersmith and Fulham",
        "ward": "North End",
        "longitude": -0.208644362766368,
        "latitude": 51.4899488390558,
        "eastings": 524466,
        "northings": 178299,
        "uprn": "2"
    "code": 2000,
    "message": "Success"

A single address object is returned in the result attribute.


To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request. They are the following

  • 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 will undergo usual authentication and restriction rules (individual and daily lookup limits) to surface any problems you may have during implementation. However, it will not count towards a postcode lookup on your key.


Per lookup charges apply. Empty responses are not charged.