Consumer guidance

How to find, request and use HMCTS APIs responsibly.

Contents

---

1. Before you request access

Understand what you need

• Read the API’s plain-English description and understand what data it returns, and what it does not
• Check the classification — Official-Sensitive APIs require additional justification and may have longer approval times
• Confirm your service or use case is within the intended scope of the API. Do not request access speculatively.

Check your organisation is eligible

• You must be part of HMCTS Digital and Technology Solutions, a justice sector partner, or an approved third party
• You need a valid work email address to register
• Your organisation must have a data sharing agreement in place where required — check with the API owner

Not sure whether your use case is appropriate? Contact the marketplace team before you submit anything — it is a much cheaper conversation than a rejected request.

---

2. Making an access request

What you will need to provide

• Use case description: What you are building, and why you need this API.
• Environment: Whether you need sandbox, production, or both.
• Expected call volume: Low, medium or high — this helps the producer plan capacity.
• Authentication readiness: Confirmation that your system can implement OAuth 2.0 with JWT bearer tokens.

What happens next

• The API owner reviews your request
• You will be notified whether it is approved or rejected
• If rejected, a reason will be given and you may resubmit with additional information
• Once approved, your credentials will be issued via a secure channel

Do not attempt to access an API before your request has been approved. Unauthorised access attempts are logged and may affect future requests.

---

3. Using the API responsibly

Rate limits and fair use

• Do not exceed the rate limits defined in the API specification
• Cache responses where appropriate — do not poll repeatedly for data that does not change frequently
• Use the sandbox environment for development and testing. Never test against production.

Authentication

• All APIs use OAuth 2.0 with JWT bearer tokens
• Tokens expire — implement token refresh correctly and do not hard-code credentials
• Do not share credentials between services or teams. Each consuming service should have its own client credentials.

Data handling

• Data returned by HMCTS APIs is subject to UK GDPR and the Data Protection Act 2018
• Official-Sensitive data must be handled in accordance with the Government Security Classifications policy
• Do not store API responses longer than necessary for your use case
• Do not expose raw API responses to end users without appropriate data processing

---

4. Error handling and resilience

How to handle each response status

HTTP status	Meaning	What to do
400	Bad request	Check your request parameters against the API specification
401	Unauthorised	Refresh your token. Do not loop on auth failures.
403	Forbidden	Your credentials do not have access to this resource
404	Not found	Handle gracefully - the resource may legitimately not exist
429	Too many requests	Back off and retry after the period in the Retry-After header
5xx	Server error	Implement exponential backoff. Use circuit breakers in your service.

Do not treat the API as guaranteed to be available. Implement circuit breakers and fallbacks in your service architecture.

---

5. Keeping access current

• If your use case changes significantly, notify the API owner and resubmit your access request with updated details
• If your service is decommissioned, revoke your credentials and notify the marketplace team
• Access may be reviewed periodically — you may be asked to re-confirm your use case
• Keep your contact details up to date so the API owner can reach you about breaking changes

---

6. Getting help

• API-specific questions: Use the API’s entry in the catalogue to find the owning team’s contact details.
• Access request support: Contact the marketplace team.
• Urgent production issues: Contact the HMCTS DTS service desk.
• Marketplace feedback: Tell the marketplace team — the service is in beta and feedback shapes it.

---

7. Data governance

When accessing HMCTS APIs you are interacting with data that may be subject to legal and regulatory obligations. The following standards apply to all consumers.

Legal framework

• UK GDPR and the Data Protection Act 2018 — any personal data returned by HMCTS APIs must be processed lawfully, with a documented legal basis
• Government Security Classifications policy — Official-Sensitive data requires enhanced security controls in your systems
• Computer Misuse Act 1990 — credentials must not be shared or misused; unauthorised access is a criminal offence

You must not access any API containing personal data without a signed DPA or DSA in place.

For the full set of obligations, read the data governance standards.