get:
  summary: Retrieve Income Tax (Self Assessment) Final Declaration Obligations
  description: |
    This endpoint allows a developer to retrieve the final declaration (previously known as crystallisation) obligations for a customer’s Income Tax account. The account identifier (National Insurance number) must be provided.
    
    ### Test data
    Scenario simulation using Gov-Test-Scenario headers is only available in the sandbox environment.
    
    | Header Value (Gov-Test-Scenario)      | Scenario                                                                               |
    |---------------------------------------|----------------------------------------------------------------------------------------|
    | N/A - DEFAULT                         | Simulates a success response with an open obligation.                                  |
    | MULTIPLE                              | Simulates a success response with multiple obligations.                                |
    | INSOLVENT_TRADER                      | Simulates a scenario where the remote endpoint indicates that the trader is insolvent. |
    | NOT_FOUND                             | Simulates a scenario where no data is found.                                           |
    | DYNAMIC                               | The following response values will change to correspond to the values submitted in the request: <br/> • periodStartDate <br/> • periodEndDate <br/> • dueDate <br/> • receivedDate|


  parameters:
    - $ref: './common/pathParameters.yaml#/components/parameters/nino'
    - name: taxYear
      in: query
      description: |
        The tax year the data applies to.
        
        If a tax year is not specified, returns all obligations starting from 4 years before the current tax year.
        
        For example, if current tax year is 2023-24 and no tax year is specified, all obligations from 2019-20 to 2023-24 are returned.
        
        The earliest allowable tax year is 2017-18.
      schema:
        type: string
        example: 2022-23
      required: false
    - $ref: './common/queryParameters.yaml#/components/parameters/status'
    - $ref: './common/headers.yaml#/components/parameters/acceptJson'
    - $ref: './common/headers.yaml#/components/parameters/authorization'
    - $ref: './common/headers.yaml#/components/parameters/testScenarioHeader'

  security:
    - User-Restricted:
        - read:self-assessment

  responses:
    "200":
      description: Success
      headers:
        X-CorrelationId:
          $ref: './common/headers.yaml#/components/parameters/correlationId'
        Deprecation:
          $ref: './common/headers.yaml#/components/parameters/deprecationHeader'
        Sunset:
          $ref: './common/headers.yaml#/components/parameters/sunsetHeader'
        Link:
          $ref: './common/headers.yaml#/components/parameters/linkHeader'
      content:
        application/json:
          schema:
            $ref: './schemas/retrieve_crystallisation_obligations_response.json'
          examples:
            example-1:
              description: Default
              value:
                $ref: './examples/retrieve_crystallisation_obligations.json'

    "400":
      description: Bad request
      headers:
        X-CorrelationId:
          $ref: './common/headers.yaml#/components/parameters/correlationId'
        Deprecation:
          $ref: ./common/headers.yaml#/components/parameters/deprecationHeader
        Sunset:
          $ref: ./common/headers.yaml#/components/parameters/sunsetHeader
        Link:
          $ref: ./common/headers.yaml#/components/parameters/linkHeader
      content:
        application/json:
          schema:
            $ref: './schemas/error-response.yaml'
          examples:
            FORMAT_NINO:
              $ref: './common/errors.yaml#/components/examples/formatNino'
            FORMAT_TAX_YEAR:
              $ref: './common/errors.yaml#/components/examples/formatTaxYear'
            FORMAT_STATUS:
              $ref: './common/errors.yaml#/components/examples/formatStatus'
            RULE_TAX_YEAR_NOT_SUPPORTED:
              $ref: './common/errors.yaml#/components/examples/ruleTaxYearNotSupported'
            RULE_TAX_YEAR_RANGE_INVALID:
              $ref: './common/errors.yaml#/components/examples/ruleTaxYearRangeInvalid'
            RULE_INSOLVENT_TRADER:
              $ref: './common/errors.yaml#/components/examples/ruleInsolventTrader'
            RULE_INCORRECT_GOV_TEST_SCENARIO:
              $ref: './common/errors.yaml#/components/examples/ruleIncorrectGovTestScenario'

    "403":
      description: Forbidden
      headers:
        X-CorrelationId:
          $ref: './common/headers.yaml#/components/parameters/correlationId'
        Deprecation:
          $ref: ./common/headers.yaml#/components/parameters/deprecationHeader
        Sunset:
          $ref: ./common/headers.yaml#/components/parameters/sunsetHeader
        Link:
          $ref: ./common/headers.yaml#/components/parameters/linkHeader
      content:
        application/json:
          schema:
            $ref: './schemas/error-response.yaml'
          examples:
            CLIENT_OR_AGENT_NOT_AUTHORISED:
              $ref: './common/errors.yaml#/components/examples/clientOrAgentNotAuthorised'

    "404":
      description: Not Found
      headers:
        X-CorrelationId:
          $ref: './common/headers.yaml#/components/parameters/correlationId'
        Deprecation:
          $ref: ./common/headers.yaml#/components/parameters/deprecationHeader
        Sunset:
          $ref: ./common/headers.yaml#/components/parameters/sunsetHeader
        Link:
          $ref: ./common/headers.yaml#/components/parameters/linkHeader
      content:
        application/json:
          schema:
            $ref: './schemas/error-response.yaml'
          examples:
            MATCHING_RESOURCE_NOT_FOUND:
              $ref: './common/errors.yaml#/components/examples/notFound'
            NO_OBLIGATIONS_FOUND:
              $ref: './common/errors.yaml#/components/examples/noObligationsFound'