HM Land Registry V0.3 'Submit an application to change the Land Register API' Schema
HM Land Registry V0.3 'Submit an application to change the Land Register API' Schema from HM Land Registry — 6 path(s) described in OpenAPI.
OpenAPI Specification
{
"openapi": "3.0.1",
"info": {
"description": "V0.3 of the set of APIs for the new 'Submit an application to change the Land Register API' Schema",
"title": "V0.3 'Submit an application to change the Land Register API' Schema",
"version": "0.3"
},
"servers": [
{
"url": "https://businessgateway.landregistry.gov.uk/bg2/api",
"description": "Production"
},
{
"url": "https://bgtest.landregistry.gov.uk/bg2test/api",
"description": "Stub"
}
],
"paths": {
"/v0/applications": {
"post": {
"description": "Submit an application API - Submit application creation requests for processing",
"operationId": "Submit an application API",
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubstantiveApplication"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationCreationDataResponse"
}
}
},
"description": "Application creation request accepted",
"headers": {
"Location": {
"description": "Get application creation status URI for checking status",
"schema": {
"type": "string"
},
"style": "simple"
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Request due to payload not meeting the required schema"
},
"401": {
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Unauthorised - an access token is required"
},
"500": {
"description": "Internal Server Error"
}
},
"tags": [
"Submit an application API"
]
}
},
"/v0/documents/url": {
"post": {
"description": "Create an upload URL - Retrieve a generated document upload URL",
"operationId": "Create an upload URL",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentUploadUrlRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Request was successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentUploadUrlDataResponse"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorised - an access token is required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"tags": [
"Send a document API"
]
}
},
"Upload a document": {
"servers": [
{
"url": "documentcapture.landregistry.gov.uk",
"description": "An example domain for document uploads"
}
],
"put": {
"operationId": "Upload a document",
"description": "Upload a document - Upload the document contents. **Note**: This URL, including hostname and path parameters is returned from the create URL endpoint and **should be used unmodified**. The path and hostname given in the API specification here are examples only.",
"security": [],
"parameters": [
{
"in": "header",
"name": "X-Amz-Checksum-Sha256",
"description": "The base64 encoded SHA-256 hash of the file contents. Must match both the document being uploaded and the value provided to the create URL endpoint.",
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Content-Length",
"description": "The length of the file in bytes. Must match both the document being uploaded and the value provided to the create URL endpoint.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"403": {
"description": "Forbidden. Ensure the content length and SHA-256 headers have been provided, and match both the file length and sha256 hash, and were the same values supplied to the create URL endpoint"
}
},
"tags": [
"Send a document API"
]
}
},
"/v0/applications/{application_request_id}/information": {
"get": {
"description": "Application information API - Get the information about an application",
"operationId": "Application information API",
"parameters": [
{
"description": "The ID returned by Application Creation to track submission requests",
"in": "path",
"name": "application_request_id",
"example": "12345678-1234-1234-1234-123546789abc",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusDataResponse"
}
}
},
"description": "Request status received"
},
"400": {
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Unauthorised - an access token is required"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Application creation request not found in the system"
},
"500": {
"description": "Internal Server Error"
}
},
"tags": [
"Application information API"
]
}
},
"/v0/notifications": {
"get": {
"description": "Receive notifications API - Get any unacknowledged notifications",
"operationId": "Receive notifications API",
"parameters": [
{
"in": "query",
"name": "created_before",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"in": "query",
"name": "created_after",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"type": "string",
"enum": [
"NEW",
"ACKNOWLEDGED"
]
}
},
{
"in": "query",
"name": "occurred_before",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"in": "query",
"name": "occurred_after",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"in": "query",
"name": "notification_type",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "subject",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "additional_provider_filter",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "List of notifications",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NotificationResponse"
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
}
},
"tags": [
"Notifications API"
]
}
},
"/v0/notifications/acknowledge": {
"post": {
"description": "Acknowledge notifications API - Acknowledge notifications that have been processed, so they are no longer returned when fetching",
"operationId": "Acknowledge notifications API",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notifications acknowledged successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/BulkAcknowledgeResult"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetail"
}
}
}
}
},
"tags": [
"Notifications API"
]
}
}
},
"components": {
"schemas": {
"AddressReference": {
"maxLength": 50,
"minLength": 1,
"pattern": "^[A-Za-z0-9-?,_]+$",
"type": "string",
"description": "Unique identifier for addresses, used to reference addresses from elsewhere in the spec",
"example": "property address"
},
"PartyReference": {
"maxLength": 50,
"minLength": 1,
"pattern": "^[A-Za-z0-9-?,_]+$",
"type": "string",
"description": "Unique identifier for parties, used to reference parties from elsewhere in the spec",
"example": "customer"
},
"DocumentReference": {
"maxLength": 50,
"minLength": 1,
"pattern": "^[A-Za-z0-9-?,_]+$",
"type": "string",
"description": "Unique identifier for documents, used to reference documents from elsewhere in the spec",
"example": "signed_charge"
},
"TransactionReference": {
"maxLength": 50,
"minLength": 1,
"pattern": "^[A-Za-z0-9-?,_]+$",
"type": "string",
"description": "Unique identifier for transactions, used to reference transactions from elsewhere in the spec",
"example": "property charge"
},
"TransactionFee": {
"type": "object",
"properties": {
"transaction_reference": {
"$ref": "#/components/schemas/TransactionReference"
},
"fee": {
"description": "Fee in pence",
"type": "integer"
}
}
},
"AddressDetails": {
"type": "object",
"description": "The details captured for a specific address. Details differ depending on type",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"UK",
"OVERSEAS",
"EMAIL",
"DX",
"BFPO",
"PO_BOX"
]
}
},
"discriminator": {
"propertyName": "type"
}
},
"AddressForServiceOption": {
"type": "string",
"description": "* `PROVIDED_ADDRESS` - The address for service has been provided alongside this option\n* `NOT_REQUIRED` - The address for service is not required for the party",
"enum": [
"PROVIDED_ADDRESS",
"NOT_REQUIRED"
]
},
"AmountDetails": {
"type": "object",
"description": "A type of TransactionDetails that captures the value of the transaction",
"allOf": [
{
"$ref": "#/components/schemas/TransactionDetails"
},
{
"type": "object",
"properties": {
"value": {
"minimum": 0,
"description": "The value associated with the transaction in pounds",
"type": "integer",
"format": "int32"
},
"value_band": {
"$ref": "#/components/schemas/ValueBand"
},
"full_value_of_property_band": {
"$ref": "#/components/schemas/ValueBand"
},
"full_value_of_property": {
"type": "integer",
"format": "int32",
"description": "Full value of the property in the title(s) in pounds"
},
"outstanding_charge": {
"type": "integer",
"format": "int32",
"description": "Value in pounds of any outstanding charge if applicable"
}
}
}
]
},
"BypassValidationData": {
"required": [
"comment",
"reason",
"validation_pointer",
"validation_type"
],
"type": "object",
"description": "Fields to describe which validators to bypass and why",
"properties": {
"validation_type": {
"maxLength": 250,
"minLength": 1,
"description": "The type of validation to bypass. Should match the 'type' returned within a status API error",
"type": "string"
},
"validation_pointer": {
"maxLength": 250,
"minLength": 1,
"description": "A JSON pointer to the field in the submission payload to bypass the validation on. Should match the 'pointer' returned within a status API error",
"type": "string",
"example": "/data/customer_reference"
},
"reason": {
"type": "string",
"description": "The reason the validation is being bypassed",
"enum": [
"DISAGREE_WITH_REGISTER",
"HMLR_DATA_INCORRECT_OR_OUTDATED",
"EXCEPTION_NOT_COVERED_BY_BUSINESS_RULES"
]
},
"comment": {
"maxLength": 250,
"minLength": 1,
"description": "A user inputted description of why the validation is being bypassed",
"type": "string"
}
}
},
"Charge": {
"required": [
"date",
"value"
],
"type": "object",
"description": "A TransactionDetails object to capture information about a charge",
"allOf": [
{
"$ref": "#/components/schemas/TransactionDetails"
},
{
"type": "object",
"properties": {
"date": {
"description": "The date of the charge, in the format yyyy-MM-dd",
"type": "string",
"format": "date"
},
"mdref": {
"maxLength": 10,
"minLength": 0,
"description": "The unique MD reference given to the mortgage",
"type": "string",
"example": "MD123A"
},
"value": {
"type": "integer",
"description": "The total charge amount for all titles in pounds",
"format": "int32"
}
}
}
]
},
"Discharge": {
"required": [
"discharge_submission_type"
],
"type": "object",
"description": "A TransactionDetails object to capture information about a discharge",
"allOf": [
{
"$ref": "#/components/schemas/TransactionDetails"
},
{
"type": "object",
"properties": {
"discharge_submission_type": {
"type": "string",
"description": "How the discharge will be submitted:\n* ATTACHED - The discharge is submitted with this application\n* LENDER - The lender will submit the discharge\n* LATER - The discharge will be submitted later",
"enum": [
"ATTACHED",
"LENDER",
"LATER"
]
}
}
}
]
},
"DocumentMetadata": {
"required": [
"certification_statement_type",
"document_filename"
],
"type": "object",
"description": "Metadata about the document that was uploaded",
"properties": {
"certification_statement_type": {
"type": "string",
"description": "* `CERTIFIED` - I/we certify this is a true copy of an original document\n* `CERTIFIED_BY_ANOTHER` - I/we certify this document is a true copy of an original document which is certified by a conveyancer to be a true copy of the original\n* `NOT_CERTIFIED` - This document is an uncertified copy ",
"enum": [
"CERTIFIED",
"CERTIFIED_BY_ANOTHER",
"NOT_CERTIFIED"
]
},
"document_filename": {
"maxLength": 255,
"minLength": 0,
"description": "The filename of the document",
"type": "string",
"example": "thedeed.pdf"
}
}
},
"DocumentUploadUrlDataResponse": {
"type": "object",
"description": "The response object containing information needed for uploading a document",
"properties": {
"data": {
"$ref": "#/components/schemas/DocumentUploadUrlResponse"
}
}
},
"DocumentUploadUrlResponse": {
"type": "object",
"description": "The response object containing information needed for uploading a document",
"properties": {
"upload_url": {
"type": "string",
"description": "The URL used to upload the document. The request must be a PUT HTTP request, where the body of the request is the document that will be uploaded. This URL should only be used once",
"example": "about:blank"
},
"document_id": {
"type": "string",
"description": "A unique id for this document, which should be used in the application submission request",
"example": "12345678-1234-1234-1234-1234-123456789abc"
}
}
},
"DocumentUploadUrlData": {
"required": [
"file_length",
"file_sha256",
"document_type"
],
"type": "object",
"description": "The data needed to generate a URL to upload a document",
"properties": {
"document_type": {
"type": "string",
"description": "The HM Land registry document type",
"enum": [
"ABSTRACT",
"ACKAPU",
"ADJAR",
"ADJREVU",
"ADMIN_LTRS",
"ADV1",
"ADV2",
"AGREEMENT",
"AMS1",
"AN1",
"AP1",
"APPL_FRM",
"APPOINTMENT_OF_TRUSTEE",
"AS1",
"AS2",
"AS3",
"ASSENT",
"ASSIGNMENT",
"BIRTH_CERT",
"BOUND_PLAN",
"CC",
"CCD",
"CERT_CON_CH",
"CERT_DEATH",
"CERT_REG_CH",
"CERT_S89",
"CH1",
"CH2",
"CH3",
"CHARG_ORD",
"CHARGE",
"CIVIL_CERT",
"CM2",
"CM5",
"CM6",
"CN1",
"CNFRM_DTMN_LTA_LGHA",
"CNFRM_NO_DEED_SUR",
"CNFRM_NO_LTA_LGHA",
"CNSNT_ADMIN_COURT",
"COMP_DOC",
"CONSENT",
"CONST_COMP",
"CONTR_RES",
"CONV_CERT",
"CONV_CERT_DEATH",
"CONVEYANCE",
"COR_CERT",
"CORRES",
"COSR",
"COURT_ORD",
"CRALIQ",
"CRED_DEC",
"CRED_RES",
"CRT_FORM_7",
"CRWALIQ",
"DB",
"DEATH_CERT",
"DEC_AB_NULL_MARR",
"DEED",
"DEED_POLL",
"DEED_REG_DIS",
"DEED_SUR",
"DISCHARGE",
"DJP",
"DL",
"DOP",
"DRIVING_LICENCE",
"DS1",
"DS2",
"DS3",
"DS3_SHORT",
"EOB",
"EOL",
"EVD_NO_RENEW",
"EVIDENCE",
"EV_OV_NAME_CHANGE",
"EX1",
"EX1A",
"FORM_600",
"FORM_600CH",
"FORM_DI",
"FORM_JO",
"FR1",
"GENDER_CERT",
"GVD",
"HR1",
"HR2",
"HR4",
"ID1",
"ID2",
"ID3",
"ID4",
"ID5",
"ID_EV",
"ID_FRM",
"INDENTURE",
"JP1",
"K17_OR_K18",
"K20",
"K22",
"K3",
"K4",
"LEASE",
"LICENCE",
"LIQ_CERT_1",
"LIQ_CERT_2",
"LIQ_CERT_3",
"LIQ01",
"LNDLD_CNSNT",
"LONP",
"LR_CORRES",
"LTT",
"MARR_CERT",
"MEMO",
"MORD",
"MRTG_DEED",
"NOD",
"ORD_DISS_NULL_CP",
"PASSPORT",
"PLAN",
"POA",
"PROBATE",
"PSS1",
"REVERS_INT",
"RN",
"RX1",
"RX2",
"RX3",
"RX4",
"RXC",
"RXCD",
"SC",
"SDLT",
"SEV",
"SHRF_RTN",
"SIDE_LTR",
"SOT",
"SSALIQ",
"STAT_DEC",
"SUB_CHARGE",
"TP1",
"TP2",
"TR1",
"TR2",
"TR4",
"TRANSFER",
"TRUSTEE_RESOLUTION",
"UN1",
"UN2",
"UN3",
"UN4",
"UT1",
"VAR_CHARGE",
"VAR_COV",
"VAR_EAS",
"VAR_LEASE",
"VESTING_ORDER",
"WCT",
"WINDING_UP",
"WIT_STATE"
]
},
"additional_provider_filter": {
"type": "string",
"description": "A value that can be used to subsequently retrieve request responses based upon high level grouping"
},
"file_length": {
"maximum": 41943040,
"minimum": 1,
"type": "integer",
"description": "The file contents length in bytes",
"format": "int64"
},
"file_sha256": {
"maxLength": 44,
"minLength": 44,
"type": "string",
"description": "The checksum of file contents, as a base64 encoded string of the SHA-256 binary digest of the file, which should be 44 characters long. See the Business Gateway developer pack for detailed information on generating the correct SHA-256 hash"
}
}
},
"DocumentUploadUrlRequest": {
"required": [
"data"
],
"type": "object",
"description": "The request to send to the endpoint to request an upload URL",
"properties": {
"data": {
"$ref": "#/components/schemas/DocumentUploadUrlData"
}
}
},
"ErrorResponse": {
"type": "object",
"description": "Wrapper for any error responses",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://landregistry.github.io/bgtechdoc/problems/global#bad-request"
},
"title": {
"type": "string",
"example": "Bad Request"
},
"status": {
"type": "integer",
"format": "int32",
"example": 400
},
"detail": {
"type": "string",
"example": "The request is invalid or malformed."
},
"instance": {
"type": "string",
"format": "uri"
},
"code": {
"type": "string",
"example": "ignore me"
},
"errors": {
"type": "array",
"description": "A list of all errors generated",
"items": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"ProblemDetails": {
"required": [
"detail",
"type"
],
"description": "Detailed information about an error",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of error received",
"example": "L2_MDREF_ERROR"
},
"detail": {
"type": "string",
"description": "A longer description about the type of error received",
"example": "The MDref included in the request does not exist"
},
"pointer": {
"type": "string",
"description": "A JSON pointer to the location in the JSON payload that caused the error (optional)",
"example": ["/data/transaction/t1/mdref"]
}
}
},
"ProblemDetail": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "about:blank",
"description": "A uri referencing documentation for this problem"
},
"title": {
"type": "string",
"nullable": true,
"example": "Server Error",
"description": "A brief summary of the problem"
},
"detail": {
"type": "string",
"nullable": true,
"example": "There was a problem with your request, try again soon.",
"description": "A human readable explanation of the problem"
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hm-land-registry/refs/heads/main/openapi/hm-land-registry-submit-application-to-change-the-register-v0.3-openapi.json