Skip to main content

Transactional API Endpoints

Tim
Updated

Base URL

The base URLs for each environments are as follows.

Staging:

https://{{tenant_id}}.api.staging.england.medicus.health

Production:

https://{{tenant_id}}.api.england.medicus.health

Tenant ID is the Medicus tenant ID for the healthcare organisation. It is accessible from within their Medicus site.

 

Ping

GET {{base_url}}/transactional-api/ping

Intended use: Allow developers to test their connection to the API and/or maintain API health checks.

Supported authentication:

  • Application restricted
  • User restricted

Example response:

{
    "status": "ok",
    "timestamp": "2026-04-10T09:45:56Z",
    "application": {
        "identifier": "medicus-test",
        "name": "Medicus Test API Consumer"
    },
    "requestingOrganisation": {
        "organisationName": "Dr MA Baird's Practice",
        "organisationIdentifierType": "nhs-england-ods-code",
        "organisationIdentifierValue": "N82090"
    },
    "requestingPractitioner": null
}

 

Find Patient

POST {{base_url}}/transactional-api/find-patient

Intended use: Power a patient search/finder within the consumer application.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
  "query": "ani"
}

Example response:

[
    {
        "patientId": "8570a762-1f05-11ee-9f5d-0a58a9feac02",
        "displayName": "Mrs Anita Hardy",
        "nhsNumber": "9727989047",
        "dateOfBirth": "1961-04-18",
        "address": {
            "line1": "16 Bond Sreet",
            "line2": "High Moor",
            "locality": "Leeds",
            "administrativeArea": "West Yorkshire",
            "postalCode": "LS26 1AF",
            "country": "United Kingdom"
        },
        "genderIdentity": "Male",
        "active": true
    }
]

This endpoint also supports the following.

Date of birth (various formats):

{
  "query": "13/05/1992" 
}
{
  "query": "13.5.92"
}

NHS number:

{
  "query": "9691860929" 
}

This endpoint will return many results. Do not use it if your use case requires a single matching patient - use Match Patient instead.

Please note: If your use case requires knowledge of the PDS Sensitive Record / Restricted flag then this must be obtained directly from the PDS as the source of truth. See the PDS guidance on this for more information.

 

Match Patient

POST {{base_url}}/transactional-api/match-patient

Intended use: Retrieve the patient ID for a single patient.

Supported authentication:

  • Application restricted
  • User restricted

The endpoint either accepts NHS number, NHS number + demographics OR DOB first name and surname.

Example request [NHS number]:

{
  "nhsNumber": "9674965513"
}

Example request [NHS number, DOB and surname]:

{
  "dateOfBirth": "2016-07-03",
  "nhsNumber": "9674965513",
  "familyName": "hallam"
}

Example request [DOB, first name, surname]: 

{
  "dateOfBirth": "2016-07-03",
  "givenName": "cyril",
  "familyName": "hallam",
}

Example response:

{
    "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7"
}

 

Get Patient Demographics

GET {{base_url}}/transactional-api/patient/019ac994-3e6d-7352-8511-b3e2978a42c7/demographics

Intended use: Retrieve the demographic & contact details for a single patient.

Supported authentication:

  • Application restricted
  • User restricted

Example response:

{
    "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
    "officialName": {
        "prefix": "Mr",
        "givenName": "Cyril",
        "middleNames": "Edmond",
        "familyName": "Hallam"
    },
    "homeAddress": {
        "line2": "4 Main Street",
        "locality": "DOUNE",
        "postalCode": "FK16 6BJ",
        "country": "United Kingdom"
    },
    "dateOfBirth": "2016-07-03",
    "gender": "male",
    "nhsNumber": "9674965513",
    "homeTelephoneNumber": "+441599999888",
    "mobileTelephoneNumber": "+447799888666",
    "emailAddress": "cyril@medicus.health"
}

 

Retrieve Care Record

POST {{base_url}}/transactional-api/retrieve-care-record

Intended use: Retrieve the care record for a single patient.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
   "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7"
}

To align to common standards within the NHS, the API calls and response structure are identical to GP Connect Access Record Structured: https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-structured-fhir 

Please note: 

  • As per GP Connect rules, this endpoint will not return entries in the RCGP Exclusion List or that have been marked as "Confidential from Third Parties"
  • Documents outside of encounters are not included in this endpoint, if a list of documents is needed then use "List Documents"

 

List Documents

POST {{base_url}}/transactional-api/list-documents

Intended use: Retrieve all documents for a single patient.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
   "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7"
}

To align to common standards within the NHS, the API calls and response structure are identical to GP Connect Access Document: https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-document-fhir 

 

