HM Courts & Tribunals Service Application 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 Application Codes API
  version: '@version@'
servers:
- url: /
tags:
- description: Application Codes are reference data, not managed in App Reg. They are required to provide a set repeatable data that can be used by Application List Entries, such as the title, wording or whether an application has an associated fee.
  name: application-codes
paths:
  /application-codes:
    get:
      description: 'Returns a paginated list of Application Codes.

        - Filters:

        - `code` – case-insensitive partial match

        - `title` – case-insensitive partial match'
      operationId: getApplicationCodes
      parameters:
      - description: Filter by code (contains, case-insensitive).
        example: AD99004
        in: query
        name: code
        schema:
          maxLength: 10
          type: string
      - description: Filter by title (contains, case-insensitive).
        example: Certificate of Satisfaction
        in: query
        name: title
        schema:
          maxLength: 500
          type: string
      - description: 'ISO date (yyyy-MM-dd) on which returned Application Codes must be valid.

          '
        example: 2021-01-01
        in: query
        name: date
        required: false
        schema:
          format: date
          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`.\nSupported properties:\n  - `title`\n  - `code`\n  - `bulkRespondentAllowed`\n  - `feeDue`\n"
        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/application-code-page'
          description: Page of Application 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 Application Codes (paginated, filterable)
      tags:
      - application-codes
  /application-codes/{code}:
    get:
      description: Returns the Application Code matching the supplied code and valid on the supplied date.
      operationId: getApplicationCodeByCodeAndDate
      parameters:
      - description: Code used to identify the Application Code (case-insensitive).
        example: AD99004
        in: path
        name: code
        required: true
        schema:
          maxLength: 10
          type: string
      - description: 'ISO date (yyyy-MM-dd) on which the Application 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/application-code-get-detail-dto'
          description: Application 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 Application Code by code
      tags:
      - application-codes
components:
  schemas:
    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
    application-code-get-summary-dto:
      description: Lightweight DTO for Application Codes, used in list/search views.
      properties:
        applicationCode:
          description: Code that identifies the application.
          example: AD99003
          type: string
        title:
          description: Human-readable title.
          type: string
        wording:
          $ref: '#/components/schemas/template-detail'
        isFeeDue:
          description: 'True if Application List Entries using this Application Code require an Application List Entry Fee Status to be created and linked.

            '
          type: boolean
        requiresRespondent:
          description: 'True if Application List Entries using this Application Code require a respondent to be created and linked.

            '
          type: boolean
        bulkRespondentAllowed:
          description: 'True if Application List Entries using this Application Code allow multiple respondents to be created and linked.

            '
          type: boolean
        feeReference:
          description: A short reference code that identifies a Fee.
          example: CO5.2
          maxLength: 12
          type:
          - string
          - 'null'
        feeAmount:
          $ref: '#/components/schemas/application_code_get_detail_dto_feeAmount'
        feeDescription:
          description: Descriptive text for the fee.
          type:
          - string
          - 'null'
        offsiteFeeReference:
          description: A short reference code that identifies a offsite Fee.
          example: CO1.1
          maxLength: 12
          type:
          - string
          - 'null'
        offsiteFeeAmount:
          $ref: '#/components/schemas/application_code_get_detail_dto_offsiteFeeAmount'
        offsiteFeeDescription:
          description: 'Descriptive text for the offsite fee.

            '
          example: Offsite Fee for application to Crown Court
          type:
          - string
          - 'null'
      required:
      - applicationCode
      - bulkRespondentAllowed
      - isFeeDue
      - requiresRespondent
      - title
      - wording
      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
    application-code-get-detail-dto:
      description: Immutable DTO representing a detailed Application Code.
      properties:
        applicationCode:
          description: Code that identifies the application.
          example: AD99003
          type: string
        title:
          description: Human-readable title.
          example: Application to Crown Court
          type: string
        wording:
          $ref: '#/components/schemas/template-detail'
        isFeeDue:
          description: 'True if Application List Entries using this Application Code require an Application List Entry Fee Status to be created and linked.

            '
          type: boolean
        requiresRespondent:
          description: 'True if Application List Entries using this Application Code require a respondent to be created and linked.

            '
          type: boolean
        bulkRespondentAllowed:
          description: 'True if Application List Entries using this Application Code allow multiple respondents to be created and linked.

            '
          type: boolean
        feeReference:
          description: A short reference code that identifies a Fee.
          example: CO5.2
          maxLength: 12
          type:
          - string
          - 'null'
        feeAmount:
          $ref: '#/components/schemas/application_code_get_detail_dto_feeAmount'
        feeDescription:
          description: Descriptive text for the fee.
          example: Fee for application to Crown Court
          type:
          - string
          - 'null'
        offsiteFeeReference:
          description: A short reference code that identifies a offsite Fee.
          example: CO5.2
          maxLength: 12
          type:
          - string
          - 'null'
        offsiteFeeAmount:
          $ref: '#/components/schemas/application_code_get_detail_dto_offsiteFeeAmount'
        offsiteFeeDescription:
          description: Descriptive text for the offsite fee.
          example: Offsite Fee for application to Crown Court
          type:
          - string
          - 'null'
        startDate:
          description: Date the Application Code became active.
          example: 2025-09-17
          format: date
          type: string
        endDate:
          description: Date the Application Code became inactive. `null` indicates that this row is still active.
          example: 2025-12-01
          format: date
          type:
          - string
          - 'null'
      required:
      - applicationCode
      - bulkRespondentAllowed
      - endDate
      - isFeeDue
      - requiresRespondent
      - startDate
      - title
      - wording
      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
    application-code-page:
      allOf:
      - $ref: '#/components/schemas/page'
      - properties:
          content:
            items:
              $ref: '#/components/schemas/application-code-get-summary-dto'
            type: array
        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
    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
    application_code_get_detail_dto_offsiteFeeAmount:
      description: 'Offsite Fee amount for this Application Code, expressed in pence (GBP minor units). Always use integer values; 1 GBP = 100 pence.

        '
      properties:
        value:
          description: Amount in pence.
          example: 1299
          format: int64
          minimum: 0
          type: integer
        currency:
          default: GBP
          description: ISO 4217 currency code (always "GBP" for now).
          enum:
          - GBP
          example: GBP
          type: string
      required:
      - value
      type:
      - object
      - 'null'
    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
    application_code_get_detail_dto_feeAmount:
      description: 'Fee amount for this Application Code, expressed in pence (GBP minor units). Always use integer values; 1 GBP = 100 pence.

        '
      properties:
        value:
          description: Amount in pence.
          example: 1299
          format: int64
          minimum: 0
          type: integer
        currency:
          default: GBP
          description: ISO 4217 currency code (always "GBP" for now).
          enum:
          - GBP
          example: GBP
          type: string
      required:
      - value
      type:
      - object
      - 'null'