Skip to main content
HMCTS API Marketplace

Beta This is a new service – your feedback will help us to improve it.

Consumer guidance

How to find, request and use HMCTS APIs responsibly.

Contents

  1. Before you request access
  2. Making an access request
  3. Using the API responsibly
  4. Error handling and resilience
  5. Keeping access current
  6. Getting help
  7. Data governance
  8. Terms of use

1. Before you request access

Understand what you need

  • Read the API’s description and understand what data it returns, and what it does not

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

2. Making an access request

  1. Browse the API catalogue to find the APIs you want to test. You do not need an account to do this.
  2. Sign in, or create a developer account if you do not have one yet. You need an account to create an application for Try it now and test the APIs.
  3. Create an application for Try it now and add the APIs you want to test. Your Try it now credentials and keys are issued automatically, with no review.
  4. Test your software with the APIs, using dummy data.
  5. When you are ready for live data, request production credentials for an application you have tested, describing what you are building and why you need the API.
  6. The HMCTS Data Access Panel reviews your request. This is currently an offline process, so look out for emails asking for clarification or confirming the outcome.
  7. If approved, the API Marketplace team issues your production credentials and keys.

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

Authentication

  • All APIs use OAuth 2.0 with JWT bearer tokens
  • Tokens expire — implement token refresh correctly and do not hard-code credentials
  • Application registration — 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

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.

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 at APIMarketplace@hmcts.net.
Urgent production issues
Contact the HMCTS DTS service desk.

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
Warning You must not access any API containing personal data without a signed DPA or DSA in place.

8. Terms of use

These Terms of Use apply to all users of the HMCTS API Marketplace.

By using the marketplace, you agree to comply with applicable HMCTS policies, security standards and legal obligations.

Acceptable use

You must:

  • Use APIs only for approved business purposes.
  • Access only the data and functionality you are authorised to use.
  • Protect credentials, tokens and other authentication secrets.
  • Follow any API-specific documentation, access conditions or data-sharing requirements.

You must not:

  • Share credentials between teams, services or individuals.
  • Attempt to bypass security controls, rate limits or monitoring.
  • Access, modify or disclose data without appropriate authorisation.
  • Use APIs in a way that could disrupt services or compromise security.

Security

All users are responsible for maintaining appropriate security controls within their services and systems.

Any actual or suspected security incident, credential compromise or unauthorised access must be reported immediately through the established HMCTS security and support processes.

Monitoring and audit

HMCTS may monitor API usage to:

  • Maintain service availability.
  • Investigate security incidents.
  • Support operational and compliance requirements.
  • Ensure compliance with marketplace standards.

Users must cooperate with any audit or investigation relating to their use of marketplace APIs.

Access management

Access to APIs is subject to approval by the API owner and may be reviewed periodically.

HMCTS and API owners reserve the right to suspend, restrict or revoke access where:

  • Access is no longer required.
  • Terms of Use or marketplace standards are breached.
  • Continued access presents a security, operational or legal risk.

API changes

API owners should provide reasonable notice of material changes or decommissioning activities where possible.

Consumers are responsible for maintaining compatibility with supported API versions.

Disclaimer

HMCTS makes reasonable efforts to ensure the availability and accuracy of information within the marketplace but does not guarantee uninterrupted access to any API or service.

Contact

If you have questions about these Terms of Use contact the Marketplace Team at APIMarketplace@hmcts.net.

Browse the API catalogue