UK address validation (PAF) API

Validate an address against Royal Mail PAF. Send the complete address in full_address, or send it across address_line_1, address_line_2, address_line_3, town_city, county and postcode. You only need to send the fields you have; blank fields are ignored.

Set output_format to standard for the clean matched address and a clear outcome. Set it to detailed to receive the same fields plus technical matching information. An address_status of review means a possible match was found but needs review. Only verified confirms a complete match.

Endpoint

POST

https://api.provero.io/api/validate/uk-address

Headers

Authorization:
Content-Type: application/json
Accept: application/json

Request Body

Field	Type	Required	Description
`full_address`	`string`	No	The complete address in one field. When this has a value, `address_line_1`, `address_line_2` and `address_line_3` are not added to it.
`address_line_1`	`string`	No	The first line of the address. Used when `full_address` is empty or not sent.
`address_line_2`	`string`	No	The second line of the address. Used when `full_address` is empty or not sent.
`address_line_3`	`string`	No	The third line of the address. Used when `full_address` is empty or not sent.
`town_city`	`string`	No	The town or city. Used with the separate address fields and to help find the best match.
`postcode`	`string`	No	The UK postcode. Used with the separate address fields and to help find the best match.
`county`	`string`	No	The county. Used when the address is supplied in separate fields.
`output_format`	`string`	No	`standard` Clean matched address and summary outcome. `detailed` Standard fields plus technical matching information.

Request Payload Example (JSON)

{
    "full_address": "10 Downing Street, London, SW1A 2AA",
    "postcode": "SW1A 2AA",
    "town_city": "London",
    "output_format": "standard"
}

Request Examples

Choose language Bash (cURL) 5 examples

curl -X POST https://api.provero.io/api/validate/uk-address \
  -H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "full_address": "10 Downing Street, London, SW1A 2AA",
    "postcode": "SW1A 2AA",
    "town_city": "London",
    "output_format": "standard"
  }'

import requests

url = "https://api.provero.io/api/validate/uk-address"
payload = {
    "full_address": "10 Downing Street, London, SW1A 2AA",
    "postcode": "SW1A 2AA",
    "town_city": "London",
    "output_format": "standard"
}

headers = {
    "Authorization": "Bearer REPLACE_WITH_API_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())

<?php
$payload = [
    "full_address" => "10 Downing Street, London, SW1A 2AA",
    "postcode" => "SW1A 2AA",
    "town_city" => "London",
    "output_format" => "standard",
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.provero.io/api/validate/uk-address",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type: application/json",
        "Accept: application/json",
    ],
]);

