Validating Customer Application Data
Preface
HM Land Registry (HMLR) is developing a new Validating Customer Application Data API to improve the process of submitting information to HMLR.
HMLR is also working on a developer pack to provide integrators with the information they need to replace the existing e-DRS SOAP API with the new version.
This pack will explain why we’re moving to a new API, provide a list of new features and demonstrate how to build and integrate it into your systems.
Feedback can be provided publicly on the GitLab issue or privately to our email channelpartners@landregistry.gov.uk.
Introduction
The new Validating Customer Application Data RESTful API will help to lodge orders with HM Land Registry to update the register or create a new lease or transfer of part. This new API will replace the existing e-DRS SOAP API and is designed to help applicants get their applications right the first time.
The new system will provide a faster and more responsive service than before. It’ll help identify errors prior to acceptance of an application, resulting in fewer requisitions and an improved experience for our customers.
To achieve this, the new API will:
- collect and validate more data than the current version
- increase the number of automated checks on application data prior to submission
- automatically check the format and structure of data
- validate information added to the application against information already on the register
- check, compare and validate the data you provide, and the information contained in the attached documents
In return, you’ll benefit from:
- increased output and data quality: With built-in checks on all application types, including charge or transfer transactions, you’ll face fewer requisitions
- consistent results across services: You’ll get parity of outcomes across our digital services
- greater data confidence and automation: More accurate data will provide opportunities to streamline our processes and improve the service for customers
- error prevention: The system will help you catch and fix administrative errors before submission
- improved attachment process: Attaching and classifying deeds will be quicker and more straightforward
- upgraded technology: You’ll benefit from a faster, more responsive platform
Changes from the SOAP API
We’ve made several important updates to the new RESTful API:
- Document uploads before order submission: you will now need to upload documents before submitting an order
- JSON format: instead of using XML, the request bodies for the new APIs will use the simpler, more efficient JSON format
- Asynchronous order submission: when you submit an order, a successful response means the request has been received. Acceptance and prioritisation will occur after validation has been applied
- Renaming applications to transactions: applications are now referred to as Transactions, and their order within the JSON will determine their priority
- Removing notes: the Notes section is no longer included but additional data fields have been added to collect the data commonly found in this field
- New fields: transaction specific data has been included, initially for transfer and charge transactions including charge values and information on joint tenancies
- Fees will be automatically calculated: this enhancement will come in a later version
Using the new API will mean that applications are only accepted onto the Day List when the data provided is both valid and correct. Applications with validation errors will not be accepted. This will significantly reduce the number of avoidable administrative requisitions, identify common avoidable mistakes such as name discrepancies or missing details and thus increase our ability to automate applications.
The new service will have endpoints to support:
- Document Capture - The ability to upload documents to HM Land Registry
- Order Submission - The ability to request to submit an Order to HM Land Registry
- Order Status - The ability to fetch the current state of an Order that has been submitted
Diagrams
Submitting an order
API Specification
Document Capture
The document capture capability should be used to attach documents to your order. There are two steps for uploading a document:
- A POST request to generate an upload URL
- A PUT request to upload the document
API Specification
See the API Specification here
Generate an upload URL
Making a POST request to the generate upload URL endpoint will result in the following items being returned:
upload_url- This is the URL to make the PUT request to. This URL will only be valid for a few minutes after generationdocument_id- This is a unique ID for this document, and must be included in the order submission payload
Uploading a document
To upload a document, make a PUT request to the URL returned from the POST API above. This request should contain the document as the body content. A 200 HTTP code will be returned if the upload was successful.
Do not use the upload URL more than once. Do not modify the URL.
This is an upload to an AWS S3 bucket, and therefore the error API responses that may be returned will be as described in the AWS documentation
Diagrams
Examples
POST /document/url - Request
{
"data": {
"document_type": "TR1"
}
}
POST /document/url - Response
{
"upload_url": "document-capture.landregistry.gov.uk/04c5c3fe-aa08-473b-9944-64ef5506f8e2",
"document_id": "04c5c3fe-aa08-473b-9944-64ef5506f8e2"
}
Note: The URL in the example may not be representative of the actual URL received.
PUT document - Request
- URL matches upload_url in
/document/urlresponse - Body content is the document to upload
PUT document - Response
- HTTP 200 on successful upload
- HTTP 4xx on failure
Order Submission
The Order Submission API is used to provide the necessary data to HM Land Registry for updating the register. This API is asynchronous, returning a unique ID for the submission request which can be used when fetching the order status.
Order submission supports the following Order types:
- Register update
- Transfer of part
- Depositionary first lease
API Specification
See the API Specification here
SOAP migration guide
The structure has changed between the SOAP and REST APIs. Most fields retain their existing names, but some have changed, as noted below:
| SOAP Field | REST Field | Comment |
|---|---|---|
| ChargeDate | date | Field on the transaction type Charge
|
| CompanyName | organisation_name | |
| ConveyancerName | full_name | Field on OtherConveyancer object |
| DisclosableOveridingInterests | disclosable_overriding_interests | |
| CertifiedCopy | certification_statement_type | |
| DXExchange | exchange_name | Field on DxAddress object |
| DXNumber | number | Field on DxAddress object |
| Product.Email | Field on OrderLodger object |
|
| EmailAddress.Email | Field on Address object, where type is Email
|
|
| IsApplicant | applicants[] | Array containing PartyReferences for applicants |
| NoMDRef | - | MDref should not be sent |
| OverseasTerritory | incorporation_territory | |
| RepresentitiveId | representation_type | |
| RoleType | Role | Field on PartyRole object |
| MessageID | Idempotency-Key | Idempotency-Key is a HTTP Header to be added in a future schema revision |
Submit an Order Request
To submit an order request, make a HTTP POST request to the order request endpoint, the body of which contains the information about the order using the “application/json” content type. The data in the body content contains:
- Addresses
- Documents
- Parties
- Transactions
- Titles
The API Specification describes the structure of the request payload in detail.
This endpoint will return an object containing a unique ID for the request, “order_request_id”, which is then used when fetching the status of the order. Any errors in the schema will be rejected as a 400 HTTP error, any other validation errors will be returned in the Order Status response.
Examples
POST - /order/submit - Charge
{
"data": {
"type": "REGISTER_UPDATE",
"ap1_warning_understood": true,
"customer_reference": "MyApplication",
"order_lodger": {
"email": {
"type": "EMAIL",
"email": "user@company.com"
},
"telephone": "07000000000",
"type": "CONVEYANCER"
},
"addresses": [
{
"reference": "borrower-address-1",
"details": {
"type": "UK",
"full_address": "1 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "1",
"postcode": "AA1 00Z"
}
}
],
"applicants": [
{
"party_reference": "borrower-1"
}
],
"documents": [
{
"reference": "mortgage-deed",
"document_id": "0001",
"document_metadata": {
"certification_statement_type": "CERTIFIED",
"document_filename": "deed.pdf"
},
"type": "MORTGAGE_DEED"
}
],
"parties": [
{
"reference": "borrower-1",
"type": "PRIVATE_INDIVIDUAL",
"address_for_service_option": "PROVIDED_ADDRESS",
"addresses": [
"borrower-address-1"
],
"forenames": "Alice",
"surname": "Smith",
"identity_evidence_type": "NOT_REQUIRED",
"representation_type": "LODGING_CONVEYANCER"
},
{
"reference": "lender-1",
"type": "UK_COMPANY",
"address_for_service_option": "NOT_REQUIRED",
"company_number": "543252345",
"organisation_name": "A. Bank",
"identity_evidence_type": "NOT_REQUIRED"
}
],
"titles": [
{
"title_number": "TN001",
"title_type": "REGISTER_TITLE",
"disclosable_overriding_interests": false,
"scope_details": {
"scope": "WHOLE"
}
}
],
"transactions": [
{
"type": "C",
"details": {
"type": "Charge",
"date": "2024-01-01",
"mdref": "MD00AA",
"value": 345000
},
"documents": [
"mortgage-deed"
],
"party_roles": [
{
"capacity": "REGISTERED_PROPRIETOR",
"party_reference": "borrower-1",
"role": "BORROWER"
},
{
"capacity": "NOT_REQUIRED ",
"party_reference": "lender-1",
"role": "LENDER"
}
],
"title_references": [
"TN001"
]
}
]
}
}
POST - /order/submit - Transfer
{
"data": {
"ap1_warning_understood": true,
"customer_reference": "MyApplication",
"type": "REGISTER_UPDATE",
"order_lodger": {
"email": {
"type": "EMAIL",
"email": "user@company.com"
},
"telephone": "07000000000",
"type": "CONVEYANCER"
},
"applicants": ["transferor-1", "transferor-2"],
"addresses": [
{
"reference": "transferor-address-1",
"details": {
"type": "UK",
"full_address": "1 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "1",
"postcode": "AA1 00Z"
}
},
{
"reference": "transferee-address-1",
"details": {
"type": "UK",
"full_address": "2 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "2",
"postcode": "AA1 00Z"
}
}
],
"parties": [
{
"reference": "transferor-1",
"type": "PRIVATE_INDIVIDUAL",
"addresses": ["transferor-address-1"],
"forenames": "Jane",
"surname": "Doe",
"representation_type": "LODGING_CONVEYANCER"
},
{
"reference": "transferor-2",
"type": "PRIVATE_INDIVIDUAL",
"addresses": ["transferor-address-1"],
"forenames": "John",
"surname": "Doe",
"representation_type": "LODGING_CONVEYANCER"
},
{
"reference": "transferee-1",
"type": "OVERSEAS_COMPANY",
"addresses": ["transferee-address-1"],
"organisation_name": "OverseaComp Inc.",
"incorporation_territory": "Europe under the Treaty on European Union and the Treaty on the Functioning of the European Union",
"company_number": "123456",
"representation_type": "NOT_REPRESENTED",
"identity_evidence_type": "VERIFIED"
}
],
"titles": [
{
"title_number": "TN001",
"title_type": "REGISTER_TITLE",
"disclosable_overriding_interests": false,
"scope_details": {
"scope": "WHOLE"
}
},
{
"title_number": "TN002",
"title_type": "REGISTER_TITLE",
"disclosable_overriding_interests": false,
"scope_details": {
"scope": "PART",
"part_description": "The field on the north side of the property"
}
}
],
"transactions": [
{
"type": "T",
"details": {
"type": "Transfer",
"additional_provisions_code": "MANUAL_TR1_FORM",
"date": "2024-01-01",
"value": 500000,
"consideration_type": "MONETARY_VALUE",
"title_guarantee_code": "FULL",
"trust_declaration_type": "JOINT_TENANTS"
},
"party_roles": [
{
"party_reference": "transferor-1",
"role": "TRANSFEROR",
"capacity": "REGISTERED_PROPRIETOR"
},
{
"party_reference": "transferor-2",
"role": "TRANSFEROR",
"capacity": "REGISTERED_PROPRIETOR"
},
{
"party_reference": "transferee-1",
"role": "TRANSFEREE",
"capacity": "ENTITLED_REGISTERED_PROPRIETOR"
}
],
"title_references": [
"TN001",
"TN002"
],
"documents": [
"tr1",
"identity-evidence"
]
}
],
"documents": [
{
"type": "TR1",
"reference": "tr1",
"document_id": "00001",
"document_metadata": {
"certification_statement_type": "CERTIFIED",
"document_filename": "tr1.pdf"
}
},
{
"type": "EVIDENCE",
"reference": "identity-evidence",
"document_id": "00002",
"document_metadata": {
"certification_statement_type": "CERTIFIED_BY_ANOTHER",
"document_filename": "evidence.pdf"
}
}
]
}
}
POST - /order/submit - Discharge, Transfer, Charge
{
"data": {
"ap1_warning_understood": true,
"customer_reference": "MyApplication",
"type": "REGISTER_UPDATE",
"order_lodger": {
"email": {
"type": "EMAIL",
"email": "user@company.com"
},
"telephone": "07000000000",
"type": "CONVEYANCER"
},
"applicants": [
"transferor-1",
"transferor-2"
],
"addresses": [
{
"reference": "transferor-address-1",
"details": {
"type": "UK",
"full_address": "1 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "1",
"postcode": "AA1 00Z"
}
},
{
"reference": "transferee-address-1",
"details": {
"type": "UK",
"full_address": "2 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "2",
"postcode": "AA1 00Z"
}
}
],
"parties": [
{
"reference": "transferor-1",
"type": "PRIVATE_INDIVIDUAL",
"addresses": [
"transferor-address-1"
],
"forenames": "Jane",
"surname": "Doe",
"representation_type": "LODGING_CONVEYANCER"
},
{
"reference": "transferor-2",
"type": "PRIVATE_INDIVIDUAL",
"addresses": [
"transferor-address-1"
],
"forenames": "John",
"surname": "Doe",
"representation_type": "LODGING_CONVEYANCER"
},
{
"reference": "transferee-1",
"type": "OVERSEAS_COMPANY",
"addresses": [
"transferee-address-1"
],
"organisation_name": "OverseaComp Inc.",
"incorporation_territory": "Europe under the Treaty on European Union and the Treaty on the Functioning of the European Union",
"company_number": "123456",
"representation_type": "NOT_REPRESENTED",
"identity_evidence_type": "VERIFIED"
},
{
"reference": "lender-1",
"type": "UK_COMPANY",
"address_for_service_option": "NOT_REQUIRED",
"company_number": "543252345",
"organisation_name": "A. Bank",
"identity_evidence_type": "NOT_REQUIRED"
}
],
"titles": [
{
"title_number": "TN001",
"title_type": "REGISTER_TITLE",
"disclosable_overriding_interests": false,
"scope_details": {
"scope": "WHOLE"
}
},
{
"title_number": "TN002",
"title_type": "REGISTER_TITLE",
"disclosable_overriding_interests": false,
"scope_details": {
"scope": "PART",
"part_description": "The field on the north side of the property"
}
}
],
"transactions": [
{
"type": "DIS",
"details": {
"type": "Discharge",
"discharge_submission_type": "ATTACHED"
},
"party_roles": [
{
"party_reference": "transferor-1",
"role": "BORROWER",
"capacity": "REGISTERED_PROPRIETOR"
},
{
"party_reference": "transferor-2",
"role": "BORROWER",
"capacity": "REGISTERED_PROPRIETOR"
}
],
"title_references": [
"TN001"
],
"documents": [
"discharge"
]
},
{
"type": "T",
"details": {
"type": "Transfer",
"additional_provisions_code": "MANUAL_TR1_FORM",
"date": "2024-01-01",
"value": 500000,
"consideration_type": "MONETARY_VALUE",
"title_guarantee_code": "FULL",
"trust_declaration_type": "JOINT_TENANTS"
},
"party_roles": [
{
"party_reference": "transferor-1",
"role": "TRANSFEROR",
"capacity": "REGISTERED_PROPRIETOR"
},
{
"party_reference": "transferor-2",
"role": "TRANSFEROR",
"capacity": "REGISTERED_PROPRIETOR"
},
{
"party_reference": "transferee-1",
"role": "TRANSFEREE",
"capacity": "ENTITLED_REGISTERED_PROPRIETOR"
}
],
"title_references": [
"TN001",
"TN002"
],
"documents": [
"tr1",
"identity-evidence"
]
},
{
"type": "C",
"details": {
"type": "Charge",
"date": "2024-01-01",
"mdref": "MD00AA",
"value": 200000
},
"documents": [
"mortgage-deed"
],
"party_roles": [
{
"capacity": "REGISTERED_PROPRIETOR",
"party_reference": "transferee-1",
"role": "BORROWER"
},
{
"capacity": "NOT_REQUIRED",
"party_reference": "lender-1",
"role": "LENDER"
}
],
"title_references": [
"TN001",
"TN002"
]
}
],
"documents": [
{
"type": "TR1",
"reference": "tr1",
"document_id": "00001",
"document_metadata": {
"certification_statement_type": "CERTIFIED",
"document_filename": "tr1.pdf"
}
},
{
"type": "EVIDENCE",
"reference": "identity-evidence",
"document_id": "00002",
"document_metadata": {
"certification_statement_type": "CERTIFIED_BY_ANOTHER",
"document_filename": "evidence.pdf"
}
},
{
"type": "DISCHARGE",
"reference": "discharge",
"document_id": "00003",
"document_metadata": {
"certification_statement_type": "CERTIFIED",
"document_filename": "discharge.pdf"
}
},
{
"type": "MORTGAGE_DEED",
"reference": "mortgage-deed",
"document_id": "00004",
"document_metadata": {
"certification_statement_type": "CERTIFIED_BY_ANOTHER",
"document_filename": "deed.pdf"
}
}
]
}
}
POST - /order/submit - Transfer of Part
{
"data": {
"type": "TRANSFER_OF_PART",
"customer_reference": "tp-not-for-value",
"ap1_warning_understood": true,
"order_lodger": {
"email": {
"type": "EMAIL",
"email": "user@company.com"
},
"telephone": "07000000000",
"type": "NON_CONVEYANCER"
},
"addresses": [
{
"reference": "transferor-address-1",
"details": {
"type": "UK",
"full_address": "1 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "1",
"postcode": "AA1 00Z"
}
},
{
"reference": "transferee-address-1",
"details": {
"type": "UK",
"full_address": "2 Fake Street, Madeup Town, Unknown County, AA1 00Z",
"number": "2",
"postcode": "AA1 00Z"
}
}
],
"applicants": ["transferor-1"],
"parties": [
{
"reference": "transferor-1",
"type": "PRIVATE_INDIVIDUAL",
"addresses": ["transferor-address-1"],
"forenames": "Jane",
"surname": "Doe",
"representation_type": "LODGING_CONVEYANCER"
},
{
"reference": "transferee-1",
"type": "PRIVATE_INDIVIDUAL",
"addresses": ["transferee-address-1"],
"forenames": "John",
"surname": "Doe",
"representation_type": "OTHER_CONVEYANCER",
"other_conveyancer": {
"conveyancer_reference": "ABC123",
"full_name": "Mike Ross",
"registered_address": "1234 56th Street, New York, 10001"
}
}
],
"titles": [
{
"title_number": "TN001",
"title_type": "TRANSFEROR_TITLE",
"disclosable_overriding_interests": false,
"scope_details": {
"scope": "PART",
"part_description": "The field on the north side of the property"
}
}
],
"transactions": [
{
"type": "TNVTP",
"detials": {
"type": "Transfer",
"value_band": {
"lower_value_band": 100001,
"upper_value_band": 200000
},
"outstanding_charge": 0,
"full_value_of_property_band": {
"lower_value_band": 1000001
},
"date": "2024-01-01",
"title_guarantee_code": "LIMITED",
"consideration_type": "NO_MONETARY_VALUE"
},
"documents": [
"tp-1"
],
"party_roles": [
{
"party_reference": "transferor-1",
"role": "TRANSFEROR",
"capacity": "REGISTERED_PROPRIETOR"
},
{
"party_reference": "transferee-1",
"role": "TRANSFEREE",
"capacity": "ENTITLED_REGISTERED_PROPRIETOR"
}
],
"title_references": ["TN001"]
}
],
"documents": [
{
"reference": "tp-1",
"type": "TP1",
"document_id": "00001",
"document_metadata": {
"certification_statement_type": "CERTIFIED_BY_ANOTHER",
"document_filename": "tp1.gif"
}
}
]
}
}
Order Status
The Order Status API is used to get the status of a specific order, using the order_request_id returned by the order submission request. The status of an order can currently be one of the following:
PENDING- HM Land Registry are still processing the application, and it has not yet been added to the DaylistNOT_ACCEPTED- The order has not been added to the Daylist, due to errors during validation. The errors that were found are included in theerrorssection in the responseQUEUED_OUT_OF_HOURS- The order has passed validation but has not yet been added to the Daylist as the Daylist is currently closed. The Order will be added to the Daylist and will move to anACCEPTEDstate after the Daylist reopensACCEPTED- The order has been accepted onto the Daylist, and has priorityNOT_CREATED- The order has not been added to the Daylist, due to an HM Land Registry system error. The request should be retried, or the support team contacted
The Order status API also includes other information about the order, including:
- The fees that were calculated for the order, which will be automatically deducted from the provided vdd_account_number
- The order_request_id used in the request
- An ID for the accepted order,
hmlr_reference, once accepted - The priority of the application,
priority_timestamp, once accepted - Any errors that prevented order submission
In its current form, you will need to poll this endpoint to identify when status changes occur. We anticipate later iterations of these API designs will include a way to receive notifications of multiple types of change being available, like the current SOAP ‘Outstanding Requests’ service, removing the need to poll this specific endpoint.
This API will always return a HTTP 200 response for a valid request, regardless of the status of the order. Any other status codes reflect an issue with retrieving the status.
API Specification
See the API Specification here
Diagrams
Interaction
State Diagram
Examples
GET /order/{id}/status - PENDING status
{
"status": "PENDING",
"order_request_id": "3e4f6da2-ada7-4081-957c-b23542466715"
}
GET /order/{id}/status - ACCEPTED status
{
"status": "ACCEPTED",
"order_request_id": "3e4f6da2-ada7-4081-957c-b23542466715",
"hmlr_reference": "AB1234",
"priority_timestamp": "2024-09-25T18:18:49.478Z",
"calculated_fees": {
"total_fee": 45,
"per_transaction": [
{
"transaction_reference": "transfer-1",
"fee": 45
}
]
}
}
GET /order/{id}/status - NOT_ACCEPTED status
{
"status": "NOT_ACCEPTED",
"order_request_id": "3e4f6da2-ada7-4081-957c-b23542466715",
"errors": [
{
"type": "L2_MDREF_ERROR",
"summary": "MDRef validation Failed",
"detail": "The MDref included in the request does not exist",
"pointer": "/data/transaction/0/details/mdref"
}
]
}
GET /order/{id}/status - QUEUED_OUT_OF_HOURS status
{
"status": "QUEUED_OUT_OF_HOURS",
"order_request_id": "3e4f6da2-ada7-4081-957c-b23542466715"
}
Glossary
| Term | Description |
|---|---|
| Application Programming Interface (API) | A set of routines, protocols and tools for building software applications |
| Case Management System (CMS) | Software used by legal firms to manage business matters, including conveyancing |
| Charge | Software used by legal firms to manage business matters, including conveyancing |
| Electronic Document Registration Service (e-DRS) | A group of services that allow users to submit electronic applications to change the register, along with supporting documents |
| Hypertext transfer protocol (HTTP) | A protocol to transfer hypertext requests and information between servers and browsers |
| Joint Tenants | Joint tenants hold the property on trust for themselves. This means that in the event of the death of one of the joint owners the deceased parties share would automatically revert to the surviving owner. The HM Land Registry would only require a certified copy of the Death Certificate of the deceased owner to update the register |
| JavaScript Object Notation (JSON) | JSON is a lightweight data interchange format, containing a collection of name/value pairs and ordered lists of values |
| Proprietor | The Proprietor is the current registered owner of land or property as shown in the Official Copy Register Entries |
| Simple Object Access Protocol (SOAP) | A protocol specification for exchanging structured information in the implementation of web services |
| Secure Sockets Layer (SSL) | A protocol developed for transmitting private documents via the internet. SSL uses asymmetric cryptography to encrypt data - a public key known to everyone and a private key known only to the recipient of the message |
| Uniform Resource Locator (URL) | A string that supplies the internet address of a web site or resource on the web, along with the protocol by which the site or resource is accessed |
| Variable Direct Debit (VDD) | A payment method where the customer enters into an agreement with the merchant giving authority to directly debit a nominated account in payment for goods or services |