Skip to main content
HMCTS API Marketplace

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

Producer guidance

How to list your team’s API in the marketplace so other teams can find it, understand what it does, and request access — and what you are responsible for once it is live.

The marketplace doesn’t own or run any of the APIs it lists — your team keeps that. What it does is make your API discoverable, documented, and reachable through a consistent access request process.

What you will need

Your API must meet the producer standards before it can be listed. You will need:

  • a published OpenAPI specification, reachable at a stable URL
  • a named owning team and a contact email
  • a data classification for everything the API returns
  • a description of what the API is for
  • a DPIA in place that covers the data being shared as part of the API

How to get your API listed

  1. Check your API meets the producer standards: the technical requirements, eligibility criteria and specification quality.
  2. Make sure your API repository is public on GitHub under the HMCTS organisation.
  3. Add the publish-api-docs.yml workflow to .github/workflows/ and raise a pull request.
  4. Once merged, trigger the workflow manually or cut a GitHub release — the version is stamped from the release tag.
  5. Confirm the Swagger UI documentation site is live at https://hmcts.github.io/<repo-name>/.
  6. Email the API Marketplace team at APIMarketplace@hmcts.net to get your API published. The team will review your API and confirm.
  7. Once approved, your API appears in the catalogue and is kept in sync with your specification automatically.

Ongoing responsibilities

Keeping the spec current
Update your OpenAPI specification whenever you change the API. Cut a new GitHub release to publish the updated documentation.
Notifying consumers of breaking changes
Tell consumers about breaking changes with enough notice to act on them.
Reviewing access requests promptly
Respond to consumer access requests promptly. Give a clear reason if you reject one.
Maintaining contact details
Keep info.contact.email in your spec pointing at an active team inbox.
Deprecation and removal
If you need to remove an API, tell all consumers and the marketplace team at least 30 days in advance.

Get help

If you’re not sure whether your API is ready, or you want to talk through the process first, contact the marketplace team at APIMarketplace@hmcts.net.