POST/transactional-api/report-launch

Generate Report Launch URL

Runs a report against an ad hoc list of NHS numbers and/or Medicus patient IDs and returns a URL for a logged-in clinician to open it in Medicus. Population is always built by Medicus from the resolved identifiers; nothing about the report itself is ever saved, and the returned URL can be opened once.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/report-launch' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "nhsNumbers": [
      "9990000018"
    ],
    "patientIds": [],
    "title": "Overdue Reviews",
    "columns": [
      {
        "value": "patientName",
        "headerName": "Patient"
      },
      {
        "value": "patientNhsNumber",
        "headerName": "NHS Number"
      }
    ]
  }'

Body parameters

Field	Type	Required	Description
nhsNumbers	array<string> (nullable)	No	NHS numbers to include, alongside or instead of patientIds.
patientIds	array<string<uuid>> (nullable)	No	Medicus patient IDs to include, alongside or instead of nhsNumbers.
title	string (nullable)	No	Name shown as the report title in Medicus. Defaults to the requesting partner's name followed by "Report" if omitted.
columns	array<object>	Yes	Demographic fields to include. Each value one of: patientName, patientPrimaryIdentifier, patientUuid, patientNhsNumber, patientDateOfBirth, patientAge, patientGender, patientRegistrationType, patientRegistrationDate, patientCurrentRegistrationType, namedGP, homeAddress, homePhoneNumber, mobilePhoneNumber, emailAddress, currentRegistrationStartDate, dateOfDeath, prescriptionsDispensedByPractice, careHomeResident. Clinical/prescription/appointment columns are not supported yet: those only mean something paired with a real SNOMED/EMIS code list, which is out of scope for this endpoint.

Responses

200 Launch created.

Response fields

Field	Type	Description
launchUrl	string	Single-use URL for a clinician to open the report in Medicus.
unmatchedNhsNumbers	array<string>	Submitted NHS numbers that did not resolve to exactly one patient.
unmatchedPatientIds	array<string>	Submitted patient IDs that did not resolve to a patient.

{
  "launchUrl": "https://england.medicus.health/reporting/report-launch/view/4d59c916-9726-11ec-af3f-0a58a9feac02",
  "unmatchedNhsNumbers": [
    "string"
  ],
  "unmatchedPatientIds": [
    "string"
  ]
}

400 Validation error.

2 possible code values

Code	Description	When
too-many-identifiers	nhsNumbers and patientIds together must not exceed 10,000 entries.	nhsNumbers and patientIds together exceed 10,000 entries
invalid-columns	columns is invalid: Value 'notARealField' is not facet-valid with respect to enumeration 'demographicInformationValueType'.	a columns entry names a value outside demographicInformationValueType

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "too-many-identifiers",
      "description": "nhsNumbers and patientIds together must not exceed 10,000 entries."
    }
  ]
}