openapi: 3.0.0
servers:
  - url: 'https://bgtest.landregistry.gov.uk/api/deeds'
  - url: /v1
info:
  title: Deed API
  description: Land Registry Deed API
  version: 2.3.1
paths:
  /deed/:
    post:
      summary: Deed
      operationId: addDeed
      description: |-
        The post Deed endpoint creates a new deed based on the JSON provided.
         The reponse will return a URL that can retrieve the created deed.
         > REQUIRED: Land Registry system requests Conveyancer to confirm that the Borrowers identity has been established in accordance with Section 111 of the Network Access Agreement.
      responses:
        '201':
          description: |
            A URL to the GET endpoint for the deed returned on successful creation.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: |
            Bad Request due to invalid schema. Response will include 1 or more schema errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deed_create_error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Deed_Application'
        required: true
  '/deed/{deed_reference}':
    get:
      summary: Deed
      description: |
        The Deed endpoint returns details of a specific deed based on the unique deed reference.
        The response includes the Title Number, Property information, Borrower(s) information and deed information.
      parameters:
        - name: deed_reference
          in: path
          description: Unique reference of the deed.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: Pass application/json for the deed as JSON or application/pdf to get a pdf
          required: true
          schema:
            type: string
      tags:
        - Deed
      responses:
        '200':
          description: |
            A specific deed is returned in Operative Deed Format (application/json header). If the application/pdf header is given instead. This will return a PDF Document of the requested Deed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operative_Deed'
            application/pdf:
              schema:
                $ref: '#/components/schemas/Operative_Deed'
        '404':
          description: Deed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deed_not_found'
            application/pdf:
              schema:
                $ref: '#/components/schemas/deed_not_found'
        '410':
          description: Deed found but permanently removed. this is the expected result when obtaining a PDF of a deed with the status of TERMINATED or EXPIRED
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/deed_found_but_removed'
  /deed/retrieve-signed:
    get:
      summary: Retrieves ALL-SIGNED deed(s).
      description: |
        The Retrieve Signed endpoint checks the service for all deeds that have been completely signed by the borrowers or borrower. Only the deeds associated with the conveyancer are returned.
        The response is a json array output containing the deed references e.g. 93e806ab-f1bc-4671-be3e-4cc68b21b77a.
      tags:
        - Retrieve all signed deeds
      responses:
        '200':
          description: ALL-SIGNED deeds are returned.
          content:
            application/json:
              schema:
                type: string
        '404':
          description: No deed found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deed_not_found'
  /deed/in-progress:
    get:
      summary: Retrieves deed(s) that are in-progress.
      description: |
        Retrieves deed(s) that have a status of DRAFT, PARTIALLY_SIGNED or ALL_SIGNED.Only the deeds associated with the conveyancer are returned.
        The response is a json array containing a json object for each deed that is in progress, this will contain the deed reference, expiry date, identity checked status and borrowers array. The borrowers array will contain a list of borrowers related to the deed and will contain the surname, firstname and signature status.
        If none are found, returns ‘There are currently no in-progress deeds’.
      tags:
        - Retrieve in progress deeds
      responses:
        '200':
          description: Any deed(s) that are in-progress are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/In_Progress_Deed'
  '/deed/{deed_reference}/make-effective':
    post:
      summary: Make Effective
      description: |
        The Make Effective endpoint triggers the service to make a deed effective, dating it with the timestamp of when this call is made.
        The response includes the Title Number, Property information, Borrower(s) information and deed information, as well as the timestamp that is saved onto the deed.
        This will accept deeds that have a status of ALL-SIGNED or NOT-LR-SIGNED.
      parameters:
        - name: deed_reference
          in: path
          description: Unique reference of the deed.
          required: true
          schema:
            type: string
      tags:
        - Make Effective
      responses:
        '200':
          description: A URL to the GET endpoint for the deed returned on successful.
        '400':
          description: |-
            One or more errors have been detected. A list of which should accompany this response.
             This is most likely to occur if the deed has already been made effective, or if not all borrowers have signed the deed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deed_effective_error'
        '404':
          description: Deed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deed_not_found'
  '/deed/{deed_reference}/terminate-deed':
    patch:
      summary: 'This endpoint sets a deed status to TERMINATED or EXPIRED if called by a polling job, and removes personal data'
      description: This PATCH endpoint will set the status of the incoming deed to TERMINATED or EXPIRED and will remove any personal data associated with the deed.
      tags:
        - Terminate deed
      parameters:
        - name: deed_reference
          in: path
          description: Unique reference of the deed.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            A URL to the GET endpoint for the deed returned on successful termination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/path_response'
        '400':
          description: |
            Bad request returned when terminating deed
          content:
            application/json:
              schema:
                type: string
                example:
                  message: '<organisation> failed to terminate deed: <deed_reference>'
        '401':
          description: |
            A message stating that deed termination has failed
          content:
            application/json:
              schema:
                type: string
                example:
                  message: 'Failed to terminate deed for reference: <deed_reference>'
        '404':
          description: A message stating that the deed reference is not valid.
          content:
            application/json:
              schema:
                type: string
                example:
                  message: deed reference <deed_reference> is not valid
  '/deed/{deed_reference}/extend-deed':
    patch:
      summary: This endpoint adds ninety days to the current expiry date of a deed if it meets the criteria of being within ninety days of expiry
      description: This PATCH endpoint will add ninety days to the current expiry date of the deed if it meets the criteria of being within ninety days of expiry
      tags:
        - Extend deed
      parameters:
        - name: deed_reference
          in: path
          description: Unique reference of the deed.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            A URL to the GET endpoint for the deed returned on successful extension.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/path_response'
        '400':
          description: |
            Bad request returned when extending deed
          content:
            application/json:
              schema:
                type: string
                example: Failed to extend deed <deed_reference>. Deed does not meet criteria for extension.
        '401':
          description: |
            A message stating that deed extension has failed
          content:
            application/json:
              schema:
                type: string
                example:
                  message: 'Failed to extend deed for reference: <deed_reference>'
        '403':
          description: A message stating that the deed cannot be extended.
          content:
            application/json:
              schema:
                type: string
                example:
                  message: This deed cannot be extended
        '404':
          description: A message stating that the deed reference is not valid.
          content:
            application/json:
              schema:
                type: string
                example:
                  message: deed reference <deed_reference> is not valid
  '/deed/{deed_reference}/identity-checks':
    patch:
      summary: Identity Checks
      description: |-
        The PATCH endpoint compares the borrower information provided with that on the deed.
         If it matches it marks the checks as complete.
         The reponse will return a URL that can retrieve the updated deed.
         > REQUIRED: By calling this endpoint you are confirming that the Borrowers identity has been established in accordance with Section 111 of the Network Access Agreement.
      tags:
        - Identity Checks
      parameters:
        - name: deed_reference
          in: path
          description: Unique reference of the deed.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            A URL to the GET endpoint for the deed returned on success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/path_response'
        '400':
          description: |
            Bad Request due to invalid schema or check failure. Response will include 1 or more errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/id_checks_error'
        '404':
          description: Deed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deed_not_found'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Identity_Payload'
        required: true
