Skip to main content
Use this endpoint to record a clinical observation such as a vital sign, laboratory result, or measurement. You must supply a status, a LOINC or other code identifying the observation, and the patientId. The value can be a quantity (with unit), a string, or a coded concept.

​
Request

POST https://api.clinikapi.com/v1/observations

​
Headers

​
x-api-key
string
required
Your ClinikAPI secret key (clk_live_* or clk_test_*).
​
Content-Type
string
required
Must be application/json.

​
Body

​
status
string
required
Observation status. One of: registered, preliminary, final, amended, corrected, cancelled.
​
code
string | object
required
The observation type. Pass a string shorthand or a full { system, code, display } object (e.g. LOINC code 8867-4 for heart rate).
​
patientId
string
required
ID of the patient this observation belongs to.
​
encounterId
string
ID of the encounter during which this observation was made.
​
performerId
string
ID of the practitioner who performed the observation.
​
effectiveDateTime
string
When the observation was made, in ISO 8601 format.
​
category
string
Observation category. One of: vital-signs, laboratory, social-history, exam.
​
valueQuantity
object
Numeric observation value with unit.
​
valueString
string
String observation value (up to 2000 characters). Use when the value is free text.
​
valueCodeableConcept
object
Coded observation value.
​
interpretation
string
Clinical interpretation flag. One of: H (high), L (low), N (normal), A (abnormal), HH (critically high), LL (critically low).
​
referenceRange
object
Normal range for this observation.
​
component
array
Multi-component observations (e.g. blood pressure). Maximum 20 items, each with code and valueQuantity or valueString.
​
bodySite
string
Anatomical body site. Maximum 200 characters.
​
method
string
Observation method. Maximum 200 characters.
​
note
string
Additional notes. Maximum 2000 characters.

​
Response

Returns 201 Created with the new observation resource.
​
data.id
string
Generated observation ID.
​
data.status
string
Observation status.
​
data.code
object
The observation code.
​
data.patientId
string
Patient ID.
​
meta
object
Standard response metadata.

​
Examples

​
curl — heart rate vital sign

curl -X POST https://api.clinikapi.com/v1/observations \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "final",
    "code": { "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" },
    "patientId": "pt_abc123",
    "encounterId": "enc_def456",
    "category": "vital-signs",
    "effectiveDateTime": "2025-01-15T09:10:00.000Z",
    "valueQuantity": { "value": 72, "unit": "bpm" },
    "interpretation": "N",
    "referenceRange": {
      "low": { "value": 60, "unit": "bpm" },
      "high": { "value": 100, "unit": "bpm" }
    }
  }'

​
TypeScript SDK

import { ClinikAPI } from "@clinikapi/sdk";

const client = new ClinikAPI({ apiKey: "clk_live_abc123" });

const observation = await client.observations.create({
  status: "final",
  code: { system: "http://loinc.org", code: "8867-4", display: "Heart rate" },
  patientId: "pt_abc123",
  encounterId: "enc_def456",
  category: "vital-signs",
  effectiveDateTime: "2025-01-15T09:10:00.000Z",
  valueQuantity: { value: 72, unit: "bpm" },
  interpretation: "N",
});

console.log(observation.data.id);