openapi: 3.2.0
info:
  title: Hmcts Application Codes API
  version: '@version@'
  contact:
    name: HMCTS AppReg Team
    url: https://github.com/hmcts/appreg-api
  description: 'Operations tagged application-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: 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
    servers:
    - url: /
  /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
    servers:
    - url: /
components:
  schemas:
    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
    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-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
    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
    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:
      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
    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'
    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
    application-code-page:
      allOf:
      - $ref: '#/components/schemas/page'
      - properties:
          content:
            items:
              $ref: '#/components/schemas/application-code-get-summary-dto'
            type: array
        type: object
x-refined-from:
- appreg-api-openapi.yaml
- hmcts-applications-register-openapi.yml