Skip to main content
Use this endpoint to create a diagnostic report — a lab panel, radiology report, or pathology result. A lab report groups related observation IDs under a single coded report type and may include a free-text clinical conclusion, SNOMED conclusion codes, and attached PDF documents. Create your individual observations first, then reference their IDs in resultIds.

​
Request

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

​
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
Report status. One of: registered, partial, preliminary, final, amended, corrected, appended, cancelled.
​
code
string | object
required
LOINC panel code identifying the type of report. Pass a plain string or an object with system, code, and display (e.g. { system: "http://loinc.org", code: "24323-8", display: "Comprehensive metabolic panel" }).
​
patientId
string
required
The ID of the patient this report belongs to (e.g. pt_abc123).
​
category
string
Report category. One of: LAB (Laboratory), RAD (Radiology), PAT (Pathology).
​
encounterId
string
The encounter this report is associated with (e.g. enc_xyz789).
​
effectiveDateTime
string
ISO 8601 timestamp of the clinically relevant time (e.g. when the specimen was collected).
​
resultIds
string[]
Array of observation IDs whose results are included in this report (e.g. ["obs_glucose", "obs_sodium"]).
​
conclusion
string
Free-text clinical conclusion or interpretation.
​
conclusionCodes
array
Coded clinical findings (SNOMED CT). Array of objects with system, code, and display.
​
performer
string
ID of the practitioner who performed the diagnostic procedure.
​
resultsInterpreter
string
ID of the practitioner who interpreted the results.
​
specimenIds
string[]
IDs of specimen resources associated with this report.
​
presentedForm
array
Attached documents (e.g. PDF reports, images).

​
Response

Returns 201 Created with the new lab report resource wrapped in the standard envelope.
​
data.id
string
The generated lab report ID (e.g. lab_abc123).
​
data.status
string
Report status as submitted.
​
data.code
string | object
The LOINC report code.
​
data.patientId
string
Patient reference.
​
data.resultIds
string[]
Linked observation IDs.
​
data.conclusion
string
Clinical conclusion text, if provided.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Examples

​
curl

curl -X POST https://api.clinikapi.com/v1/labs \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "final",
    "code": {
      "system": "http://loinc.org",
      "code": "24323-8",
      "display": "Comprehensive metabolic 2000 panel"
    },
    "patientId": "pt_abc123",
    "encounterId": "enc_xyz789",
    "category": "LAB",
    "effectiveDateTime": "2025-01-15T10:30:00Z",
    "resultIds": ["obs_glucose", "obs_sodium", "obs_creatinine"],
    "conclusion": "All values within normal limits. No significant abnormalities.",
    "conclusionCodes": [
      {
        "system": "http://snomed.info/sct",
        "code": "281900007",
        "display": "No abnormality detected"
      }
    ]
  }'

​
TypeScript SDK

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

const { data } = await clinik.labs.create({
  status: 'final',
  code: {
    system: 'http://loinc.org',
    code: '24323-8',
    display: 'Comprehensive metabolic 2000 panel',
  },
  patientId: 'pt_abc123',
  encounterId: 'enc_xyz789',
  category: 'LAB',
  effectiveDateTime: '2025-01-15T10:30:00Z',
  resultIds: ['obs_glucose', 'obs_sodium', 'obs_creatinine'],
  conclusion: 'All values within normal limits. No significant abnormalities.',
  conclusionCodes: [
    {
      system: 'http://snomed.info/sct',
      code: '281900007',
      display: 'No abnormality detected',
    },
  ],
});

console.log(data.id); // lab_abc123