Retrieve Document

GET {{base_url}}/transactional-api/retrieve-document/Binary/document-019d5953-82bc-7000-b83f-458e60453cdb

Intended use: Retrieve the a document for a single patient when the document id is known from first making a request to Get Care Record or List Documents.

Supported authentication:

  • Application restricted (you must have first obtained the document ID)

Example request:

To align to common standards within the NHS, the API calls and response structure are identical to GP Connect Access Document: https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-document-fhir 

 

Create Coded Note

POST {{base_url}}/transactional-api/create-note

Intended use: Create basic coded entries in the patient's record e.g. "Smoker".

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
  "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
  "code": {
    "conceptId": "73211009",
    "description": "Diabetes mellitus"
  },
  "text": "Patient presented with elevated HbA1c levels. Discussed dietary changes and medication review.",
  "hiddenFromPatientFacingServices": false,
  "confidentialFromThirdParties": true,
  "recordDate": "2026-03-25"
}

Example response:

{
    "id": "019d76b2-f8cc-7164-b099-46e00fe8c2a2"
}

 

Create Observation

POST {{base_url}}/transactional-api/create-observation

Intended use: Create structured observation records such as blood pressure, height, weight.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
  "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
  "observationType": {
    "conceptId": "75367002",
    "description": "Blood pressure"
  },
  "bodySite": {
    "conceptId": "368208006",
    "description": "Left upper arm structure"
  },
  "interpretation": {
    "conceptId": "17621005",
    "description": "Normal"
  },
  "hiddenFromPatientFacingServices": false,
  "confidentialFromThirdParties": false,
  "recordDate": "2026-03-25",
  "observationDate": "2026-03-25",
  "observationTime": "15:02:00",
  "valueBloodPressure": {
    "systolic": 120,
    "diastolic": 80
  },
}

Example response:

{
    "id": "019d76b2-1645-72f4-863e-a414bd9c515f"
}

The possible value types are...

Coded:

  "valueCode": {
    "conceptId": "10828004",
    "description": "Positive"
  },

Quantity:

  "valueQuantity": {
    "value": 65.5,
    "unit": {
      "conceptId": "258683005",
      "description": "kg"
    }
  },

Blood pressure:

  "valueBloodPressure": {
    "systolic": 120,
    "diastolic": 80
  },

Date & time:

  "valueDateTime": "2025-04-25T12:42:00",

Date:

  "valueDate": "2025-04-25",

Free text string:

  "valueString": "Not detected."

Please ensure that you use the appropriate value for the type of observation (e.g. do not use a free text string for a weight).

 

Create Document

POST {{base_url}}/transactional-api/create-document

Intended use: Create documents in the patient's record.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
  "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
  "fileName": "discharge.docx",
  "title": "Discharge letter from ED",
  "contentType": "application/msword",
  "data": "UEsDBBQABgAIAAAAIQDfpNJsWgEAACAFAAATAAgCW0NvbnRlbnRfVHlwZXNdLnhtbCCiBAIooAAC...",
  "code": {
    "conceptId": "823701000000103",
    "description": "Discharge letter"
  },
  "clinicalSpecialty": {
    "conceptId": "773568002",
    "description": "Emergency medicine"
  },
  "hiddenFromPatientFacingServices": false,
  "confidentialFromThirdParties": true,
  "recordDate": "2026-03-25",
  "documentDate": "2026-03-25",
  "authorDepartment": "Emergency Department",
  "additionalInformation": "Lorem ipsum"
}

Example response:

{
    "id": "019d76b2-ab37-7169-8b8f-f0ebbdfab3f2"
}

 

Create Outbound Referral

POST {{base_url}}/transactional-api/create-outbound-referral

Intended use: Create referrals (including attachments) in the patient's record.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
  "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
  "code": {
    "conceptId": "308477009",
    "description": "Referral to psychiatrist"
  },
  "referredToOrganisation": {
    "name": "Psychiatrist & Co"
  },
  "referredToPractitioner": {
    "name": "Practitioner A"
  },
  "hiddenFromPatientFacingServices": false,
  "confidentialFromThirdParties": true,
  "referralDate": "2026-03-25",
  "ubrn": "123412341234",
  "additionalInformation": "Lorem ipsum",
  "priority": "urgent",
  "attachments": [
    {
      "fileName": "referral.docx",
      "contentType": "application/msword",
      "data": "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..."
    }
  ]
}

Example response:

{
    "id": "019d76b2-1645-72f4-863e-a414bd9c515f"
}

 

Create Encounter

POST {{base_url}}/transactional-api/create-encounter

