HM Courts & Tribunals Service Jobs 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 Jobs API
  version: '@version@'
servers:
- url: /
tags:
- description: Background job operations for asynchronous tasks (polling status across all job types).
  name: Jobs
paths:
  /jobs/{jobId}:
    get:
      description: Returns the current status and details of a background job.
      operationId: getJobStatusById
      parameters:
      - description: The unique identifier of the job.
        example: 9f7b2a35-57ac-4a1c-9c41-83b6c8157af4
        in: path
        name: jobId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/job-acknowledgement'
          description: Job status retrieved successfully.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              example: Accept
              schema:
                type: string
        '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.
        '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 the status of a background job
      tags:
      - Jobs
components:
  schemas:
    job-status:
      description: The status of the job being polled by the user.
      enum:
      - RECEIVED
      - VALIDATING
      - PROCESSING
      - FAILED
      - COMPLETED
      example: RECEIVED
      type: string
    job-type:
      description: The type of the job being polled by the user.
      enum:
      - ACTIVITY_AUDIT_REPORT
      - FEES_REPORT
      - LIST_MAINTENANCE_REPORT
      - SEARCH_WARRANTS_REPORT
      - WORKLOAD_REPORT
      - DURATION_REPORT
      - PRIVATE_PROSECUTORS_INDEX_REPORT
      - BULK_UPLOAD_ENTRIES
      example: FEES_REPORT
      type: string
    job-acknowledgement:
      additionalProperties: false
      description: Acknowledgement returned when a background job is created.
      properties:
        id:
          description: Unique identifier for the job, in UUID v4 format.
          example: 9f7b2a35-57ac-4a1c-9c41-83b6c8157af4
          format: uuid
          type: string
        type:
          $ref: '#/components/schemas/job-type'
        status:
          $ref: '#/components/schemas/job-status'
        createdCount:
          description: 'Number of applications imported by this job, excluding the CSV header and including subsequently soft-deleted applications. Available only when polling a completed BULK_UPLOAD_ENTRIES job; omitted from all other responses. Counted from retained job-to-application mappings, not the current list size.

            '
          example: 12
          format: int64
          minimum: 0
          type: integer
          x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)'
        mainFeeTotal:
          description: 'Current main fees in GBP for non-deleted applications created by this upload, regardless of payment or remission status. Available only when polling a completed BULK_UPLOAD_ENTRIES job; zero when no applicable fees remain. Calculated on read, so later changes to applications or associated fees can change this value. Omitted from all other responses.

            '
          example: 120.5
          type: number
          x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)'
        offsiteFeeTotal:
          description: 'Current applicable offsite fees in GBP for non-deleted applications created by this upload, regardless of payment or remission status. Available only when polling a completed BULK_UPLOAD_ENTRIES job; zero when no applicable fees remain. Calculated on read, not an upload-time snapshot. Omitted from all other responses.

            '
          example: 30.25
          type: number
          x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)'
        totalFeeValue:
          description: 'Sum of mainFeeTotal and offsiteFeeTotal in GBP. Available only when polling a completed BULK_UPLOAD_ENTRIES job. Zero when no applicable fees remain; calculated on read. Omitted from all other responses.

            '
          example: 150.75
          type: number
          x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)'
        error_description:
          description: 'Details of a failed job. Bulk-upload validation failures may include actionable input errors; unexpected bulk-upload processing failures use a generic message and identify the job reference to quote to support.

            '
          type: string
      required:
      - id
      - status
      - type
      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