$response = curl_exec($curl);
if (curl_errno($curl)) {
    echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;

$response = Http::withToken('REPLACE_WITH_API_TOKEN')
    ->acceptJson()
    ->post('https://api.provero.io/api/validate/uk-address', [
        'full_address' => '10 Downing Street, London, SW1A 2AA',
        'postcode' => 'SW1A 2AA',
        'town_city' => 'London',
        'output_format' => 'standard',
    ]);

return $response->json();

// Run on your server with Node.js 18+. Keep your API token out of browser code.
const response = await fetch("https://api.provero.io/api/validate/uk-address", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.PROVERO_API_TOKEN}`,
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
    body: JSON.stringify({
        full_address: "10 Downing Street, London, SW1A 2AA",
        postcode: "SW1A 2AA",
        town_city: "London",
        output_format: "standard"
    })
});

console.log(response.status);
console.log(await response.json());

Response Examples

Choose response example Standard - Match 11 examples

{
    "address_status": "verified",
    "premise_match": "FULL",
    "address_line_1": "Prime Minister & First Lord Of The Treasury",
    "address_line_2": "10 Downing Street",
    "address_line_3": "",
    "post_town": "LONDON",
    "postcode": "SW1A 2AA",
    "country": "England",
    "full_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, LONDON, SW1A 2AA"
}

{
    "address_status": "review",
    "premise_match": "PARTIAL",
    "address_line_1": "20 Canterbury Crescent",
    "address_line_2": "",
    "address_line_3": "",
    "post_town": "SHEFFIELD",
    "postcode": "S10 3RX",
    "country": "England",
    "full_address": "20 Canterbury Crescent, SHEFFIELD, S10 3RX"
}

{
    "address_status": "verified",
    "address_line_1": "Prime Minister & First Lord Of The Treasury",
    "address_line_2": "10 Downing Street",
    "address_line_3": "",
    "post_town": "LONDON",
    "postcode": "SW1A 2AA",
    "country": "England",
    "full_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, LONDON, SW1A 2AA",
    "query": "10 Downing Street, London, SW1A 2AA",
    "valid": true,
    "address_complete": true,
    "confidence": 1,
    "count": 1,
    "fit": 1,
    "organisation_match": "FULL",
    "premise_match": "FULL",
    "postcode_match": "FULL",
    "thoroughfare_match": "FULL",
    "locality_match": "FULL",
    "post_town_match": "FULL",
    "match": {
        "organisation_name": "Prime Minister & First Lord Of The Treasury",
        "department_name": "",
        "po_box": "",
        "building_name": "",
        "sub_building_name": "",
        "building_number": "10",
        "premise": "10",
        "dependant_thoroughfare": "",
        "thoroughfare": "Downing Street",
        "double_dependant_locality": "",
        "dependant_locality": "",
        "post_town": "London",
        "postcode": "SW1A 2AA",
        "line_1": "Prime Minister & First Lord Of The Treasury",
        "line_2": "10 Downing Street",
        "line_3": "",
        "formatted_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A 2AA",
        "country": "England",
        "country_iso_2": "GB",
        "latitude": 51.503541,
        "longitude": -0.12767
    }
}

{
    "address_status": "no_match",
    "premise_match": "NO_MATCH",
    "address_line_1": "",
    "address_line_2": "",
    "address_line_3": "",
    "post_town": "",
    "postcode": "",
    "country": "",
    "full_address": "",
    "requestError": {
        "serviceException": {
            "messageId": "No matching PAF address found.",
            "code": 404
        }
    }
}

{
    "address_status": "no_match",
    "address_line_1": "",
    "address_line_2": "",
    "address_line_3": "",
    "post_town": "",
    "postcode": "",
    "country": "",
    "full_address": "",
    "query": "Unknown address, ZZ1 1ZZ",
    "valid": false,
    "address_complete": false,
    "confidence": 0,
    "count": 0,
    "fit": 0,
    "organisation_match": "NO_MATCH",
    "premise_match": "NO_MATCH",
    "postcode_match": "NO_MATCH",
    "thoroughfare_match": "NO_MATCH",
    "locality_match": "NO_MATCH",
    "post_town_match": "NO_MATCH",
    "match": null,
    "requestError": {
        "serviceException": {
            "messageId": "No matching PAF address found.",
            "code": 404
        }
    }
}

{
    "message": "Provide a full address or at least one separate address field.",
    "errors": {
        "full_address": [
            "Provide a full address or at least one separate address field."
        ]
    }
}

{
    "message": "The postcode field must not be greater than 16 characters.",
    "errors": {
        "postcode": [
            "The postcode field must not be greater than 16 characters."
        ]
    }
}

{
    "message": "Insufficient balance for validation request.",
    "service": "uk-address",
    "required_amount": "0.0460000000",
    "current_balance": "0.0000000000"
}

{
    "requestError": {
        "serviceException": {
            "messageId": "The address could not be checked. Check the address and try again.",
            "code": 400,
            "errorCode": "UK_ADDRESS_INPUT_REJECTED"
        }
    }
}

{
    "requestError": {
        "serviceException": {
            "messageId": "UK address validation is temporarily unavailable. Please try again later.",
            "code": 503,
            "errorCode": "UK_ADDRESS_UNAVAILABLE"
        }
    }
}

{
    "requestError": {
        "serviceException": {
            "messageId": "UK address validation is temporarily unavailable. Please try again later.",
            "code": 502,
            "errorCode": "UK_ADDRESS_UNAVAILABLE"
        }
    }
}

Response Body

Success structure

Field Name	Type	Always Returned	Description
`address_status`	`string`	Yes	Summary outcome for explicit formats: verified, review, no_match or error. A returned candidate is review unless address_complete passes.
`premise_match`	`string`	Yes	Existing premise result, unchanged: FULL, PARTIAL, INCORRECT, MISSING, NA or NO_MATCH. This field does not determine address_status by itself.
`address_line_1`	`string`	Yes	Canonical PAF line 1. Empty when no match exists.
`address_line_2`	`string`	Yes	Canonical PAF line 2. Address components are not forced into fixed line meanings.
`address_line_3`	`string`	Yes	Canonical PAF line 3, or an empty string when unused.
`post_town`	`string`	Yes	Canonical uppercase postal town returned by PAF.
`postcode`	`string`	Yes	Canonical uppercase postcode with standard spacing.
`country`	`string`	Yes	Country returned with the matched PAF address.
`full_address`	`string`	Yes	Non-empty canonical address lines, Post Town and Postcode joined with comma-space. County and country are not appended.
`count`	`integer`	Yes	Number of candidates, from 0 to 10. Only the best candidate is returned in match.
`fit`	`number`	Yes	Closeness of the input to the candidate, between 0 and 1. Zero for no match.
`organisation_match`	`string`	Yes	Component match status: FULL, PARTIAL, INCORRECT, MISSING or NA. NO_MATCH when no candidate exists.
`postcode_match`	`string`	Yes	Postcode match status after safe case and whitespace normalisation: FULL, PARTIAL, INCORRECT, MISSING or NA. NO_MATCH when no candidate exists.
`thoroughfare_match`	`string`	Yes	Component match status: FULL, PARTIAL, INCORRECT, MISSING or NA. NO_MATCH when no candidate exists.
`locality_match`	`string`	Yes	Component match status: FULL, PARTIAL, INCORRECT, MISSING or NA. NO_MATCH when no candidate exists.
`post_town_match`	`string`	Yes	Component match status: FULL, PARTIAL, INCORRECT, MISSING or NA. NO_MATCH when no candidate exists.
`query`	`string`	Yes	The submitted free-form address query.
`valid`	`boolean`	Yes	True when a PAF candidate was found. This does not mean the input was an exact match.
`address_complete`	`boolean`	Yes	True only for one candidate with all six component statuses FULL or NA and no fuzzy, unusable or conflicting supplied postcode. Otherwise review the suggested address.
`confidence`	`number`	Yes	Matching confidence between 0 and 1. Zero for no match.
`match`	`object\|null`	Yes	Canonical PAF address match. Null is only returned on a 404 no-match response.
`match.organisation_name`	`string`	No	Canonical organisation name.
`match.department_name`	`string`	No	Canonical department name.
`match.po_box`	`string`	No	Canonical PO box.
`match.building_name`	`string`	No	Canonical building name.
`match.building_number`	`string`	No	Canonical building number.
`match.dependant_thoroughfare`	`string`	No	Canonical dependent thoroughfare.
`match.thoroughfare`	`string`	No	Canonical thoroughfare.
`match.double_dependant_locality`	`string`	No	Canonical double dependent locality.
`match.dependant_locality`	`string`	No	Canonical dependent locality.
`match.post_town`	`string`	No	Canonical post town.
`match.postcode`	`string`	No	Canonical postcode.
`match.udprn`	`string`	No	Royal Mail UDPRN, included in Detailed output only when returned by the result.
`match.uprn`	`string`	No	UPRN, included in Detailed output only when returned by the result.

Error structure

Field Name	Type	Always Returned	Description
`message`	`string`	No	Top-level error message returned for malformed requests, insufficient balance, or service errors.
`errors`	`object`	No	Validation errors grouped by request field.
`requestError`	`object`	No	Returned when no PAF match is found or the address validation service cannot process the request.
`service`	`string`	No	Service alias returned with a 402 insufficient-balance response.
`required_amount`	`string`	No	Credit amount required to process the validation request.
`current_balance`	`string`	No	Current available balance at the time the request was rejected.