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 case	Endpoint	Notes
Create vital sign Observations	`POST /v2/{organizationId}/fhir/R4/Patient/{patientId}/Observation/$create-vital-signs`	Body 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.

Parameter	Required	Repeatable	Description
`effective-date-time`	Yes	No	A `dateTime` with timezone/offset information. Exactly one must be present.
`measurement`	At least one of `measurement` / `composite-measurement`	Yes	A simple single-value measurement.
`composite-measurement`	At least one of `measurement` / `composite-measurement`	Yes	A composite measurement made up of multiple component measurements (e.g. a blood pressure reading with systolic and diastolic values).

Each measurement occurrence has the following parts, and no others:

code (required): a Coding identifying the measurement type. system must be one of the allowed code systems.
value (required): 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.
comment (optional): a non-blank valueString holding the patient's own remark about the measurement. See Comments.

Each composite-measurement occurrence has the following parts, and no others:

code (required): a Coding identifying the composite measurement type, subject to the same code-system rule as above.
measurement (required, repeatable): one or more component measurements, each with a code and a value part following the rules above. A component measurement takes no comment.
comment (optional): a non-blank valueString holding the patient's own remark about the composite measurement as a whole. See Comments.

Comments

A comment carries a remark the patient wrote about their own measurement, for example "I weighed myself before lunch". It is placed on the measurement or composite-measurement it belongs to, and is returned as the created Observation's note:

"note": [
  {
    "text": "I weighed myself before lunch."
  }
]

Note that Observation.note.text is typed markdown, so characters such as * and # may be interpreted as markup by whatever displays the note.

A comment describes a whole measurement, so it cannot be placed on an individual component measurement inside a composite-measurement. Doing so is a validation error.

Allowed code systems

System	Notes
`http://loinc.org`	LOINC
`https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen`	NHG 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"
          }
        },
        {
          "name": "comment",
          "valueString": "I weighed myself before lunch."
        }
      ]
    }
  ]
}

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": "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]"
              }
            }
          ]
        },
        {
          "name": "comment",
          "valueString": "Measured after sitting quietly for ten minutes."
        }
      ]
    }
  ]
}

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
note holding the submitted comment, when one was given

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

Error behavior

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

What this endpoint is for​

Endpoint map​

Required access​

Required scope​

Request body​

Comments​

Allowed code systems​

Request size limit​

Request example​

Simple measurement (e.g. body weight)​

Composite measurement (e.g. blood pressure)​

Response shape​

Error behavior​

Related pages​