Migration Guide for CAF V2 users


Instead of using SOAP headers (V1) or an API key parameters (V2), V3 is presented over the Internet using standard HTTP basic authencation over HTTPS.

If you already have a username and password (CAF V1) or API key (CAF V2), then you can use these immediately to test authentication to CAF V3:


The V3 API is a REST/JSON API which provides all the functionality of the V1 and V2 APIs. You can retrieve V3 assets by making standard HTTP GET requests to the URLs. This means that the search and retrieval parts of the API can be tested in the browser.

The API is also has machine readable documentation in OpenAPI format, and you can explore the API using Swagger.

Searching addresses

Address searches are carried out via the /v3/addresses/search API call. Your call should have one or more term querystring parameters, each of which is a JSON string representing a restriction on your query. For example, to query by post code, you can use the JSON string {index:'postCode',value:'JE2 4WG'}. Terms can have additional properties which specify whether to search aliases or history, or to use metaphones.

Records are never destroyed in CAF, only marked inactive, and searches continue to retrieve inactive records unless you specify otherwise. To do this, add a term of {index:'active',value:'true'}.

The CAF V2 parameters map to V3 search terms as follows:

Where are the CAF IDs?

V3 provides a ref property for every object. This is a numeric value which is globally unique within the CAF database, regardless of whether the object is a Road, Address, Candidate or Parish. ref therefore provides an analogue for the CAF ID in CAF V1 and V2.

However, CAF V3 also guarantees the immutability of the doc property. Every object within a given journal (Addresses, Roads, Candidates and Parishes) has a doc which is unique within that journal. Each revision of that object also has a unique rev. For most uses, therefore, it is sufficient to store and use doc values only in your system.


The ref property is primarily of use to specify as a parameter to the /v3/{journal}/pull call, which is analogous to the V1 and V2 GetUpdates call.

The V3 pull call works very similarly. However, unlike the V1 and V2 GetUpdates call, it does not attempt to collapse multiple updates to the same address into a single update (some users of GetUpdates found this behaviour quite obscure). V3's pull simple lists every update separately.

Pull can be now be used with any journal, e.g. for roads: