Skip to main content
Use this endpoint to record a structured clinical assessment for a patient. Assessments map to the FHIR ClinicalImpression resource and capture overall clinical evaluations — coded findings, diagnoses, and summaries. You must provide at minimum patientId, status, and summary. Findings can be coded (ICD-10, SNOMED) or free-text.

​
Request

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

​
Headers

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

​
Body

​
patientId
string
required
ID of the patient being assessed (e.g. pt_abc123).
​
status
string
required
Assessment status. One of: in-progress, completed.
​
summary
string
required
Narrative clinical summary of the assessment findings and plan.
​
encounterId
string
ID of the encounter during which this assessment was made (e.g. enc_xyz789).
​
practitionerId
string
ID of the practitioner conducting the assessment (e.g. prac_def456).
​
description
string
Short description of the assessment context (e.g. "Annual wellness assessment").
​
findings
array
List of clinical findings. Each finding may include a code (ICD-10 or SNOMED) and a text description.
​
note
string
Additional clinician notes — follow-up instructions, plan details, or observations.
​
effectiveDateTime
string
ISO 8601 timestamp of when the assessment was conducted (e.g. "2025-01-15T10:00:00Z").

​
Response

Returns 201 Created with the new assessment wrapped in the standard envelope.
​
data.id
string
Generated assessment ID (e.g. assess_abc123).
​
data.patientId
string
Patient ID the assessment is linked to.
​
data.status
string
Assessment status (in-progress or completed).
​
data.summary
string
Clinical summary as submitted.
​
data.findings
array
Array of finding objects, each with optional code and text.
​
data.practitionerId
string
Practitioner ID, if provided.
​
data.encounterId
string
Encounter ID, if provided.
​
data.effectiveDateTime
string
Timestamp of when the assessment was conducted.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Examples

​
curl

curl -X POST https://api.clinikapi.com/v1/assessments \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "patientId": "pt_abc123",
    "encounterId": "enc_xyz789",
    "practitionerId": "prac_def456",
    "description": "Annual wellness assessment",
    "summary": "Patient presents with well-controlled hypertension and type 2 diabetes. No signs of end-organ damage.",
    "findings": [
      { "code": "I10", "text": "Essential hypertension — well controlled on lisinopril 10mg" },
      { "code": "E11.9", "text": "Type 2 diabetes mellitus — HbA1c 6.8%, at goal" }
    ],
    "note": "Follow up in 3 months. Order HbA1c and CMP at next visit.",
    "effectiveDateTime": "2025-01-15T10:00:00Z"
  }'

​
TypeScript SDK

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

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

const { data: assessment } = await clinik.assessments.create({
  status: 'completed',
  patientId: 'pt_abc123',
  encounterId: 'enc_xyz789',
  practitionerId: 'prac_def456',
  description: 'Annual wellness assessment',
  summary: 'Patient presents with well-controlled hypertension and type 2 diabetes. No signs of end-organ damage.',
  findings: [
    { code: 'I10', text: 'Essential hypertension — well controlled on lisinopril 10mg' },
    { code: 'E11.9', text: 'Type 2 diabetes mellitus — HbA1c 6.8%, at goal' },
  ],
  note: 'Follow up in 3 months. Order HbA1c and CMP at next visit.',
  effectiveDateTime: '2025-01-15T10:00:00Z',
});

console.log(assessment.id); // assess_abc123