components:
  schemas:
    Borrower:
      type: object
      required:
        - surname
        - forename
        - id
        - token
      properties:
        forename:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        middle_name:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        surname:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        token:
          type: string
          description: Borrower token for accessing Borrower Frontend.
          pattern: '^([a-zA-Z0-9]{8})$'
        id:
          type: integer
          description: Unique borrower ID.
          pattern: '^[0-9]+$'
        signature:
          description: Date and time the signature was applied.
          type: string
    InProgressIndividualName:
      type: object
      properties:
        id:
          type: integer
        forename:
          type: string
        middle_name:
          type: string
        surname:
          type: string
        signature:
          type: string
          enum:
            - 'Y'
            - 'N'
    PrivateIndividualName:
      type: object
      additionalProperties: false
      required:
        - surname
        - forename
        - dob
        - phone_number
        - address
      properties:
        forename:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        middle_name:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        surname:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        dob:
          type: string
          pattern: '^(0[1-9]|[12][0-9]|3[01])[\/](0[1-9]|1[012])[\/]\d{4}$'
        gender:
          type: string
          enum:
            - Male
            - Female
            - Not Specified
        phone_number:
          type: string
          pattern: '^(07[\d]{9})$'
        address:
          type: string
          pattern: '^(?!\s*$)((?![<>&#]).)+$'
    IdChecksPrivateIndividual:
      type: object
      additionalProperties: false
      required:
        - id
        - forename
        - surname
        - dob
        - address
      properties:
        id:
          type: integer
        forename:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        middle_name:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        surname:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
        dob:
          type: string
          pattern: '^(0[1-9]|[12][0-9]|3[01])[\/](0[1-9]|1[012])[\/]\d{4}$'
        address:
          type: string
          pattern: '^(?!\s*$)((?![<>&#]).)+$'
    ChargeClause:
      type: object
      properties:
        description:
          type: string
    AdditionalProvisions:
      type: array
      minItems: 0
      items:
        type: object
        properties:
          additional_provision_code:
            type: string
          description:
            type: string
    Lender:
      type: object
      properties:
        address:
          type: string
        name:
          type: string
        description:
          type: string
    OpBorrowers:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Borrower'
    Borrowers:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/PrivateIndividualName'
    InProgressBorrowers:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/InProgressIndividualName'
    IdBorrowers:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/IdChecksPrivateIndividual'
    In_Progress_Deed_Empty:
      type: object
      properties:
        message:
          type: string
          description: A message stating why no in-progress deeds were returned
          example: There are currently no in-progress deeds
    In_Progress_Deed:
      type: object
      properties:
        status:
          type: string
          description: Current state of the deed
        token:
          type: string
          description: The ID of the deed
        expiry_date:
          type: string
          description: This is a timestamp representing when the deed will expire if no further interactions with the deed have taken place.
        identity_checked:
          type: string
          description: Flag showing if the identity checks have been performed for this deed
          enum:
            - 'Y'
            - 'N'
        borrowers:
          $ref: '#/components/schemas/InProgressBorrowers'
    Operative_Deed:
      type: object
      properties:
        deed:
          type: object
          description: 'Unique deed, consisting of property, borrower and charge information as well as clauses for the deed.'
          properties:
            title_number:
              type: string
              description: Unique Land Registry identifier for the registered estate.
            md_ref:
              type: string
              description: Land Registry assigned number for a Mortgage Deed (MD). If you wish to use an existing MD reference please prefix it with e- to comply with our system (eg e-MD12345)
            borrowers:
              $ref: '#/components/schemas/OpBorrowers'
            charge_clause:
              $ref: '#/components/schemas/ChargeClause'
            additional_provisions:
              $ref: '#/components/schemas/AdditionalProvisions'
            lender:
              $ref: '#/components/schemas/Lender'
            effective_clause:
              type: string
              description: Text to display the make effective clause
            property_address:
              type: string
              description: 'The address of property that the deed relates. This should be supplied in a comma separated format e.g. 30 wakefield rd, plymouth, PL6 3WA'
            reference:
              type: string
              maxLength: 50
              pattern: ^(?!\s*$)((?![<>&#]).)+$
              description: A conveyancer reference.  Can be displayed on the deed if the mortgage document template permits.
            date_of_mortgage_offer:
              type: string
              maxLength: 50
              pattern: ^(?!\s*$)((?![<>&#]).)+$
              description: Date that the mortgage offer was made.  Can be displayed on the deed if the mortgage document template permits.
            deed_status:
              type: string
              description: Current state of the deed
            token:
              type: string
              description: The ID of the deed
            effective_date:
              type: string
              description: An effective date is shown if the deed is made effective
            identity_checked:
              type: string
              description: Flag showing if the identity checks have been performed for this deed
              enum:
                - 'Y'
                - 'N'
            proxy_organisation_name:
              type: string
              description: 'The name of the proxy organisation that will be given permission to perform actions, such as creating or getting a deed.'
    Identity_Payload:
      type: object
      required:
        - borrowers
      properties:
        borrowers:
          $ref: '#/components/schemas/IdBorrowers'
    Deed_Application:
      type: object
      required:
        - title_number
        - borrowers
        - md_ref
        - identity_checked
        - property_address
      properties:
        title_number:
          type: string
          pattern: '^([A-Z]{0,3}[1-9][0-9]{0,5}|[A-Z]{1,3}[1-9][0-9]{0,3}[Z])$'
        borrowers:
          $ref: '#/components/schemas/Borrowers'
        md_ref:
          pattern: '^e-MD([0-9]{5}|([0-9]{3,4}[A-Z]{1}))$'
          type: string
        identity_checked:
          pattern: '^[Y|N]$'
          type: string
        is_second_charge:
          pattern: '^[Y|N]$'
          type: string
          description: This is to confirm whether or not this will be for a second charge.
        property_address:
          pattern: ^((?![<>&#]).)*[A-Z]{1,2}[0-9R][0-9A-Z]? [0-9](?:[AB]|[D-H]|[JLN]|[P-U]|[W-Z]){2}$
          type: string
          description: 'The address of property that the deed relates. This should be supplied in a comma separated format e.g. 30 wakefield rd, plymouth, PL6 3WA'
        reference:
          type: string
          maxLength: 50
          pattern: ^(?!\s*$)((?![<>&#]).)+$
          description: A conveyancer reference.  Can be displayed on the deed if the mortgage document template permits.
        date_of_mortgage_offer:
          type: string
          maxLength: 50
          pattern: ^(?!\s*$)((?![<>&#]).)+$
          description: Date that the mortgage offer was made.  Can be displayed on the deed if the mortgage document template permits.
        deed_effector:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
          description: Name of the legal deed effector. To be used where the legal deed effector name is different to that of the conveyancer.
        proxy_organisation_name:
          type: string
          pattern: ^(?!\s*$)((?![<>&#]).)+$
          description: 'The name of the proxy organisation that will be given permission to perform actions, such as creating or getting a deed.'
    deed_not_found:
      title: The format of errors returned when attempting to get a deed
      type: object
      properties:
        message:
          type: string
          example: deed not found error
    deed_found_but_removed:
      title: The format of errors returned when attempting to get a deed in PDF form
      type: object
      properties:
        message:
          type: string
          example: 'The deed you requested has been found but has been permanently removed and has a status of: TERMINATED'
    deed_create_error:
      title: The format of errors returned when attempting to create a deed
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          example:
            - Schema errors
            - Title Validation Error
            - Invalid request for the provided title
    deed_effective_error:
      title: The format of errors returned when attempting to make a deed effective
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          example:
            - error
            - make effective error
    id_checks_error:
      title: The format of errors returned when attempting to complete identity checks
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          example:
            - error
            - an id check error
    path_response:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          example: /deed/e643f282-0ef0-453e-a395-60ec890e1072