Skip to main content
Guide

Getting Started

This guide takes you from zero to your first authenticated call against the Transactional API.

Before you begin

Your integration must be registered with Medicus before any call will succeed. If you haven't started yet, contact our Partner Integrations team to work through the prerequisites.

Prerequisites​

Before you can call the API, your integration must be set up with Medicus:

  1. A registered application: identified by an applicationIdentifier.
  2. A published JWKS: a URL serving your application's public keys, which Medicus uses to verify the requests you sign. You hold the matching private key.
  3. Granted endpoint access: each endpoint is granted individually in the form <endpoint>:<mode> (for example create-note:application-restricted). See Authentication.
  4. Enabled for the tenant: each practice must enable your application through Medicus before you can call their data. This is self-service for practice administrators. You do not need to contact Medicus per practice.

See Authentication for how these fit together.

Base URL and format​

Each Medicus tenant (practice) is served on its own subdomain. Endpoints accept and return application/json and use a flat path scheme:

https://{tenantId}.api.england.medicus.health/transactional-api/<endpoint>

{tenantId} identifies the practice you are integrating with. During onboarding you develop against Staging, where the host is https://{tenantId}.api.staging.england.medicus.health.

Try it in Postman

Prefer a GUI? Download the Medicus Transactional API Postman collection, import it, set the base_url and client_id collection variables, paste your private key into the collection's JWT auth, then send Ping. The collection is generated from the same spec as this reference, so it always covers the current endpoints.

1. Mint a request token​

Every request carries a short-lived RS256 JWT signed with your application's private key, sent as a bearer token. The token must expire within 60 seconds of being issued. See Authentication for the full claim set.

2. Call ping​

ping is the simplest endpoint: it confirms your credentials work and echoes back the calling application and requesting context.

curl https://{tenantId}.api.england.medicus.health/transactional-api/ping \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $MEDICUS_JWT"

A 200 response confirms you are authenticated:

{
  "status": "ok",
  "timestamp": "2026-01-01T09:00:00Z",
  "application": { "identifier": "your-app", "name": "Your App" },
  "requestingOrganisation": { "...": "..." },
  "requestingPractitioner": { "...": "..." }
}

Next steps​

  • Browse the full Transactional API reference - each endpoint documents its own 400 cases alongside the request/response shape.
  • See Authentication for what a 403 (auth or endpoint access failure) looks like.
  • Receive webhooks for events such as a care record being opened.