The client address API at /v2/clients/{clientId}/addresses is being extended by adding property details to the address resource. This post serves as notice to our developer community of this change, and while this is considered to be a minor update, it highlights some potential pitfalls that need to be avoided when we release this into production. We'll discuss these below when we talk about the operations for managing them, but first things first - what do we mean by property details?
What are property details?
Property Details refer to an object containing metadata describing the property at the given address. This could for example include details such as number of bedrooms; type of construction; number of outbuildings; or the year of construction.
Note: You should consult the API documentation, after we publish the release, to ensure you have the most up-to-date information before you start any development work.
How does it affect the client address resource?
Property Details will form part of the client address resource, and can therefore be included on any address operations. Below is a JSON example of how Property Details forms part of the existing address resource. There are no other changes to the address resource apart from the addition of property details.
{
"status": string (enum),
"href": string,
"residencyStatus": string (enum),
"address": {
"locality": string,
"country": {
"code": string,
"name": string
},
"line1": string,
"line2": string,
"line3": string,
"line4": string,
"county": {
"code": string,
"name": string
},
"postalCode": string
},
... all other current address fields
"property": {
"type": string (enum),
"typeDetail": string (enum)
"tenureType": string (enum),
"status": string (enum),
"construction": string (enum),
"constructionNotes": string (allowed if "construction" is "other"),
"roofConstruction": string (enum),
"numberOfBedrooms": int,
"yearBuilt": int,
"isExLocalAuthority": bool,
"numberOfOutbuildings": int,
"newBuild": {
"isCoveredByNHBCCertificate": bool,
"isCoveredByOtherCertificates": bool,
"otherCertificateNotes": string (available if "isCoveredByOtherCertificates" = true),
"nameOfBuilder": string
}
}
Note that Property Details (property) is a nested object, similar to the address details.
How will it affect existing code?
GET
This will now return any property details that may have been captured in iO. If there are none, then the property details object will be omitted from the payload.
DELETE
This will delete the client address as well as the related property details (even if they were captured in iO and not via the API).
PUT
Any existing consumers of PUT will potentially not include any property details in their current payloads. This will not cause the API call to fail, but it does mean that any existing property details will be deleted, because they are not included in the resource.
POST
If included in the JSON payload, POST operations will now create a client address as well as the property details record.
What do I need to do if I have existing property details in iO and I use the client address API?
If you have existing property details in IO (located in Fact Find → Mortgage → Property Details) linked to client addresses, then once these new changes are live, the property details will be included in the response of a client address GET operation. It's important in this case when updating addresses via a PUT operation, that the property details are included in the payload to avoid inadvertently deleting the property details.
When will these changes be released?
These new changes will be released in early September 2019.
