Guidance

Court and Tribunal Hearings Service Application Programming Interface (API) Requirements

Updated 29 July 2026

Applies to England, Scotland and Wales

1. Foreword

The Court and Tribunal Hearings Service (CaTH) supports the delivery of HMCTS’ commitment to open justice by modernising and improving public access to information provided by HMCTS. This is done by publishing or displaying court and tribunal information (such as hearing lists), according to the relevant policy requirements and business rules.

CaTH has the capability to integrate with source systems to receive data or documents directly. This removes the need for legacy, manual publishing processes.

As part of CaTH, we have developed an outbound API that allows HMCTS to send information to third party organisations.

This guidance provides a high-level overview of the service, more detail about integrating with our outbound API and the structure of files that we receive and send.

2. Overview of CaTH

At its core, CaTH enables jurisdictions to publish information that can be distributed to external users, providing a single point of access for viewing information published by HMCTS.

Below is an illustrated example of CaTH’s core process:

Diagram showing data pipelines into a business rules system that outputs daily, civil cause, and SJP public lists.

The CaTH service has been developed to address inconsistencies in both the content and methods of publication used by different jurisdictions. Its objective is to bring these disparate approaches together into a single, unified solution, ensuring greater consistency and standardisation.

Information is typically received as a “payload” (a JSON formatted packet of information) and displayed via style guides within the service itself or via PDF versions as part of subscriptions.

It is the responsibility of the “payload” / publication owner to ensure the incoming “payload” is appropriately redacted and has gone through the necessary HMCTS Risk Management Framework. Any data within the “payload” received will simply be displayed based on its associated style guide. CaTH does not perform data manipulation.

When receiving a “payload” CaTH will check that all mandatory fields and headers have been included for the associated style guide. This check will be done based on an agreed ‘validation schema’. If it fails this check, then the publication will not be published, and a message returned to the source providing reasons for the failure.

3. Publishing principles

CaTH has been designed with 5 underlying publishing principles that must be adhered to.

Publishing principles:

• We Publish at a location
• We Publish for a period
• All Publications can be subscribed to (but restricted subject to the “sensitivity”)
• All Publications need a “trigger”
• All Publications can be superseded

3.1 Publishing at a location:

CaTH can publish at several distinct levels as shown in the image below, provided that publications for that list type remain consistent. For example, we would not expect to publish the same content on behalf of Basildon County Court and Basildon Combined Court under two distinct locations – there would need to be a payload per location.

UK maps showing national vs regional court coverage, with icons for a single courthouse and multiple courts

3.2 Publishing for a period

CaTH has been built to be the technical platform to service needs of different jurisdictions and varying publication types. There are various publications which are distributed across a range of different time periods, sometimes with these periods overlapping. Examples include daily hearing lists, weekly hearings lists (which can include information from daily lists), and monthly hearing lists (which can include both the daily and weekly lists).

Publications are displayed and held within CaTH for a configurable period. This information’s “display-from” and “display-to” dates are supplied by the source system when sending to CaTH.

CaTH handles these overlapping publications by allowing services to include a content date, for example the date of hearings or the date of publication. Additionally, jurisdictions can name their publication types, thereby distinguishing them according to the time periods they cover. For example, naming publications daily lists, weekly registers etc.

3.3 Publication classifications

CaTH is a freely accessible service available to all members of the public. However, not all information is publicly available, with certain sensitive information being available only to professional users and accredited members of the media. With this in mind, publications are assigned a ‘sensitivity’ so that CaTH knows how to classify the publication and which users to make it available to.

The image below depicts three distinct levels of classifications. The source system will set the sensitivity of the publication and CaTH will publish accordingly.

Pyramid showing information levels: Public for all users, Private for verified users, Classified for select users

3.4 All publications can be superseded

To support jurisdictions updating a publication, “payloads” may overwrite existing “payloads” without needing to remove the old one and publish a new one. Simply publishing again (provided key fields match) will ensure superseding happens.

An example of this would be when a particular hearing has been vacated and an updated list must be published which no longer lists the vacated hearing.

• Provenance (the source system)
• Type (such as a “Crown Daily List”)
• Location ID
• Language (to ensure we do not supersede alternative language formats)
• Content date

4. Third party - outbound API

The following section outlines how HMCTS shares information with third parties via the API. If you require anything in addition to what is outlined below, such as different authentication mechanisms, this will need to be discussed and approved through governance channels in HMCTS.

Note – The publications you receive will depend on the list types and associated sensitivities agreed as part of the onboarding process.

4.1 Overview

CaTH will receive a “payload” from a source system. We mainly receive JSON files from source systems, however we can and do occasionally receive flat / raw files, which can be one of the following types:

• .csv
• .doc
• .docx
• .htm
• .html
• .pdf

CaTH will either send you the JSON or one of the flat files above via the outbound API, alongside metadata describing the file.

If a publication is manually deleted in CaTH, for example it has been published with a mistake, we will also notify you of this deletion.

4.2 Notification mechanism

CaTH will notify you of the above via HTTP REST. With the base URL that you provide, we will notify you as follows:

Notification Type	Request Method
New Publication	POST
Update to Existing Publication (Superseded)	PUT
Delete Publication	DELETE

4.3 Endpoints

To enable connections with CaTH, you are required to set up the following endpoints with the agreed URL formats below:

