HM Courts & Tribunals Service Court Locations API

openapi: 3.2.0
info:
  title: Hmcts Court Locations API
  version: '@version@'
  contact:
    name: HMCTS AppReg Team
    url: https://github.com/hmcts/appreg-api
  description: 'Operations tagged court-locations 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: Court Locations are reference data, not managed in App Reg. They are a consolidation of both crown and magistrates courts where an application will be heard and resulted.
  name: court-locations
paths:
  /court-locations:
    get:
      description: 'Returns a paginated list of Court Locations.

        - Filters:

        - `name` – case-insensitive partial match

        - `code` – case-insensitive partial match'
      operationId: getCourtLocations
      parameters:
      - description: Filter by court name (contains, case-insensitive).
        example: Cardiff Crown Court Set 1
        in: query
        name: name
        schema:
          maxLength: 100
          type: string
      - description: Filter by Court Location code (contains, case-insensitive).
        example: MCJC002
        in: query
        name: code
        schema:
          maxLength: 10
          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=name,asc`.

          '
        explode: true
        in: query
        name: sort
        schema:
          example:
          - name,asc
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/court-location-page'
          description: Page of summarised Court Locations
          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 Court Locations (paginated, filterable)
      tags:
      - court-locations
    servers:
    - url: /
  /court-locations/{code}:
    get:
      description: Returns the Court Location matching the supplied code and valid on the supplied date.
      operationId: getCourtLocationByCodeAndDate
      parameters:
      - description: Code used to identify the Court Location (case-insensitive).
        example: MCJC002
        in: path
        name: code
        required: true
        schema:
          maxLength: 10
          type: string
      - description: 'ISO date (yyyy-MM-dd) on which the Court Location 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/court-location-get-detail-dto'
          description: Court Location 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 Court Location by code and date
      tags:
      - court-locations
    servers:
    - url: /
components:
  schemas:
    court-location-page:
      allOf:
      - $ref: '#/components/schemas/page'
      - properties:
          content:
            items:
              $ref: '#/components/schemas/court-location-get-summary-dto'
            type: array
        type: object
    court-location-get-summary-dto:
      description: Lightweight DTO for Court Locations, used in list/search views.
      properties:
        name:
          description: Human-readable court name.
          example: Cardiff Crown Court Set 1
          type: string
        locationCode:
          description: Code that identifies the Court Location.
          example: CCC003
          type: string
      required:
      - locationCode
      - name
      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
    court-location-get-detail-dto:
      description: Immutable DTO representing a detailed Court Location.
      properties:
        name:
          description: Human-readable court name.
          example: Cardiff Crown Court Set 1
          type: string
        locationCode:
          description: Code that identifies the Court Location.
          example: CCC003
          type: string
        startDate:
          description: Date the Court Location became active.
          example: 2025-09-17
          format: date
          type: string
        endDate:
          description: Date the Court Location became inactive. `null` indicates that this row is still active.
          example: 2025-12-01
          format: date
          type:
          - string
          - 'null'
      required:
      - endDate
      - locationCode
      - name
      - startDate
      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
x-refined-from:
- appreg-api-openapi.yaml
- hmcts-applications-register-openapi.yml