Guidance

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

Updated 15 July 2026

Applies to England, Scotland and Wales

1. Foreword

The Court and Tribunal Hearings service supports the delivery of HMCTS’s commitment to open justice. By modernising and improving public access to information provided by HMCTS. Publishing or displaying court/tribunal information (such as court and tribunal hearing lists), according to the relevant policy requirements and business rules.

The service has the capability to integrate with source systems to receive data, or documents directly removing the need for legacy, manual publishing processes.

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

Within this document we’ll provide you with a high-level overview of the service, and more detail about our outbound API and the structure of files that we receive and send.

2. Overview of CaTH

The vision for CaTH is “To support the delivery of HMCTS’s commitment to open justice and to modernise and improve public access to information provided by HMCTS by publishing or displaying court/tribunal information (such as court and tribunal lists), according to the relevant policy requirements and business rules.”

At its most basic, CaTH is a system which allows jurisdictions to push publications through it to give external users a one stop shop to view information published by HMCTS.

Basic representation of CaTH 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 across the landscape in how and what is being published by various jurisdictions and the objective of this service is to bring these approaches together into one unified solution.

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 5x underlying design 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 touched on in the image below but on the proviso that publications for that list type remain consistent. E.g. We would not expect to publish the same content on behalf of Basildon County Court and Basildon Combined Court under 2x 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 varying publications that get published/circulated over a multitude of different periods, sometimes with these periods overlapping (such as daily, weekly (which could include content from the daily), and monthly (which could include both the daily and weekly content)).

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

CaTH can further handle these challenges by allowing services to include a content date e.g. the date of the hearings or the date the publication is published.

This challenge is even further managed by allowing jurisdictions to name their publication types, thus making them distinguishable to the user for the periods they cover e.g. Daily list, Weekly register.

3.3 Publication classifications

Whilst CaTH is a public and free service available for users from members of the public, professional users to accredited members of the media. Not all the publications that HMCTS does or will publish are publicly available. With this in mind, publications must be assigned a ‘sensitivity’ so that CaTH knows how to classify the publication and which users to make it available to.

The below describes 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 that one hearing has been vacated and a new list needs publishing without the vacated hearing

This will only occur if 5x key fields match (see below). Where all 5x do not match, a second publication will be available to be displayed.

• 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

This section will provide details of the what and the how we’ll be sending information to you.

What follows is our current way of sending and authenticating with 3rd parties. If you require anything in addition to this e.g. different authentication mechanisms, this will require a change our side and will need to be discussed and approved through governance channels on the HMCTS side.

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 2.4.1 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 2.5 for details	String (See section 2.5)
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 1.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 2.5 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 2.3.

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 2.4.1, 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 2.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 2.7)

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