Skip to main content

Submitting Vital Sign Measurements

For product owners and partners: Use this page to understand how home-measured vital signs (e.g. blood pressure, weight, pulse rate) are submitted into the MediKIT API and turned into clinical Observation records.

For architects and developers: Use this page to implement the $create-vital-signs operation with the correct Parameters request shape, coding rules, and response handling.

Vital sign measurements are submitted as a FHIR R4 custom operation. Each request creates one or more Observation resources, category vital-signs, scoped to a single patient and organization.

What this endpoint is for​

Use $create-vital-signs when your product needs to submit measured vital signs such as:

  • home blood pressure, weight, or pulse-rate readings from a patient-facing app or connected device
  • staff-recorded vitals captured outside a full encounter workflow

Endpoint map​

Use caseEndpointNotes
Create vital sign ObservationsPOST /v2/{organizationId}/fhir/R4/Patient/{patientId}/Observation/$create-vital-signsBody is a Parameters resource

Required access​

Required scope​

  • observation.create-vital-signs

Request body​

The request body is a Parameters resource with the following top-level parts. No other top-level parameter names are accepted — an unrecognized parameter name is rejected.

ParameterRequiredRepeatableDescription
effective-date-timeYesNoA dateTime with timezone/offset information. Exactly one must be present.
measurementAt least one of measurement / composite-measurementYesA simple single-value measurement.
composite-measurementAt least one of measurement / composite-measurementYesA composite measurement made up of multiple component measurements (e.g. a blood pressure reading with systolic and diastolic values).

Each measurement occurrence must include:

  • code — a Coding identifying the measurement type. system must be one of the allowed code systems.
  • value — the measurement value, expressed as one of:
    • valueQuantity — a numeric value with a unit. system must be http://unitsofmeasure.org (UCUM) and unit must be present.
    • valueCodeableConcept — a coded value (e.g. a severity category).
    • valueBoolean — a true/false value.

Each composite-measurement occurrence must include:

  • code — a Coding identifying the composite measurement type, subject to the same code-system rule as above.
  • component — one or more parts, each holding a measurement sub-part with the same structure as the top-level measurement parameter.

Allowed code systems​

SystemNotes
http://loinc.orgLOINC
https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingenNHG table 45

Request size limit​

A single request may contain at most 150 measurements combined (measurement + composite-measurement occurrences). Exceeding this returns a validation error.

Request example​

Simple measurement (e.g. body weight)​

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "effective-date-time",
      "valueDateTime": "2024-01-15T10:30:00+01:00"
    },
    {
      "name": "measurement",
      "part": [
        {
          "name": "code",
          "valueCoding": {
            "system": "http://loinc.org",
            "code": "29463-7",
            "display": "Body weight"
          }
        },
        {
          "name": "value",
          "valueQuantity": {
            "value": 72.0,
            "unit": "kg",
            "system": "http://unitsofmeasure.org",
            "code": "kg"
          }
        }
      ]
    }
  ]
}

Composite measurement (e.g. blood pressure)​

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "effective-date-time",
      "valueDateTime": "2024-01-15T10:30:00+01:00"
    },
    {
      "name": "composite-measurement",
      "part": [
        {
          "name": "code",
          "valueCoding": {
            "system": "http://loinc.org",
            "code": "85354-9",
            "display": "Blood pressure panel"
          }
        },
        {
          "name": "component",
          "part": [
            {
              "name": "measurement",
              "part": [
                {
                  "name": "code",
                  "valueCoding": {
                    "system": "http://loinc.org",
                    "code": "8480-6",
                    "display": "Systolic blood pressure"
                  }
                },
                {
                  "name": "value",
                  "valueQuantity": {
                    "value": 120.0,
                    "unit": "mmHg",
                    "system": "http://unitsofmeasure.org",
                    "code": "mm[Hg]"
                  }
                }
              ]
            },
            {
              "name": "measurement",
              "part": [
                {
                  "name": "code",
                  "valueCoding": {
                    "system": "http://loinc.org",
                    "code": "8462-4",
                    "display": "Diastolic blood pressure"
                  }
                },
                {
                  "name": "value",
                  "valueQuantity": {
                    "value": 80.0,
                    "unit": "mmHg",
                    "system": "http://unitsofmeasure.org",
                    "code": "mm[Hg]"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Response shape​

Successful responses return a FHIR R4 Bundle (type: collection) containing the newly created Observation resources — one entry per measurement or composite-measurement submitted. Each observation has:

  • status: preliminary
  • category: vital-signs
  • subject set to the patient
  • performer set to the patient

Each request is persisted atomically: either all measurements are created, or none are.

Error behavior​

StatusScenario
403Client lacks observation.create-vital-signs scope or access to the requested patient context
422Missing/unrecognized parameters, invalid effective-date-time, no measurements provided, unsupported code system, non-UCUM quantity, or more than 150 measurements in one request
500The request was valid but could not be persisted