HM Land Registry ECD API

openapi: 3.2.0
info:
  title: Estimate Completion Date ECD API
  description: A specification for the HMLR Business Gateway estimate completion date service.
  version: 1.0.0
servers:
- url: https://businessgateway.landregistry.gov.uk/bg2/api
  description: Live endpoint
- url: https://bgtest.landregistry.gov.uk/bg2test/api
  description: Customer Test Endpoint
security:
- basicAuth: []
tags:
- name: ECD
paths:
  /v1/applications/{application_reference}/estimate-completion-date:
    get:
      operationId: getEstimateCompletionDate
      tags:
      - ECD
      summary: Get estimate completion date of associated application reference
      description: Get estimated completion date for register create/update applications associated to application reference.
      parameters:
      - $ref: '#/components/parameters/ApplicationReferenceParameter'
      responses:
        '200':
          description: Successfully retrieved the application estimate completion date
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/ECDResponseData'
              examples:
                'Example: Application reference valid, application is received. ECD is available.':
                  value:
                    data:
                      application_reference: X000XXX
                      application_status: RECEIVED
                      application_priority_date: 20/08/2021
                      estimated_completion_date_status: AVAILABLE
                      estimated_completion_dates:
                      - date: 17/03/2023
                        probability: 0.9
                'Example: Application reference is valid, application is delayed. ECD is available.':
                  value:
                    data:
                      application_reference: X001XXX
                      application_status: DELAYED
                      application_priority_date: 19/01/2023
                      estimated_completion_date_status: AVAILABLE
                      estimated_completion_dates:
                      - date: 13/05/2024
                        probability: 0.9
                'Example: Application reference is valid, application is received. ECD status is exceeded.':
                  value:
                    data:
                      application_reference: X002XXX
                      application_status: RECEIVED
                      application_priority_date: 12/02/2022
                      estimated_completion_date_status: EXCEEDED
                'Example: Application reference valid and matches an application. ECD is not yet calculated.':
                  value:
                    data:
                      application_reference: X003XXX
                      application_status: RECEIVED
                      application_priority_date: 20/04/2022
                      estimated_completion_date_status: CALCULATING
                'Example: Application reference is valid and matches a cancelled application. ECD status is unavailable.':
                  value:
                    data:
                      application_reference: X004XXX
                      application_status: CANCELLED
                      application_priority_date: 23/08/2022
                      estimated_completion_date_status: UNAVAILABLE
        4XX:
          description: client errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                'Example 400: Application reference invalid format':
                  value:
                    errors:
                    - code: BG40001
                      detail: Malformed invalid schema. Application Reference is invalid.
                      status: '400'
                      trace_id: c62e9b3f-e523-4f04-a941-c6cf0d60c080
                      title: Invalid application reference.
                'Example 404: Application reference valid format but does not match an HMLR application':
                  value:
                    errors:
                    - code: BG40002
                      detail: application reference is not found.
                      status: '404'
                      trace_id: c62e9b3f-e523-4f04-a941-c6cf0d60c080
                      title: application reference not found.
        5XX:
          $ref: '#/components/responses/DefaultErrorResponse'
components:
  schemas:
    Source:
      type: object
      description: An object containing references to the primary source of the error.
      properties:
        pointer:
          type: string
          description: JSON Pointer to the value in the request document that caused the error
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error
        header:
          type: string
          description: A string indicating the name of a single request header which caused the error
    ECD:
      type: object
      description: If EstimatedCompletionDateStatus is [AVAILABLE] the estimated completion date of the application is provided.
      properties:
        date:
          type: string
          format: date
          description: ECD is calculated using the time in which 90% of the application type were completed. See documentation for current calculation ruleset.
        probability:
          description: The chance the application will be completed by this date.
          type: number
          example: 0.9
          minimum: 0
          maximum: 1
    ErrorResponse:
      description: A response for an unsuccessful result.
      type: object
      properties:
        errors:
          description: A collection of one or more errors as to why the API request failed.
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Error:
      type: object
      description: An error response for an unsuccessful request.
      required:
      - code
      - detail
      properties:
        code:
          description: The code related to this error, see documentation for more information.
          type: string
        detail:
          description: The descriptive reason behind an error.
          type: string
        status:
          description: The http status code related to this error.
          type: string
          example: '503'
        trace_id:
          type: string
          description: A trace identifier for this request.
          example: c62e9b3f-e523-4f04-a941-c6cf0d60c080
        title:
          type: string
          description: A short summary of the problem that does not change from occurrence to occurrence of the problem.
        source:
          $ref: '#/components/schemas/Source'
    ApplicationReference:
      description: HMLR generated unique set of characters that identifies applications
      type: string
      pattern: ^([A-Z][0-9]{3}[A-Z]{3})|([A-Z]{2}[0-9A-F]{5})$
    ApplicationStatus:
      type: string
      description: "A code representing the status of an application.  \n - DELAYED: The application has requisitions, an extension of time has been granted, a site visit has been requested, the application has been referred internally or there are prior pending applications. \n - RECEIVED: The application has been received, the priority is protected and is awaiting processing. \n - CANCELLED: The application has been cancelled and removed from the Daylist. \n - COMPLETED: The application has been completed and is no longer active on the Daylist."
      enum:
      - DELAYED
      - CANCELLED
      - RECEIVED
      - COMPLETED
    ECDResponseData:
      description: Response object
      type: object
      required:
      - application_reference
      - application_status
      - application_priority_date
      - estimated_completion_date_status
      properties:
        application_reference:
          $ref: '#/components/schemas/ApplicationReference'
        application_status:
          $ref: '#/components/schemas/ApplicationStatus'
        application_priority_date:
          type: string
          format: date
          description: Date of a Land Registry Application that is used to confer priority.
        estimated_completion_date_status:
          $ref: '#/components/schemas/ECDStatus'
        estimated_completion_dates:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ECD'
    ECDStatus:
      type: string
      description: "A code representing the status of obtaining the estimated completion date.  \n - AVAILABLE: ECD is available \n - CALCULATING: This is shown when the ECD for the application is being calculated for the first time. \n - EXCEEDED: ECD is unavailable. This is shown when the ECD for the application has elapsed. \n - UNAVAILABLE: ECD is unavailable. Application status is completed or cancelled. \n - NOT_APPLICABLE: ECD is unavailable."
      enum:
      - AVAILABLE
      - CALCULATING
      - EXCEEDED
      - UNAVAILABLE
      - NOT_APPLICABLE
  responses:
    DefaultErrorResponse:
      description: An error has occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Gateway Timeout:
              value:
                errors:
                - code: BG50004
                  detail: The gateway has timed out.
                  status: '504'
                  trace_id: c62e9b3f-e523-4f04-a941-c6cf0d60c080
                  title: An error has occurred
  parameters:
    ApplicationReferenceParameter:
      in: path
      name: application_reference
      description: HMLR generated unique set of characters that identifies applications.
      required: true
      schema:
        $ref: '#/components/schemas/ApplicationReference'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic