Land Register API

openapi: 3.0.1
info:
  title: Land Register API
  description: |
    The Land Register API aims to be the primary method of accessing register data for HM Land Registry.

    The Land Register API provides data and services around the core data set.
    Access to the API must be requested through the Digital Register project team.
    If you would like to integrate systems with the Land Register API then please follow these steps:
    -  Contact the project team about your needs to ensure that the API can serve them.
    -  Create your own client for accessing the API, only returning the data you are using.
    -  Request access to the API through a senior member of the project team (coordination of access in pre-production and production will be handled by WebOps). An individual access token will be created for each consuming service.
    -  Send your access token in the 'Authorization' header of each call to the API. e.g. replace 'abc123' in:
      `curl --header 'Authorization: Bearer abc123' --url ...`
    -  Add to your Fraud Impact Assessment form that you will be accessing the Land Register API, the reasons why it is
      needed and the specific data that is required.
    -  Ensure that the data that is requested by your systems from the API is limited to only the data that you need.
    -  Do NOT directly expose the data to external sources.
    -  Application_timestamp will be returned as a UTC timezone, as such will NOT match exactly how it is stored within legacy databases.

    The Digital Register project team and Counter Fraud team are available to support you through this process.
  contact:
    name: Digital Register Team
    url: https://landregistry.gov.uk
    email: DigitalRegister@landregistry.gov.uk
  version: 6.0.0
servers:
- url: http://localhost:8080/api/v1/
  description: Local development server (outside dev-env)
- url: http://localhost:4780/api/v1/
  description: Local development server (devenv)
- url: https://land-register.development.stp.hmlr.zone/api/v1/
  description: Remote development server
- url: http://10.79.1.126:5001/api/v1/
  description: Integration environment
- url: http://10.79.1.119:5001/api/v1/
  description: Acceptance environment
- url: https://integration-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP integration environment
- url: https://preview-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP preview environment (Acceptance)
- url: https://analysis-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP analysis environment
- url: https://syt1-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP SYT1 environment
- url: https://syt2-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP SYT2 environment
- url: https://syt3-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP SYT3 environment
- url: https://uat1-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP UAT1 environment
- url: https://uat2-land-register-service.apps.core.test.stp.hmlr.zone/api/v1
  description: STP UAT2 environment
security:
- bearerAuth: []
tags:
- name: interest
  description: Operations relating to legal interests that relate parties and places.
- name: party
  description: Operations relating to persons or organisations.
- name: place
  description: Operations relating to land or property.
- name: title
  description: Operations relating to titles for land or property.
