HM Land Registry Draft Titles API

openapi: 3.2.0
info:
  title: Land Register Draft Titles API
  description: "The Land Register API aims to be the primary method of accessing register data for HM Land Registry.\n\nThe Land Register API provides data and services around the core data set.\nAccess to the API must be requested through the Digital Register project team.\nIf you would like to integrate systems with the Land Register API then please follow these steps:\n-  Contact the project team about your needs to ensure that the API can serve them.\n-  Create your own client for accessing the API, only returning the data you are using.\n-  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.\n-  Send your access token in the 'Authorization' header of each call to the API. e.g. replace 'abc123' in:\n  `curl --header 'Authorization: Bearer abc123' --url ...`\n-  Add to your Fraud Impact Assessment form that you will be accessing the Land Register API, the reasons why it is\n  needed and the specific data that is required.\n-  Ensure that the data that is requested by your systems from the API is limited to only the data that you need.\n-  Do NOT directly expose the data to external sources.\n-  Application_timestamp will be returned as a UTC timezone, as such will NOT match exactly how it is stored within legacy databases.\n\nThe Digital Register project team and Counter Fraud team are available to support you through this process.\n"
  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: draft-titles
paths:
  /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:
    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
    Interests:
      type: object
      properties:
        notices:
          type: array
          description: The list of enhanced notices for the title
          items:
            $ref: '#/components/schemas/Notice'
        covenants:
          $ref: '#/components/schemas/Interests_covenants'
        charges:
          type: array
          description: 'The list of charges for the title. The charges are listed in the order they appear in the register and the priority

            will need to be determined by inspecting the charges themselves.

            '
          items:
            anyOf:
            - $ref: '#/components/schemas/RegisteredCharge'
            - $ref: '#/components/schemas/EquitableCharge'
            x-force-type: Charge
          x-force-type: List<Charge>
        restrictions:
          type: array
          description: List of restrictions against the title
          items:
            $ref: '#/components/schemas/Restriction'
      description: The list of interests on the title
    ValidationError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - required:
        - validation_issues
        type: object
        properties:
          validation_issues:
            type: array
            items:
              $ref: '#/components/schemas/ValidationIssue'
        description: 'Returned when a request body contains invalid property values.

          '
    ValidationIssue:
      required:
      - message
      - property_name
      type: object
      properties:
        message:
          type: string
          description: A message summarising why this property failed to validate.
          example: The ID cannot be null.
        type:
          $ref: '#/components/schemas/ValidationIssueType'
        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 encountered while validating a property on a request body.

        '
    PrivateIndividualAlias:
      required:
      - legacy_name_id
      type: object
      properties:
        sequence:
          minimum: 1
          type: integer
          description: 'The position of the alias within the list. Proprietor and alias lists are sequenced separately.

            '
          format: int32
          example: 3
        decor:
          type: string
          description: Text which contains the details of any decoration and/or title held by a private individual. e.g. 'OBE','GC', 'KCMG'. For those private individuals holding titles such as 'Duke of ...', 'Lord' etc., the particulars of such titles will be held in this field.
          example: OBE
        surname:
          type: string
          example: Smith
        name:
          type: string
          description: Full name of the individual.
          example: Mrs Sarah Louise Smith OBE
          x-data-quality:
          - tag: data_quality_alias_name_missing
            message: The title has an alias entry with missing forename and/or surname.
        legacy_name_id:
          type: string
          description: 'The legacy identifier for the alias.

            '
          example: 2015-03-31-15.25.12.037850
        title:
          type: string
          example: Mrs
        forenames:
          type: string
          example: Sarah Louise
      description: 'An additional name, referred to in the register, that a private individual sometimes uses or is also known as.

        '
    Authority:
      type: object
      properties:
        authority:
          type: string
          description: Name of the compliance authority
          example: Joe Bloggs
        description:
          type: string
          description: Description of the compliance authority
          example: conveyancer
      description: 'The person or organisation, or a description of the appropriate party, that can provide evidence of compliance with the terms of an interest

        '
    SubRegister:
      type: string
      description: 'A single-character code that identifies in which part of the register an entry resides.


        The subregister code may be any of the following values:

        - `A`: the entry is part of the property register

        - `B`: the entry is part of the proprietorship register

        - `C`: the entry is part of the charges register

        '
      example: A
      enum:
      - A
      - B
      - C
    Notice:
      required:
      - legacy_entry_ids
      type: object
      properties:
        protected_interests:
          minItems: 1
          type: array
          description: 'Text which describes the protected interest of a legal interest.

            '
          example: agreement for sale
          items:
            type: string
          x-data-quality:
          - tag: data_quality_church_missing_from_notice
            message: The title has a notice with a missing named church in the protected interest.
          - tag: data_quality_protected_interest_missing_from_notice
            message: The title has a notice with the protected interest missing.
        additional_considerations:
          type: array
          description: 'When information is provided or is missing which prevents the automation of the application/order because either

            referral to Practice Guidance or some other manual intervention is required, then a note will be added explaining

            the need for additional consideration. It may contain text to explain why a notice cannot be fully structured and

            therefore may not be suitable for automatic processing.

            '
          items:
            type: string
            example: Check practice guidance for the latest applicable charities act
        notes:
          type: array
          description: The list of notes associated with the notice.
          items:
            type: string
            example: copy filed
        sources:
          type: array
          description: The documents, deeds or other means by which the interest has been created.
          items:
            $ref: '#/components/schemas/Source'
        expiry_condition:
          type: string
          description: Text which describes the expiry condition for the legal interest.
          example: and exercisable within a period of 20 years from 2 January 2004
        subject:
          type: string
          description: Text which describes the subject or prime consideration of a legal interest.
          example: registered estate
        parish_church:
          type: string
          description: The name of a parish church affected by a unilateral notice in respect of the repair of a church chancel. This will only be populated where the protected interest is ‘the liability to repair the chancel of’.
          example: The Church of the Holy Mary
        notice_type:
          type: string
          description: Classification of a notice.
          enum:
          - agreed notice
          - crown rent notice
          - death duty notice
          - home rights notice
          - section 49 notice
          - unilateral notice
          - unknown
        legacy_entry_ids:
          minItems: 1
          type: array
          description: 'The unique identifier for this entry as used by the legacy database.

            The `entry_date` associated with a `legacy_entry_id` is stored in the corrosponding

            index posistion within the `entry_dates` array. For example, the first `legacy_entry_id`

            relates to the first entry_date.

            '
          example: 2019-11-18 12.52.12.555232
          items:
            type: string
        notice_date:
          type: string
          description: The date of the unilateral notice.
          example: 2020/01/31
          x-data-quality:
          - tag: data_quality_notice_date_missing_from_notice
            message: The title has a notice missing a notice date.
        lease_term:
          type: string
          description: The period of time during which a tenant holds an interest in land.
          example: 5 years from 2020-01-20
          x-data-quality:
          - tag: data_quality_lease_term_missing_from_notice
            message: The title has a notice with the lease term missing or incomplete.
        served_by:
          type: string
          description: The name of the person or organisation that has served the unilateral notice on the registered proprietor on behalf of the beneficiary.
          example: John Smith
        entry_dates:
          type: array
          description: 'The date(s) on which the entries were added to the register.

            The `legacy_entry_id` associated with an `entry_date` is stored in the corrosponding

            index posistion within the `legacy_entry_ids` array. For example, the first `entry_date`

            relates to the first `legacy_entry_id`.

            '
          items:
            type: string
            format: date
        beneficiaries:
          type: array
          description: 'The names of the private individuals and/or organisations who will benefit from the legal interest.

            '
          example: whole
          items:
            type: string
          x-data-quality:
          - tag: data_quality_beneficiary_missing_from_notice
            message: The title has a notice with a missing beneficiary.
        statute:
          type: string
          description: A law enacted by the legislative branch of a government.
          example: Section 42 of the Leasehold Reform, Housing and Urban Development Act 1993
        object:
          type: string
          description: 'Text which describes the object or defined extent of a legal interest.

            For home rights there might be a note giving extent limitations i.e. stating

            that home rights only applies to part of the estate.   When this note is available ''object''

            will be set to null, otherwise it will always be set to “whole”.

            '
          example: whole
      description: 'Entry in the register representing a burden of interest affecting a registered estate or charge.

        For home rights notices, only Home Rights/Matrimonial Homes (RMHA role code) entries will have

        structured fields present (e.g., notice date, object, and entry date). Home rights contained in

        cautions, land charges or provided as free format will only have a legacy entry id present.

        For unilateral notices the notice and beneficiary will appear as a single Notice but

        there will be two legacy_entry_id values and two entry_date values with the first belonging to

        the unilateral notice and the second to the beneficiary.

        '
      x-data-quality:
      - tag: data_quality_unilateral_notice_missing
        message: The title has a beneficary but the corresponding unilateral notice is not present.
      - tag: data_quality_beneficiary_missing_from_unilateral_notice
        message: The title has an entry relating to a unilateral notice but the corresponding beneficiary is not present.
    PricePaidDate:
      required:
      - description
      type: object
      properties:
        description:
          type: string
          description: 'This will be the textual representation of the date as entered on the item.

            If a specific date is provided then it could either be in long date format eg: 1 March 2016

            or in short date format eg: 01/03/2016.

            If there is no specific date then this can be a description from the item such as "on the date the lease was granted".

            If a date is expected but is missing then a data quality issue of data_quality_price_paid_date_missing

            is issued and date is set to null.

            '
          example: 6 March 2020
        value:
          type: string
          description: 'The structured date if applicable.

            '
          format: date
      description: 'For price paid this is the date of the deed from which the price paid was taken. For value stated,

        this is the date of the application that gave rise to the entry on the register.

        A date will not be available on some lease entries.

        '
    Source:
      type: object
      properties:
        date:
          type: string
          description: The date of the document, deed or other means in which the interest was contained.
          format: date
          x-data-quality:
          - tag: data_quality_deed_date_missing_from_notice
            message: The title has a notice missing a deed date.
          - tag: data_quality_charge_date_missing_from_notice
            message: The title has a notice missing a charge date.
        parties:
          type: array
          description: The parties to the document, deed or other means by which the interest has been created.
          items:
            $ref: '#/components/schemas/Party'
          x-data-quality:
          - tag: data_quality_deed_parties_missing_from_notice
            message: The title has a notice with the deed parties missing.
        type:
          type: string
          description: The type of document, deed or other means by which the interest has been created.
          example: Conveyance
          x-data-quality:
          - tag: data_quality_deed_type_missing_from_notice
            message: The title has a notice with the deed type or arrangement type missing.
      description: 'Details about a document, deed or other means by which the interest has been created.

        '
    AmountRange:
      allOf:
      - $ref: '#/components/schemas/Amount'
      - required:
        - amount_type
        type: object
        properties:
          lower_description:
            type: string
            description: 'The lower amount stated when a range of amounts has been entered.

              If the amount stated was "Under £100,000" this will appear as the upper amount

              and lower amount is set to null. If the lower amount expected is missing

              then a data quality issue of data_quality_price_paid_amount_missing is

              issued and amount is set to null, neither upper or lower amounts will be available

              if a data quality issue is raised.

              '
            example: £100,001
          upper_description:
            type: string
            description: 'The upper amount stated when a range of amounts has been entered.

              If the amount stated was "Over £100,000,000" then this will appear as the lower amount

              and upper value is set to null. If the upper amount expected is missing

              then a data quality issue of data_quality_price_paid_amount_missing is

              issued and amount is set to null, neither upper or lower amounts will

              be available if a data quality issue is raised.

              '
            example: £200,000
          amount_type:
            type: string
            enum:
            - amount range
      x-discriminator-value: amount range
    AmountSingle:
      allOf:
      - $ref: '#/components/schemas/Amount'
      - required:
        - amount_type
        type: object
        properties:
          description:
            type: string
            description: 'The price paid or value stated amount including currency.

              This amount can also include information regarding inclusion

              or exclusion of a VAT element. It will also include entries

              such as "under £100,000", "over £1,000,000" and

              "between ''amount1'' and ''amount2''" where these are

              held as single descriptions. If an expected amount

              is missing then a data quality issue of

              data_quality_price_paid_amount_missing is issued

              and amount is set to null.

              '
            example: £120,000
          amount_type:
            type: string
            enum:
            - single amount
      x-discriminator-value: single amount
    CompanyLocation:
      type: string
      description: 'The geographical location of the organisation.

        A value of ''overseas'' includes the Isle of Man and the Channel Islands.

        '
      example: england or wales
      enum:
      - england or wales
      - scotland
      - northern ireland
      - overseas
    Exemption:
      type: object
      properties:
        context:
          type: string
          description: The context in which the exemption applies
          example: action
        exemption:
          type: string
          description: Text which describes the circumstances in which the interest does not apply
          example: other than a charge
      description: 'The circumstances in which the conditions of an interest do not apply

        '
    Party:
      type: object
      properties:
        names:
          type: array
          description: The full name of a private individual or organisation within a party.
          example: Joe Blogs
          items:
            type: string
        role:
          type: string
          description: The relationship of the party to the source.
          example: lendor
      description: One or more private individuals and/or organisations that have the same role in a legal transaction.
    LanguageCode:
      type: string
      description: 'A three-character code representing a language according to the

        [ISO 639-3 standard](https://iso639-3.sil.org/code_tables/639/data).

        '
      example: eng
      enum:
      - eng
      - cym
    Amount:
      required:
      - amount_type
      type: object
      properties:
        amount_type:
          type: string
          description: 'Coarse classification of an amount. Used to easily distinguish between a single amount or a range of amounts

            '
          enum:
          - single amount
          - amount range
      discriminator:
        propertyName: amount_type
    DeveloperStatus:
      type: string
      description: "Any title which is part of a developing estate is identified as such as early as\npossible by the use of the developer status and this ensures that all titles within\na plot can be managed in the same way providing an efficient process and improved\ncustomer experience.\nThe developer status can be added and removed without an application being raised.\nWhen developer status is added the status is 'currently a developing title'\nand on removal of developer status it changes to 'previously a developing title'.\nIf the title is not part of a developing estate then the status will\nbe set to 'title is not a developing title'.\nA title that is a developing title can also have a title status of 'pending new title'.\n\n\n---\n\nA property of this type may be any of the following values:\n- `currently a developing title`: Currently a developing title\n  \n- `previously a developing title`: Previously a developing title\n  \n- `title is not a developing title`: Title is not a developing title\n  "
      example: currently a developing title
      enum:
      - currently a developing title
      - previously a developing title
      - title is not a developing title
      x-enum-descriptions:
      - 'Currently a developing title

        '
      - 'Previously a developing title

        '
      - 'Title is not a developing title

        '
    OrganisationType:
      type: string
      description: 'Fine-grained classification of an organisation.

        '
      example: corporate body
      enum:
      - private individual
      - limited company or public limited company
      - county council
      - local authority
      - corporate body
      - industrial and provident society (company)
      - industrial and provident society (corporate body)
      - unknown (used for customer names only)
      - unlimited company
      - limited liability partnership
      - housing association/society (company)
      - housing association/society (corporate body)
      - official custodian for charities
      - official custodian for charities (on behalf of trustees)
      - co-operative society (company)
      - co-operative society (corporate body)
      - community benefit society (company)
      - community benefit society (corporate body)
      - registered society (company)
      - registered society (corporate body)
      - housing association co-operative society (company)
      - housing association co-operative society (corporate body)
      - housing association community benefit society (company)
      - housing association community benefit society (corporate body)
      - housing association registered society (company)
      - housing association registered society (corporate body)
      - unknown (proprietor has no IOPN delimiters)
    PrivateIndividual:
      required:
      - proprietor_type
      properties:
        aliases:
          type: array
          description: The list of aliases relating to this private individual.
          items:
            $ref: '#/components/schemas/PrivateIndividualAlias'
        proprietor_type:
          type: string
          description: Classification of a proprietor to distinguish between a private individual and an organisation.
          enum:
          - private individual
      description: 'Proprietor details for a private individual.

        '
      allOf:
      - $ref: '#/components/schemas/Proprietor'
      - $ref: '#/components/schemas/PrivateIndividualName'
      x-discriminator-value: private individual
    Proprietor:
      type: object
      properties:
        sequence:
          minimum: 1
          type: integer
          description: 'The position of the proprietor within the list.

            '
          format: int32
          example: 1
        addresses:
          type: array
          description: 'The list of addresses relating to this proprietor. These addresses are used for serving notices,

            notifications or other communications by HM Land Registry staff.

            '
          items:
            $ref: '#/components/schemas/ProprietorAddress'
          x-data-quality:
          - tag: data_quality_proprietor_address_missing
            message: The title has a proprietor with no address.
        legacy_name_id:
          type: string
          description: 'The legacy identifier for the proprietor name.

            '
          example: 2015-03-31-15.25.12.037850
      description: 'The legal owner of the land or charge.

        '
      discriminator:
        propertyName: proprietor_type
        mapping:
          private individual: '#/components/schemas/PrivateIndividual'
          organisation: '#/components/schemas/Organisation'
    ProprietorAddress:
      type: object
      properties:
        building_name:
          type: string
          description: 'Name of residential or commercial premise.


            The building name is a description applied to a single building or a small group of buildings, such as Highfield

            House. This also includes those building numbers that contain non-numeric characters, such as 44A.

            Some descriptive names, when included with the rest of the address, are sufficient to identify the property

            uniquely and unambiguously, for example, MAGISTRATES COURT.


            Sometimes the building name will be a blend of distinctive and descriptive naming, for example, RAILWAY

            TAVERN (PUBLIC HOUSE) or THE COURT ROYAL (HOTEL).


            The building number will be shown in this field when it contains a range, decimal or non-numeric character

            (see Building Number field).


            Condition:

            Building Name must be present if Organisation Name, Building Number and PO Box Number are not present


            `Legacy DB Mapping (table / column): T_ADDR_INFO_WORK / HOUSE_DESC`

            '
          example: ABBEY COURT
        double_dependent_locality:
          type: string
          description: 'This is used to distinguish between similar thoroughfares or the same thoroughfare within a dependent

            locality.


            For example, Millbrook Industrial Estate and Cranford Estate in this situation: BRUNEL WAY,

            MILLBROOK INDUSTRIAL ESTATE, MILLBROOK, SOUTHAMPTON and BRUNEL WAY, CRANFORD ESTATE,

            MILLBROOK, SOUTHAMPTON.


            Condition:

            If a Double Dependent Locality is present, a Dependent Locality must also be present.


            `Legacy DB Mapping (table / column): T_ADDR_INFO_WORK / LOCAL_NAME_2`

            '
          example: MATFORD BUSINESS PARK
        postcode:
          type: string
          description: 'A postcode is an abbreviated form of address made up of combinations of between five and seven

            alphanumeric characters. These are used by Royal Mail to help with the automated sorting of mail. A postcode

            may cover between 1 and 100 addresses.


            There are two main components of a postcode, for example, NW6 4DP:


            * The outward code (or ‘outcode’). The first two–four characters of the postcode constituting the postcode

            area and the postcode district, for example, NW6. It is the part of the postcode that enables mail to be sent

            from th

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