Intended use: Create encounters in the patient's record.

Supported authentication:

  • Application restricted
  • User restricted

Example request:

{
  "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
  "startDate": "2026-04-12",
  "startTime": "12:10:00",
  "hiddenFromPatientFacingServices": false,
  "confidentialFromThirdParties": true,
  "encounterType": {
    "conceptId": "325861000000105",
    "description": "Face to face consultation"
  },
  "topics": [
    {
      "code": {
        "conceptId": "394700004",
        "description": "Asthma annual review"
      },
      "headings": [
        {
          "code": {
            "conceptId": "717121000000105",
            "description": "History"
          }
        },
        {
          "code": {
            "conceptId": "715851000000102",
            "description": "Examination findings"
          }
        },
        {
          "code": {
            "description": "Impression"
          }
        },
        {
          "code": {
            "conceptId": "717371000000107",
            "description": "Plan"
          }
        }
      ]
    }
  ]
}

Example response:

{
    "id": "019d8d47-6997-71a5-b4db-8a089b278a01",
    "topics": [
        {
            "id": "019d8d47-6d55-7269-9ead-04a21e26d8a3",
            "code": {
                "conceptId": "394700004",
                "description": "Asthma annual review"
            },
            "headings": [
                {
                    "id": "019d8d47-6f69-73df-8367-4bdf26070365",
                    "code": {
                        "conceptId": "717121000000105",
                        "description": "History"
                    }
                },
                {
                    "id": "019d8d47-7039-7120-9c53-454337369d4c",
                    "code": {
                        "conceptId": "715851000000102",
                        "description": "Examination findings"
                    }
                },
                {
                    "id": "019d8d47-7046-723f-b35f-45ff1fb7d256",
                    "code": {
                        "conceptId": null,
                        "description": "Impression"
                    }
                },
                {
                    "id": "019d8d47-7103-70b2-86f8-a17b2aa5bde8",
                    "code": {
                        "conceptId": "717371000000107",
                        "description": "Plan"
                    }
                }
            ]
        }
    ]
}

Consumers can then make additional API requests to add things to the encounter using the consultation topic heading ID:

{
  "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7",
  "code": {
    "conceptId": "73211009",
    "description": "Diabetes mellitus"
  },
  "text": "Patient presented with elevated HbA1c levels. Discussed dietary changes and medication review.",
  "hiddenFromPatientFacingServices": false,
  "confidentialFromThirdParties": true,
  "recordDate": "2026-03-25",
  "consultationTopicHeadingId": "019d8d47-6f69-73df-8367-4bdf26070365"
}

 

List Staff

GET {{base_url}}/transactional-api/list-staff

Intended use: List all active staff at a practice. For example, all of the staff that you would want to subscribe to webhook events for.

Supported authentication:

  • Application restricted
  • User restricted

Example response:

{
  "id": "c749d4f7-ef76-432a-a735-84f9d9dbc60f",
  "name": "John Smith",
  "username": "john.smith@medicus.health"
}

 

Find Appointment for Check-in

POST {{base_url}}/transactional-api/find-appointments-for-check-in

Intended use: Find any appointments for a single patient that are eligible for check-in. This endpoint is primarily used by kiosks and the application must have resolved the patient ID first.

Supported authentication:

  • Application restricted

Example request:

{
   "patientId": "019ac994-3e6d-7352-8511-b3e2978a42c7"
}

Note: This endpoint is a POST to allow for additional parameters later such as site to filter down the site or type of appointment.

The response will return any appointments for the patient ID where:

  • Appointment date is today

  • Start time is more than 5 minutes in the future (if known, i.e. some appointments are untimed)

  • Delivery mode is face-to-face

  • Status is pending and not already arrived

Example response:

{
  "appointmentId": "7c4e9a12-d3f6-4b8e-a1c7-f2d5e8b3c906",
  "startTime": "12:10",
  "siteName": "Main Surgery",
  "roomName": "Consulting Room 6",
  "patientCheckInInstructions": "Please go up the stairs next to reception and take a seat in the waiting room.",
  "practitionerName": "Dr Hannah Brown"
}

You can then use the appointment ID in a follow on request to check the patient in.

 

Mark Patient as Arrived

{{base_url}}/transactional-api/mark-patient-as-arrived

Intended use: Check a patient in for their appointment.

Supported authentication:

  • Application restricted

Example request:

{
  "appointmentId": "7c4e9a12-d3f6-4b8e-a1c7-f2d5e8b3c906"
}

The response is either 200, OK or an error (i.e. the appointment cannot be checked in if it would no longer be returned in the find appointments for check-in call).