Skip to main content
Use this endpoint to create a structured clinical document with titled sections. Documents map to the FHIR Composition resource and are designed for multi-section records like discharge summaries, referral letters, and care plans — as distinct from single-block narrative notes. You must provide at minimum patientId, practitionerId, status, type, title, and at least one sections entry.

​
Request

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

​
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 this document belongs to (e.g. pt_abc123).
​
practitionerId
string
required
ID of the practitioner authoring the document (e.g. prac_def456).
​
status
string
required
Document status. One of: preliminary, final, amended.
​
type
string
required
Document type. Common values: discharge-summary, referral-letter, care-plan, operative-report, transfer-summary, consultation-report.
​
title
string
required
Human-readable document title (e.g. "Discharge Summary - Jane Doe - Jan 15, 2025").
​
sections
array
required
Ordered list of document sections. Each section requires at minimum a title and text.
​
encounterId
string
ID of the encounter associated with this document (e.g. enc_xyz789).
​
date
string
Document date in YYYY-MM-DD format. Defaults to the current date.
​
confidentiality
string
Confidentiality level. One of: N (Normal), R (Restricted), V (Very Restricted). Defaults to N.

​
Response

Returns 201 Created with the new document wrapped in the standard envelope.
​
data.id
string
Generated document ID (e.g. doc_abc123).
​
data.patientId
string
Patient ID the document is linked to.
​
data.practitionerId
string
Practitioner ID of the document author.
​
data.status
string
Document status (preliminary, final, or amended).
​
data.type
string
Document type as submitted.
​
data.title
string
Document title.
​
data.sections
array
Array of section objects as submitted.
​
data.confidentiality
string
Confidentiality level (N, R, or V).
​
data.date
string
Document date in YYYY-MM-DD format.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Examples

​
curl

curl -X POST https://api.clinikapi.com/v1/documents \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "final",
    "type": "discharge-summary",
    "patientId": "pt_abc123",
    "encounterId": "enc_xyz789",
    "practitionerId": "prac_def456",
    "title": "Discharge Summary - Jane Doe - Jan 15, 2025",
    "date": "2025-01-15",
    "confidentiality": "N",
    "sections": [
      { "title": "Chief Complaint", "code": "chief-complaint", "text": "Patient admitted for evaluation of acute chest pain." },
      { "title": "Hospital Course", "code": "hospital-course", "text": "Troponin negative x3. Stress test negative. Discharged in stable condition." },
      { "title": "Discharge Medications", "code": "medications", "text": "Continue aspirin 81mg daily.", "resourceIds": ["rx_aspirin"] },
      { "title": "Follow-up", "code": "follow-up", "text": "PCP: 1 week. Cardiology: 4 weeks." }
    ]
  }'

​
TypeScript SDK

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

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

const { data: doc } = await clinik.documents.create({
  status: 'final',
  type: 'discharge-summary',
  patientId: 'pt_abc123',
  encounterId: 'enc_xyz789',
  practitionerId: 'prac_def456',
  title: 'Discharge Summary - Jane Doe - Jan 15, 2025',
  date: '2025-01-15',
  confidentiality: 'N',
  sections: [
    { title: 'Chief Complaint', code: 'chief-complaint', text: 'Patient admitted for evaluation of acute chest pain.' },
    { title: 'Hospital Course', code: 'hospital-course', text: 'Troponin negative x3. Stress test negative. Discharged in stable condition.' },
    { title: 'Discharge Medications', code: 'medications', text: 'Continue aspirin 81mg daily.', resourceIds: ['rx_aspirin'] },
    { title: 'Follow-up', code: 'follow-up', text: 'PCP: 1 week. Cardiology: 4 weeks.' },
  ],
});

console.log(doc.id); // doc_abc123