Request Method	URL Path
GET	BaseURL
POST	BaseURL
PUT	BaseURL/PublicationID
DELETE	BaseURL/PublicationID

The Publication ID highlighted in the PUT / DELETE requests, will be the same publication ID sent in the metadata as part of the original, new publication.

The GET endpoint is used as a health check endpoint to test your connection with us. The POST / PUT / DELETE endpoints are used by CaTH to send publications / notifications to you.

4.4 Request body

The content type for the POST and PUT requests will be: multipart/form-data.

Note - The GET and DELETE request would not contain a body, and instead the ID in the URL should be used to identify the publication to delete.

The POST / PUT request body comprised of the following parts:

Part	Mandatory	Description
metadata	Yes	Contains the JSON metadata about the publication. See section 4.5 for the JSON structure
payload	No	Present if sending a JSON publication. This is the raw JSON that we receive, or the converted to JSON in the case of receiving an excel file
file	No	Present if sending a flat / raw file

The following table describes each part’s possible content types:

Part	File type	MIME type
metadata	N/A	application/json
payload	N/A	application/json
file	.pdf	application/pdf
	.csv	text/csv
	.doc	application/msword
	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
	.htm or .html	text/html

4.5 Part: metadata

The following table details each item in the metadata JSON:

Key	Description	Type
publicationId	The UUID uniquely identifying the publication. This will be sent in subsequent PUT / DELETE requests	UUID
listType	The list the publication is for, see section 4.8 for details	String (See section 4.8)
locationName	The name of the location the publication is for	String
contentDate	The date the publication is for. For publications that span multiple tables, this is the first day of the publication	ISO 8061 date / time format
sensitivity	The sensitivity of the publication – see section 3.3 for details	String (PUBLIC, PRIVATE or CLASSIFIED)
language	The language of the publication	String (ENGLISH, WELSH or BI_LINGUAL)
displayFrom	When the publication is visible to users from	ISO 8061 date / time format
displayTo	When the publication is visible to users to	ISO 8061 date / time format

An example of the ‘metadata’ part is as follows:

{

  “publicationId”: “29e7432d-9c9f-4cb0-bdf9-06f9d4465dc9”,

  “listType”: “CIVIL_DAILY_CAUSE_LIST”,

  “locationName”: “Norwich Combined Court Centre”,

  “contentDate”: “2025-02-05T00:00:00Z”,

  “sensitivity”: “PUBLIC”,

  “language”: “ENGLISH”,

  “displayFrom”: “2024-04-05T00:00:00Z”,

  “displayTo”: “2024-04-05T00:00:00Z”,

}

4.6 Part: payload

If the data CaTH receives is JSON (or if it is Excel and is converted to JSON), this will be sent via the ‘payload’ part of the body. For flat file publications, the payload value would be null.

The structure / schema for this JSON is specific to the List Type (sent in the metadata, see section 4.8 for further details). Schemas for each of the list types can be found here: https://github.com/hmcts/pip-data-management/tree/master/src/main/resources/schemas

4.7 Part: file

If the data CaTH receives is a raw / flat file, this will be sent via the ‘file’ part of the body, and details of the possible file types we receive can be found in section 4.1.

The name of the file will be a randomly generated UUID plus the file extension. The value of file would be null for JSON publication.

4.8 List types

As can be seen in section 4.5, we will send you the List Type in the metadata which identifies which list the data is for. The full list of list types can be found here: https://github.com/hmcts/pip-data-models/blob/master/src/main/java/uk/gov/hmcts/reform/pip/model/publication/ListType.java

Note – new lists can be added and therefore the above is subject to change. The list types you receive will depend on the agreed subscriptions set up for your account.

4.9 Deletion of publications

As highlighted in section 4.2, we will notify you via a DELETE request if a publication has been manually deleted from CaTH.

We will not notify you when a publication is expired (the ‘displayTo’ date in the metadata sent has been reached)

4.10 Authentication

Currently we support OAuth authentication via the API, using the client credentials grant flow to generate a token which will be sent in the request.

The support this, we require the following from you:

• Client ID
• Client Secret
• Scope
• Token URL (to request the token from)

When making the request to yourself, we will use the above to request a bearer token. This will then be sent via the ‘Authorization’ header.

4.11 Retries

If a failure response is returned from the third party, CaTH will retry a further three times to send the publication.

4.12 Responses

We do not expect anything in the body in the response from the third party, and do not process it.

In terms of the response code, we expect a 2xx response to be returned. If anything else is returned, it will retry as per the section above.

4.13 Future dated publications

It is possible for CaTH to receive future dated publications, i.e., publications where the display from date is in the future.

In this scenario, CaTH will forward on the publication at 1AM UTC the first morning that the publication is active.

5. What we need from you

To set up your account to start receiving publications, we require the following from you:

• The base URL to send publications to
• Authentication details (See section 4.10)

When sending the authentication details to us via email, you should be encrypting the file containing the information using GnuPG (aka GPG).   

We will generate a GPG public/private key pair on our end, and the file containing the public key will be shared with you. You should be using this public key to encrypt the text file with the authentication details. Attach the encrypted file in an email to us using the same email you used to sign up with us.

Upon receiving the data from you, we will use the private key to decrypt the file to retrieve the authentication details. 

Please refer to the following online documentation on how to use GPG for encryption:

https://www.gnupg.org/documentation/index.html