Digital Mortgage Documentation

Create and Manage Mortgage Deeds API Documentation

View the Project on GitHub LandRegistry/deed-api

About This Service

Schemas

Identity Checks

Using This Service as an Intermediary

Test Hub

Example Payloads and Responses

Test Data

Business Gateway

Data Catalogue

About This Service

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.

Organisation-API

As well as the above Deed-API endpoints, the service also provides an endpoint for returning a list of organisation names via Organisation-API.

Identity Checks

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 checks will be performed by your organisation when creating a deed

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 performed by a different organisation than the one that created the deed

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.

Using This Service as an Intermediary

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.

User Authentication

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." }
  

Test Hub

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:

Borrower Frontend

https://sign-your-mortgage-deed.landregistry.gov.uk/testhub

Deed-API

https://bgtest.landregistry.gov.uk/api/deeds

Example Payloads and Responses

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.

Create Deed

POST /deed/

Payload

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"
        }
    ]
}
            
          
Responses
201 CREATED
            
{
  "path": "/deed/0729e738-c073-445f-8976-9c81bbecf5c7"
}
            
          
400 BAD REQUEST
            
{
  "errors": [
    "Problem 1: A mobile phone number must be unique to an individual."
  ]
}
            
          

Terminate Deed

PATCH /deed/<Deed Id>/terminate-deed

Responses
200 OK
                
{
  "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"
}
                
            

Extend Deed

PATCH /deed/<Deed Id>/extend-deed

Responses
200 OK
                
{
  "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"
}
                
            

In-Progress Deed

GET /deed/in-progress

Responses
200 OK
                
[
  {
    "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"
}
                
            

Get Deed

GET /deed/<Deed Id>

Responses
200 OK
            
{
  "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"
}
            
          

Retrieve signed deeds

GET /retrieve-signed

Responses
200 OK
            
{
  "deeds": [
    "40a235b9-78eb-4dab-95d6-db7c75eedcb0",
    "2130a81c-3fbe-4381-ac47-a4300c48f841"
  ]
}
            
          
404 NOT FOUND
            
{
  "message": "There are no deeds which have been fully signed"
}
            
          

Make deed effective

POST /deed/<Deed Id>/make-effective

Responses
200 OK
            
{
  "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."
  ]
}
            
          

Identity Checks

PATCH /deed/<Deed Id>/identity-checks

Payload
            
{
  "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"

    }
  ]
}
            
          
Responses
200 OK
            
{
  "path": "/deed/0729e738-c073-445f-8976-9c81bbecf5c7"
}
            
          
400 BAD REQUEST
            
{
  "message": "Identity checks have failed. Data provided does not match"
}
            
          

Generic error

For any system error not handled by the system the following error will be returned:

            
{
  "message": "Unexpected error."
}
            
          

Test Data

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 .

Good Title

Title number GR515835

Proprietors Ann Smith, Fredd Smith

Closed Title

Title Number GR518327

Response message Title closed and continued under GR518006.

Unsuitable Title

Title Number GR516921

Response Title is not suitable for a digital mortgage as it is a qualified title.

MD Reference

e-MD12344

Business Gateway

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.