paths:
  /title/{titleNumber}:
    get:
      tags:
      - title
      summary: Gets summary information for the title with the specified title number.
      description: |
        ## Error responses
        Calls to this endpoint may return the following error codes:
        | Error code   | Message                                                                           | Cause                                                                                                                  |
        |--------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
        | `LRAPI00401` | The request could not be completed because a valid access token was not provided. | A valid access token must be provided to be able to access this data. Try the request again with a valid access token. |
        | `LRAPI00404` | A title number must be provided.                                                  | The path parameter __{titleNumber}__ cannot be empty. Try the request again with a non-empty value.                    |
        | `LRAPI01001` | The request failed to validate.                                                   | An invalid title number was provided. Check the value to ensure it does not violate the parameter constraints.         |
        | `LRAPI02000` | Title number '__{titleNumber}__' does not exist.                                  | No title with the given title number could be found in the Land Register. Check that the title number is correct.      |
      operationId: getTitle
      parameters:
      - name: titleNumber
        in: path
        description: |-
          The unique reference number of the desired title.

          ---

          The following constraints apply to this parameter:
          | Constraint                                                           | Error message                                           |
          |----------------------------------------------------------------------|---------------------------------------------------------|
          | The parameter must have a length less than or equal to 9 characters. | *The title number must be no longer than 9 characters.* |
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 9
          type: string
        example: AGL117262
        x-validationMessages:
          length: The title number must be no longer than 9 characters.
      responses:
        '200':
          description: Summary information for the title.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TitleResponse'
        '400':
          description: An invalid title number was supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: A valid access token was not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No title with the given title number could be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /draft-titles/{titleNumber}:
    get:
      tags:
      - draft-titles
      summary: Gets summary information for the draft title with the specified title number.
      description: |
        ## Error responses
        Calls to this endpoint may return the following error codes:
        | Error code   | Message                                                                           | Cause     c                                                                                                            |
        |--------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
        | `LRAPI00401` | The request could not be completed because a valid access token was not provided. | A valid access token must be provided to be able to access this data. Try the request again with a valid access token. |
        | `LRAPI00404` | A draft title number must be provided.                                            | The path parameter __{titleNumber}__ cannot be empty. Try the request again with a non-empty value.                    |
        | `LRAPI01001` | The request failed to validate.                                                   | An invalid title number was provided. Check the value to ensure it does not violate the parameter constraints.         |
        | `LRAPI90101` | No draft for title number '__{titleNumber}__' exists.                             | The given title number does not have a current draft associated with it. Check that the title number is correct.       |
      operationId: getDraftTitle
      parameters:
      - name: titleNumber
        in: path
        description: |-
          The unique reference number of the desired title.

          ---

          The following constraints apply to this parameter:
          | Constraint                                                           | Error message                                           |
          |----------------------------------------------------------------------|---------------------------------------------------------|
          | The parameter must have a length less than or equal to 9 characters. | *The title number must be no longer than 9 characters.* |
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 9
          type: string
        example: AGL117262
        x-validationMessages:
          length: The title number must be no longer than 9 characters.
      responses:
        '200':
          description: Summary information for the title.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TitleResponse'
        '400':
          description: An invalid title number was supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: A valid access token was not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No title with the given title number could be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      required:
      - error_code
      - error_message
      - reference
      - status
      type: object
      properties:
        error_message:
          type: string
          description: A human-readable message that provides a summary of the cause of the error.
        reference:
          type: string
          description: |
            The unique reference for the error.
            Quote this reference when seeking technical support from the Digital Register team.
          format: uuid
        error_code:
          type: string
          description: An error code in the form <code>LRAPI<var>xxxxx</var></code> that identifies the cause of the error.
        status:
          maximum: 599
          minimum: 400
          type: integer
          description: The HTTP status code returned by the server with this response.
          format: int32
      description: |
        Returned when an error occurs while trying to serve a request.
        It provides an error code for diagnostic purposes as well as a human-readable message.
    TitleResponse:
      allOf:
      - $ref: '#/components/schemas/ResponseObject'
      - $ref: '#/components/schemas/Title'
      - type: object
        properties:
          interests:
            $ref: '#/components/schemas/Interests'
          concerns:
            $ref: '#/components/schemas/Concerns'
      x-wrapped-type: Title
    ResponseObject:
      type: object
      properties:
        data_issues:
          type: array
          items:
            $ref: '#/components/schemas/DataIssue'
      description: |
        Contains properties common to all successful response types of the Land Register API.
      x-is-wrapper-type: true
    DataIssue:
      required:
      - code
      - message
      - property_name
      - reference
      type: object
      properties:
        reference:
          type: string
          description: |
            The unique reference for the data issue.
            Quote this reference when seeking technical support from the Digital Register team.
          format: uuid
        code:
          $ref: '#/components/schemas/DataQualityIssueType'
        message:
          type: string
          description: A human-readable message that provides a summary of the cause of the issue.
          example: The entry text is currently unavailable.
        property_name:
          type: string
          description: |
            The name of the property that this issue was raised for.
            The full path from the root of the response (`response.body`) is provided, with nodes separated by the '.'
            character.
          example: response.body.entries[0].entry_text
      description: |
        Represents a single issue with the quality of the data available in the Land Register.
    DataQualityIssueType:
      type: string
      description: |
        An issue code in the form <code>data_quality_<var>issue_type</var></code> that identifies the cause of the issue.
      example: data_quality_no_entry_text
      enum:
      - data_quality_language_code_invalid
      - data_quality_class_of_title_invalid
      - data_quality_tenure_invalid
      - data_quality_no_entry_text
      - data_quality_estate_interest_invalid
      - data_quality_class_invalid_for_tenure
      - data_quality_schedule_code_invalid
      - data_quality_multiple_h_schedules
      - data_quality_multiple_q_schedules
      - data_quality_timeshare_lease_code_invalid
      - data_quality_commonhold_type_invalid
      - data_quality_continued_relationship_invalid
      - data_quality_previous_relationship_invalid
      - data_quality_previous_title_number_invalid
      - data_quality_continued_title_number_invalid
      - data_quality_proprietor_type_invalid
      - data_quality_address_multiple_rdes
      - data_quality_rdes_address_missing
      - data_quality_schedule_address_blank
      - data_quality_no_entry_role_code
      - data_quality_price_paid_amount_missing
      - data_quality_price_paid_date_missing
      - data_quality_price_paid_lower_amount_missing
      - data_quality_price_paid_upper_amount_missing
      - data_quality_price_paid_additional_properties_missing
      - data_quality_alias_name_missing
      - data_quality_proprietor_address_missing
      - data_quality_proprietor_address_description_missing
      - data_quality_proprietor_surname_missing
      - data_quality_proprietor_name_missing
      - data_quality_price_paid_draft_entry_version_unknown
      - data_quality_charge_date_missing
      - data_quality_chargee_missing
      - data_quality_chargee_surname_missing
      - data_quality_chargee_name_missing
      - data_quality_chargee_postal_address_missing
      - data_quality_chargee_address_description_missing
      - data_quality_multiple_charge_on_chargee_entry
      - data_quality_invalid_value_for_covenantor
      - data_quality_covenant_missing_source_type
      - data_quality_incorrect_spelling_of_covenantor
      - data_quality_validation_issue
      - data_quality_incorrect_number_of_infills
      - data_quality_charge_date_mismatch_on_obligation
      - data_quality_obligation_exists_but_no_charge_exists
      - data_quality_charge_date_missing_from_obligation
      - data_quality_charge_date_missing_from_charge_restriction
      - data_quality_charge_party_missing_from_charge_restriction
      - data_quality_charge_missing_for_charge_restriction
      - data_quality_charge_id_missing_for_charge_restriction
      - data_quality_charge_date_missing_from_postponement
      - data_quality_charge_date_mismatch_on_postponement
      - data_quality_postponement_exists_but_no_charge_exists
      - data_quality_postponement_charge_date_infill_number_mismatches_number_of_charges_on_postponement
      - data_quality_multiple_price_paid_entries_exist_but_single_price_paid_expected
      - data_quality_no_interests
      - data_quality_entry_date_missing_from_restriction
      - data_quality_beneficiary_missing_from_notice
      - data_quality_beneficiary_missing_from_charge
      - data_quality_charging_order_type_incorrect_on_equitable_charge
      - data_quality_charging_order_type_missing_from_equitable_charge
      - data_quality_source_parties_missing_from_charge
      - data_quality_expiry_date_missing_from_charge
      - data_quality_incorrect_spelling_of_other_than_a_charge
      - data_quality_invalid_other_than_a_charge_when_not_disposition
      - data_quality_invalid_other_than_a_charge
      - data_quality_missing_charge_id
      - data_quality_impacted_action_corrected
      - data_quality_invalid_impacted_action
      - data_quality_unilateral_notice_missing
      - data_quality_beneficiary_missing_from_unilateral_notice
      - data_quality_notice_date_missing_from_notice
      - data_quality_charge_date_missing_from_notice
      - data_quality_church_missing_from_notice
      - data_quality_deed_parties_missing_from_notice
      - data_quality_deed_type_missing_from_notice
      - data_quality_deed_date_missing_from_notice
      - data_quality_protected_interest_missing_from_notice
      - data_quality_lease_term_missing_or_incomplete_from_notice
      x-enum-description:
      - |
        The data quality code used when a language code is encountered that is not either `ENG` (English) or `CYM` (Welsh).
      - |
        The data quality code used when the class of a title cannot be determined.
      - |
        The data quality code used when the tenure of a title cannot be determined.
      - |
        The data quality code used when the text of a register entry could not be retrieved.
      - |
        The data quality code used when the estate interest of a title cannot be determined.
      - |
        The data quality code used when the class of a title is inapplicable given its tenure.
      - |
        The data quality code used when the sub-register or schedule of a title cannot be determined.
      - |
        The data quality code used when the title has more than one entry with a schedule code of H.
      - |
        The data quality code used when the title has more than one entry with a schedule code of Q.
      - |
        The data quality code used when the timeshare lease code is invalid.
      - |
        The data quality code used when the commonhold type is invalid.
      - |
        The data quality code used when the related title number does not have a corresponding previous title number.
      - |
        The data quality code used when the related title number does not have a corresponding continued title number.
      - |
        The previous title number is invalid.
      - |
        The continued title number is invalid.
      - |
        The proprietor type is invalid.
      - |
        The title has more than one current RDES entry.
      - |
        The title has no address and no schedule exists.
      - |
        The title has a schedule address with a blank property description.
      - |
        This entry does not have a role code.
      - |
        The title has a price paid entry with no amount.
      - |
        The title has a price paid entry with no date.
      - |
        The title has a price paid entry with no lower amount.
      - |
        The title has a price paid entry with no upper amount.
      - |
        The title has a price paid entry with no additional properties information.
      - |
        The title has an alias entry with missing forename and/or surname.
      - |
        The title has a proprietor with no address.
      - |
        The title has a proprietor address with no description.
      - |
        The title has a proprietor with a missing surname.
      - |
        The title has a proprietor with a missing name.
      - |
        The price paid is not present because of a system issue mapping from the source data. The draft entry version for the price paid entry is unknown.
      - |
        The title has a charge that is missing the charge date.
      - |
        The title has a charge that does not have a chargee.
      - |
        The title has a chargee entry with a missing surname.
      - |
        The title has a charge with a chargee that has a missing name.
      - |
        The title has a charge with a chargee that has a missing address.
      - |
        The title has a charge with a chargee that has a missing address description.
      - |
        The title has a chargee entry linked to more than one charge entry.
      - |
        The title has a personal covenant entry with a covenantor that is invalid.
      - |
        Deeds deed_type (personal_covenants source type) is blank.
      - |
        The title has a personal covenant entry with an incorrectly entered.
      - |
        A validation issue was found the the specified entry.
      - |
        Incorrect number of infills provided.
      - |
        The title has an obligation with a charge but the date does not match the date on the charge.
      - |
        The title has an obligation but the related charge information is missing. The LegacyEntryId of the obligation without an associated charge is:
      - |
        The title has an obligation missing the charge date.
      - |
        The title has a charge restriction without a charge date.
      - |
        The title has a charge restriction without a compliance authority which is provided by the charge party.
      - |
        The title has a charge restriction but the related charge is either missing, cancelled or discharged.
      - |
        The title has a charge restriction but the related charge id is missing.
      - |
        The title has a postponement missing a charge date.
      - |
        The title has a postponement with a charge date that does not match the date on the charge.
      - |
        The title has a postponement but the related charge information is missing. The LegacyEntryId of the postponement without an associated charge is:
      - |
        The title has a postponement with multiple charges and relevant data is not held in expected infills.
      - |
        The title has multiple price paid entries but should only have a single entry.
      - |
        Unable to retrieve interests or concerns for title.
      - |
        The title has a restriction missing an entry date.
      - |
        The title has a notice with a missing beneficiary.
      - |
        The title has a charge without an expected beneficiary.
      - |
        The title has an equitable charge with an incorrect charging order type.
      - |
        The title has an equitable charge without a charging order type.
      - |
        The title has a charge missing the party information.
      - |
        The title has a charge without an expiry date.
      - |
        The exemption ‘(other than a charge)’ has incorrect spelling.
      - |
        The exemption ‘(other than a charge)’ can only be included where the impacted action is ‘disposition'.
      - |
        The exemption must be ‘(other than a charge)'.
      - |
        The title has a charge with a missing charge id.
      - |
        The impacted action has an incorrect spelling or contains erroneous characters that cannot be corrected.
      - |
        The impacted action has an incorrect spelling or contains erroneous characters.
      - |
        The title has a beneficary but the corresponding unilateral notice is not present.
      - |
        The title has an entry relating to a unilateral notice but the corresponding beneficiary is not present.
      - |
        The title has a notice missing a notice date.
      - |
        The title has a notice missing a charge date.
      - |
        The title has a notice with a missing named church in the protected interest.
      - |
        The title has a notice with the deed parties missing.
      - |
        The title has a notice with the deed type or agreement type missing.
      - |
        The title has a notice missing a deed date.
      - |
        The title has a notice with the protected interest missing.
      - |
        The title has a notice with the lease term missing or incomplete.
    Title:
      required:
      - application_reference
      - caution_against_first_registration
      - entries
      - prices_paid
      - properties
      - proprietors
      - status
      - title_number
      type: object
      properties:
        previous_title_number:
          maxLength: 9
          type: string
          description: |
            Title number that was previously allocated to a property.
          example: AGL117262
          x-data-quality:
          - tag: data_quality_previous_title_number_invalid
            message: The previous title number is invalid.
        title_number:
          maxLength: 9
          type: string
          description: The unique reference number that refers to this title.
          example: AGL117262
        scheme_status:
          $ref: '#/components/schemas/SchemeStatus'
        continuation_title_number:
          maxLength: 9
          type: string
          description: |
            Title number under which a closed title has been continued.
          example: AGL117262
          x-data-quality:
          - tag: data_quality_continued_title_number_invalid
            message: The continued title number is invalid.
        application_timestamp:
          type: string
          description: |
            The date and time that the latest application to make a substantive change to the register for this title was
            submitted.

            **NB**: This timestamp is provided in UTC, which may mean that it differs by an hour from
            the value found in the Intelligent Register, as it is configured to use BST in the summer months.
          format: date-time
          example: '2011-02-11T13:44:02Z'
        caution_against_first_registration:
          type: boolean
          description: |
            Boolean value stating whether this title is a caution against first registration.
          example: true
        application_reference:
          type: string
          description: |
            The Application Barcode Reference (ABR) of the latest application to make a substantive change to the register
            for this title.
          example: BADD31A
        timeshare_lease_issued:
          type: boolean
          description: |
            Indicates whether a timeshare discontinuous lease has been issued out of this title.
          example: true
          x-data-quality:
          - tag: data_quality_timeshare_lease_code_invalid
            message: The timeshare lease code is invalid.
        prices_paid:
          type: array
          description: Describes the Price Paid or the Value Stated for a Property
          items:
            $ref: '#/components/schemas/PricePaid'
          x-data-quality:
          - tag: data_quality_price_paid_draft_entry_version_unknown
            message: The price paid is not present because of a system issue mapping from the source data. The draft entry version for the price paid entry is unknown.
          - tag: data_quality_multiple_price_paid_entries_exist_but_single_price_paid_expected
            message: The title has multiple price paid entries but should only have a single entry.
        proprietors:
          type: array
          description: The list of proprietors relating to this title.
          items:
            discriminator:
              propertyName: proprietor_type
              mapping:
                private individual: '#/components/schemas/PrivateIndividual'
                organisation: '#/components/schemas/Organisation'
            oneOf:
            - $ref: '#/components/schemas/PrivateIndividual'
            - $ref: '#/components/schemas/Organisation'
            x-force-type: Proprietor
          x-force-type: List<Proprietor>
        district_name:
          maxLength: 38
          type: string
          description: |
            The Name of an administrative district created since local government reorganisation 1974.
            Administrative district also covers the London boroughs, unitary authorities and for (HMLR’s purposes) the Isles of Scilly parishes which encompasses the extent of the title.
            A Title extent can occur over multiple districts but currently only the main primary district is being surfaced. Multiple districts will be available in later releases of data.
          example: STRATFORD-ON-AVON
        entries:
          type: array
          description: The list of current entries on the register for this title.
          items:
            $ref: '#/components/schemas/RegisterEntry'
          x-data-quality:
          - tag: data_quality_schedule_code_invalid
            message: Ordering of entries failed due to an invalid schedule code.
          - tag: data_quality_multiple_h_schedules
            message: The title has more than one entry with a schedule code of H.
          - tag: data_quality_multiple_q_schedules
            message: The title has more than one entry with a schedule code of Q.
        pre_act_caution:
          type: boolean
          description: |
            Boolean value stating whether a caution against first registration was lodged prior to the LR Act 2002.
            This is only applicable for titles identified as cautions against first registration - caution_against_first_registration is true.
          example: true
        edition_date:
          type: string
          description: |
            The date on which the current version of the register was published.
          format: date
        estate_interest:
          $ref: '#/components/schemas/EstateInterest'
        properties:
          type: array
          description: The list of properties relating to this title.
          items:
            $ref: '#/components/schemas/Property'
          x-data-quality:
          - tag: data_quality_address_multiple_rdes
            message: The title has more than one current RDES entry.
          - tag: data_quality_rdes_address_missing
            message: The title has no address and no schedule exists.
        class_of_title:
          $ref: '#/components/schemas/ClassOfTitle'
        tenure:
          $ref: '#/components/schemas/Tenure'
        commonhold_type:
          $ref: '#/components/schemas/CommonholdType'
        developer_status:
          $ref: '#/components/schemas/DeveloperStatus'
        status:
          $ref: '#/components/schemas/TitleStatusInfo'
      description: |
        Represents a title for land or property.
    Tenure:
      type: string
      description: "The tenure of a title determines the rights of that title's proprietor(s).\n\
        \nCurrently, the law in England and Wales permits two kinds of interest: *freehold*\
        \ and *leasehold*.\n\n\n---\n\nA property of this type may be any of the following\
        \ values:\n- `freehold`: Indicates that this is a freehold title; i.e. that\
        \ full, perpetual, ownership rights of the specified property and\n  land\
        \ are granted to the proprietor(s).\n  \n- `leasehold`: Indicates that this\
        \ is a leasehold title; i.e. that possessory rights of the property (but not\
        \ the land) have been\n  granted to the proprietor(s) for the duration of\
        \ the lease agreement with the freeholder(s).\n  "
      example: freehold
      enum:
      - freehold
      - leasehold
      x-enum-descriptions:
      - |
        Indicates that this is a freehold title; i.e. that full, perpetual, ownership rights of the specified property and
        land are granted to the proprietor(s).
      - |
        Indicates that this is a leasehold title; i.e. that possessory rights of the property (but not the land) have been
        granted to the proprietor(s) for the duration of the lease agreement with the freeholder(s).
    ClassOfTitle:
      type: string
      description: "The *class of title* is a measure of confidence that HM Land Registry\
        \ has in guaranteeing the proprietor(s) of the\ntitle against a legal challenge\
        \ to that title.\n\n\n---\n\nA property of this type may be any of the following\
        \ values:\n- `

# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hm-land-registry/refs/heads/main/openapi/hm-land-registry-land-register-api-openapi.yml