HM Courts & Tribunals Service Result Codes API

openapi: 3.2.0
info:
  contact:
    name: HMCTS AppReg Team
    url: https://github.com/hmcts/appreg-api
  description: REST API for managing Administrative Tasks, Applications Lists, Application List Entries and getting important, reference data including Application Codes, Result Codes, Fees, Court Locations, Criminal Justice Areas and Standard Applicants.
  title: Applications Register Result Codes API
  version: '@version@'
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
  /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
components:
  schemas:
    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-page:
      allOf:
      - $ref: '#/components/schemas/page'
      - properties:
          content:
            items:
              $ref: '#/components/schemas/result-code-get-summary-dto'
            type: array
        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
    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
    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
    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
    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
    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-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
    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