openapi: 3.2.0
info:
  title: Hmcts Result Codes API
  version: '@version@'
  contact:
    name: HMCTS AppReg Team
    url: https://github.com/hmcts/appreg-api
  description: 'Operations tagged result-codes across 2 of this provider''s published API definitions: appreg-api-openapi.yaml, hmcts-applications-register-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /
tags:
- description: Result codes are reference data, not managed in App Reg. They are required to provide a set of ways an Application List Entry can be resulted. e.g. Approved/Denied.
  name: result-codes
paths:
  /result-codes:
    get:
      description: 'Returns a paginated list of Result Codes.

        - Filters:

        - `code` – case-insensitive partial match

        - `title` – case-insensitive partial match'
      operationId: getResultCodes
      parameters:
      - description: Filter by code (contains, case-insensitive).
        example: CC
        in: query
        name: code
        schema:
          maxLength: 10
          type: string
      - description: Filter by title (contains, case-insensitive).
        example: Fee Remitted (Benefits)
        in: query
        name: title
        schema:
          maxLength: 500
          type: string
      - description: Zero-based page index.
        in: query
        name: pageNumber
        schema:
          default: 0
          format: int32
          minimum: 0
          type: integer
      - description: Page size.
        in: query
        name: pageSize
        schema:
          default: 10
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      - description: 'Sort parameter. Format: `property,(asc|desc)`. Currently only a single sort value is supported. Example: `?sort=title,asc`.

          '
        explode: true
        in: query
        name: sort
        schema:
          example:
          - title,asc
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/result-code-page'
          description: Page of Result Codes
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              schema:
                example: Accept
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '406':
          content:
            application/problem+json:
              examples:
                notAcceptable:
                  value:
                    type: https://errors.hmcts.net/common/not-acceptable
                    title: Not Acceptable
                    status: 406
                    detail: Requested media type/version not acceptable
              schema:
                $ref: '#/components/schemas/problem'
          description: Requested media type/version not acceptable.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get Result Codes (paginated, filterable)
      tags:
      - result-codes
    servers:
    - url: /
  /result-codes/{code}:
    get:
      description: Returns the Result Code matching the supplied code and valid on the supplied date.
      operationId: getResultCodeByCodeAndDate
      parameters:
      - description: Code used to identify the Result Code (case-insensitive).
        example: CF
        in: path
        name: code
        required: true
        schema:
          maxLength: 10
          type: string
      - description: 'ISO date (yyyy-MM-dd) on which the Result Code must be valid.

          '
        example: 2021-01-01
        in: query
        name: date
        required: true
        schema:
          format: date
          type: string
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/result-code-get-detail-dto'
          description: Result Code found
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              schema:
                example: Accept
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '406':
          content:
            application/problem+json:
              examples:
                notAcceptable:
                  value:
                    type: https://errors.hmcts.net/common/not-acceptable
                    title: Not Acceptable
                    status: 406
                    detail: Requested media type/version not acceptable
              schema:
                $ref: '#/components/schemas/problem'
          description: Requested media type/version not acceptable.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get a specific Result Code by code and date
      tags:
      - result-codes
    servers:
    - url: /
components:
  schemas:
    template-constraint:
      description: The template field with an associated value
      properties:
        type:
          description: The data type of the value.
          enum:
          - TEXT
          example: TEXT
          type: string
        length:
          description: The length of the data value.
          example: 1234
          type: integer
      required:
      - length
      - type
      type: object
    template-detail:
      description: The wording details
      properties:
        template:
          description: The template name. It contains the field names between curly braces.
          example: This is a test {{Applicant number}} with a date
          type: string
        substitution-key-constraints:
          description: A list of fields and the associated constraints
          items:
            $ref: '#/components/schemas/template-key-with-constraint'
          type: array
      required:
      - template
      type: object
    result-code-get-summary-dto:
      description: Lightweight DTO used in list/search views.
      properties:
        resultCode:
          description: Code that identifies the result.
          example: RC-001
          type: string
        title:
          description: Human-readable title.
          example: Application List Entry Fee Status
          type: string
      required:
      - resultCode
      - title
      type: object
    sort_orders_inner:
      properties:
        property:
          description: Property name used for sorting.
          example: title
          type: string
        direction:
          description: Sort direction.
          enum:
          - asc
          - desc
          example: asc
          type: string
      required:
      - direction
      - property
      type: object
    page:
      description: Generic Spring Data page.
      properties:
        pageNumber:
          description: Zero-based page index.
          format: int32
          type: integer
        pageSize:
          description: Page size.
          format: int32
          type: integer
        totalElements:
          description: Total number of elements across all pages.
          format: int64
          type: integer
        totalPages:
          description: Total number of pages.
          format: int32
          type: integer
        sort:
          $ref: '#/components/schemas/sort'
        first:
          type: boolean
        last:
          type: boolean
        elementsOnPage:
          description: Total number of elements in the current page.
          format: int32
          type: integer
      required:
      - content
      - elementsOnPage
      - pageNumber
      - pageSize
      - totalElements
      type: object
    result-code-get-detail-dto:
      description: Immutable DTO representing a detailed Result Code.
      properties:
        resultCode:
          description: Code that identifies the result.
          example: RC-001
          type: string
        title:
          description: Human-readable title.
          example: Application List Entry Fee Status
          type: string
        wording:
          $ref: '#/components/schemas/template-detail'
        startDate:
          description: Date the Result Code became active.
          example: 2025-12-01
          format: date
          type: string
        endDate:
          description: Date the Result Code became inactive. `null` indicates that this row is still active.
          example: 2025-12-31
          format: date
          type:
          - string
          - 'null'
      required:
      - endDate
      - resultCode
      - startDate
      - title
      - wording
      type: object
    sort:
      description: Sorting state for the returned page.
      example:
        orders:
        - property: title
          direction: asc
        - property: code
          direction: desc
      properties:
        orders:
          description: Active sort orders in priority order.
          items:
            $ref: '#/components/schemas/sort_orders_inner'
          type: array
      type: object
    problem:
      description: RFC 9457/7807 problem details.
      properties:
        type:
          description: Problem type identifier (URI).
          example: https://errors.hmcts.net/appreg/bad-request
          format: uri
          type: string
        title:
          description: Short, human-readable summary.
          example: Invalid request parameters
          type: string
        status:
          description: HTTP status code.
          example: 400
          format: int32
          type: integer
        detail:
          description: Human-readable explanation specific to this occurrence.
          example: startDateFrom must be on or before startDateTo
          type: string
        instance:
          description: URI reference to the specific occurrence (if applicable).
          example: urn:request:2f9c3d8a-1b3a-4a1e-9b7f-6b2a6a0a2b2f
          format: uri
          type: string
        correlationId:
          description: Server-side correlation ID for tracing.
          example: 3e1a2c95a7d84a5fb3e1a2c95a7d84a5
          type: string
      required:
      - status
      - title
      - type
      type: object
    template-key-with-constraint:
      description: The template field with an associated value
      properties:
        key:
          description: Field key for substitution into the template.
          example: account-number
          type: string
        value:
          description: The optional value for the key.
          example: '12345678'
          type: string
        constraint:
          allOf:
          - $ref: '#/components/schemas/template-constraint'
          description: The constraint details for the field
      required:
      - constraint
      - key
      type: object
    result-code-page:
      allOf:
      - $ref: '#/components/schemas/page'
      - properties:
          content:
            items:
              $ref: '#/components/schemas/result-code-get-summary-dto'
            type: array
        type: object
x-refined-from:
- appreg-api-openapi.yaml
- hmcts-applications-register-openapi.yml