Create and Manage Mortgage Deeds API Documentation
View the Project on GitHub LandRegistry/deed-api
Using This Service as an Intermediary
HM Land Registry's Digital Mortgage service consists of 2 linked services:
Create and Manage Mortgage Deeds allows a conveyancer to create a digital mortgage using the interface provided by Deed-API. The service also provides endpoints for getting a created deed, checking which deeds have been signed by borrowers, and making a deed effective.
Deeds created using the Deed-API service can be signed by a borrower using the Sign Your Mortgage service on GOV.UK and submitted to HM Land Registry for registration using Business Gateway.
As well as the above Deed-API endpoints, the service also provides an endpoint for returning a list of organisation names via Organisation-API.
Under section 111 of the Network Access Agreement HM Land Registry requests conveyancers to confirm that the borrowers identity has been established.
Depending on the business model of your organisation there are two methods you can use to confirm that due diligence has been performed and the borrowers identity has been established.
If the borrowers identity will be established by your organisation on create deed you can confirm to HM Land Registry that the checks have been performed by setting the identity_checked value in the create deed payload to "Y".
For more information refer to the create deed entry in the schema .
If the checks will be carried out by a different organisation than the one creating the deed then on deed creation the identity_checks value should be set to "N".
The organisation carrying out the checks will be able to perform the identity checks by calling the /identity-checks endpoint on the system and providing the name address, ID and date of birth for each borrower.
The identity-checked endpoint is documented in the schema .
*NOTE* The borrowers will not be able to sign the deed until the identity checks have been successfully carried out either on creation or by using the identity-checked endpoint.
BY DOING EITHER OF THE STEPS ABOVE YOU ARE CONFIRMING THAT DUE DILIGENCE HAS BEEN CARRIED OUT AND THE BORROWERS IDENTITY HAS BEEN ESTABLISHED.
If you are acting as an intermediary and you will not be the organisation completing the deed then there are additional steps you will need to perform.
When creating a deed you will need to set the name of the proxy organisation you intend to assign the deed to.
To do this you will need to set the "proxy_organisation_name" field in the create deed payload to the name of the organisation you wish to designate as a proxy. Doing this will then allow the proxy conveyancer to also access the deed and perform identity checks.
To get an up to date list of the availible organisations in the service that can be used as a proxy, you can call the get the organisations endpoint in the service that will return an up to date list of all valid organisations.
When creating a deed you must provide one of these values in the create deed schema exactly in the format it is provided by the organisations endpoint.
For more information on consuming the organisations functionality see the schema file for this endpoint here .
*NOTE* If you set a value in the "proxy_organisation_name" field then only this organisation will be able to make the deed effective.
To be able to use this service, you will need to include an authorization header in your requests to our service.
The correct format for the Authorization header is to add your username and password seperated by a colon. As an example you could have 'johnsmith' as the username and 'password' as the password. Which would look like:
johnsmith:password
Then Base64 encode this string, would which look like:
am9obnNtaXRoOnBhc3N3b3Jk
Finally, you will need to add this Base64 encoded username and password to your Authorization header for the request.
Key: Authorization
Value: Basic am9obnNtaXRoOnBhc3N3b3Jk
In the future, Authorization headers will be mandatory. This will be communicated to conveyancers nearer the time. If the request is successfull, the expected payload for the endpoint will be returned. If however there is an issue with your username and password, the following responses will be returned:
401 UNAUTHORIZED
{ "Message": "Invalid credentials." }
If no header is sent with the request:
400 BAD REQUEST
{ "Message": "Authorization header not present." }
HM Land Registry operates a Test Hub which runs a test version of the Deed-API service, allowing developers to test their solution against a running example of the service.
Access to the Test Hub is controlled via WebSEAL and you will need to request to have your organisation's certificate added to the access list.
The URL's for the Test Hub are as follows:
Below are examples of payloads accepted by Deed-API and responses.
NOTE This is not an exhaustive example of all error messages the system returns but provides an example of the format of each response and error type.
This endpoint requires that the Content-Type header be set as application/json
{
"title_number": "GR515835",
"md_ref": "e-MD12344",
"property_address": "80 High Street, Plymouth, Devon, PL6 5WS",
"identity_checked": "Y",
"is_second_charge": "Y",
"borrowers": [
{
"forename": "Ann",
"surname": "Smith",
"gender": "Female",
"address": "test address with postcode, PL14 3JR",
"dob": "23/01/1985",
"phone_number": "07502154998"
},
{
"forename": "Fredd",
"surname": "Smith",
"gender": "Female",
"address": "test address with postcode, PL14 3JR",
"dob": "23/01/1985",
"phone_number": "0750215999"
}
]
}
{
"path": "/deed/0729e738-c073-445f-8976-9c81bbecf5c7"
}
400 BAD REQUEST
{
"errors": [
"Problem 1: A mobile phone number must be unique to an individual."
]
}
{
"path": "/deed/0729e738-c073-445f-8976-9c81bbecf5c7"
}
400 Bad Request
{
"message": "organisation abc failed to terminate deed: 0729e738-c073-445f-8976-9c81bbecf5c7"
}
401 Unauthenticated
{
"message": "Failed to terminate deed for reference: 0729e738-c073-445f-8976-9c81bbecf5c7"
}
404 Not Found
{
"message": "Deed reference 0729e738-c073-445f-8976-9c81bbecf5c7 is not valid"
}
{
"path": "/deed/0729e738-c073-445f-8976-9c81bbecf5c7"
}
400 Bad Request
{
"message": "organisation abc failed to extend deed: 0729e738-c073-445f-8976-9c81bbecf5c7"
}
401 Unauthenticated
{
"message": "Failed to extend deed for reference: 0729e738-c073-445f-8976-9c81bbecf5c7"
}
404 Not Found
{
"message": "Deed reference 0729e738-c073-445f-8976-9c81bbecf5c7 is not valid"
}
[
{
"expiry_date": "2019-09-01T09:58:50.982351+00:00",
"identity_checked": "Y",
"borrowers": [
{
"surname": "Smith",
"id": 338,
"signature": "N",
"forename": "Ann"
},
{
"surname": "Smith",
"id": 339,
"signature": "N",
"middle_name": "Patrick",
"forename": "Fredd"
}
],
"token": "27805ec4-3f80-439d-84f4-492e89c78d15",
"status": "DRAFT"
}
]
{
"message": "There are currently no in-progress deeds"
}
401 Unauthenticated
{
"message": "Failed to retrieve in-progress deeds"
}
500 Internal Server Error
{
"message": "Failed to retrieve in-progress deeds"
}
{
"deed": {
"additional_provisions": [
{
"additional_provision_code": "addp001",
"description": "This Mortgage Deed incorporates the Lenders Mortgage Conditions and Explanation 2006, a copy of which the borrower has received."
},
{
"additional_provision_code": "addp002",
"description": "The lender is obliged to make further advances and applies for the obligation to be entered in the register."
},
{
"additional_provision_code": "addp003",
"description": "The borrower applies to enter a restriction in the register that no disposition of the registered estate by the proprietor of the registered estate is to be registered without a written consent signed by the proprietor for the time being of the charge dated [the date of this charge] in favour of Bank of Test Plc referred to in the charges register."
}
],
"borrowers": [
{
"forename": "Ann",
"id": 676,
"surname": "Smith",
"token": "GT5VBTR8"
},
{
"forename": "Fredd",
"id": 677,
"surname": "Smith",
"token": "N1L51A4L"
}
],
"charge_clause": {
"cre_code": "CRE001",
"description": "The borrower, with full title guarantee, charges to the lender the property by way of legal mortgage with payment of all money secured by this charge."
},
"effective_clause": "This charge takes effect when the registrar receives notification from Land Registry Devices that the charge is to take effect.",
"lender": {
"address": "12 Test Place, Test Street, London NW0 0TQ",
"name": "Test Building Society",
"registration": "Company registration number: 2347676"
},
"md_ref": "e-MD12344",
"identity_checked": "Y",
"property_address": "80 High Street, Plymouth, Devon, PL6 5WS",
"status": "DRAFT",
"expiry_date": "Sat, 20 Jul 2019 12:34:27 GMT",
"title_number": "GR515835",
"token": "0b29c37b-1896-4219-832d-5ddf499a6027"
}
}
404 NOT FOUND
{
"message": "Deed not found"
}
{
"deeds": [
"40a235b9-78eb-4dab-95d6-db7c75eedcb0",
"2130a81c-3fbe-4381-ac47-a4300c48f841"
]
}
404 NOT FOUND
{
"message": "There are no deeds which have been fully signed"
}
{
"path": "/deed/40a235b9-78eb-4dab-95d6-db7c75eedcb0"
}
400 BAD REQUEST
{
"errors": [
"Problem 1: This deed cannot be made effective as not all borrowers have signed the deed."
]
}
{
"borrowers": [
{
"id": 1108,
"forename": "Ann",
"surname": "Smith",
"address": "test address with postcode, PL14 3JR",
"dob": "23/01/1985"
},
{
"id": 1109,
"forename": "Fredd",
"surname": "Smith",
"address": "test address with postcode, PL14 3JR",
"dob": "23/01/1985"
}
]
}
{
"path": "/deed/0729e738-c073-445f-8976-9c81bbecf5c7"
}
400 BAD REQUEST
{
"message": "Identity checks have failed. Data provided does not match"
}
For any system error not handled by the system the following error will be returned:
{
"message": "Unexpected error."
}
There are a selection of test Titles and MD references in the Test Hub which can be used to test the service. Note that when creating a deed the borrowers must be an exact match to the proprietors on the register. See example payload above for a create deed payload using the data below that will work in the Test Hub. Some example test data is below. For a full list click here .
Title number GR515835
Proprietors Ann Smith, Fredd Smith
Title Number GR518327
Response message Title closed and continued under GR518006.
Title Number GR516921
Response Title is not suitable for a digital mortgage as it is a qualified title.
e-MD12344
Once a digital mortgage has been signed and made effective applying to have it registered is done using the existing EDRS channel through HM Land Registry's Business Gateway Portal.
For more information on how to develop for Business Gateway please find the developer documentation here Business Gateway Developer Pack
To submit a digital mortgage follow the steps outlined in the Business Gateway documentation to lodge an Application and add a certified document to follow to the application as shown below:
<Document>
<CertifiedCopy>Certified</CertifiedCopy>
</Document>
However once this application has been lodged do not submit a request to lodge the charge document - Business Gateway will detect that this is a Digital Mortgage and do this for you automatically.