Skip to main content
Use this endpoint to record a clinical encounter for a patient. Encounters represent visits, interactions, or episodes of care. You must supply a status, a visit class (e.g. ambulatory or inpatient), and the patientId. Optionally link a practitioner, specify timing, location, and attach diagnosis codes.

​
Request

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

​
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
Encounter status. One of: planned, arrived, triaged, in-progress, onleave, finished, cancelled.
​
class
string
required
Visit class code. Use AMB (ambulatory), IMP (inpatient), EMER (emergency), HH (home health), or VR (virtual).
​
patientId
string
required
ID of the patient for this encounter.
​
practitionerId
string
ID of the practitioner responsible for the encounter.
​
type
string
Encounter type description. Maximum 200 characters.
​
serviceType
string
Service type (e.g. General Practice). Maximum 200 characters.
​
priority
string
Clinical priority. Maximum 50 characters.
​
reasonCode
string
Reason for the encounter. Maximum 500 characters.
​
period
object
Encounter time period.
​
lengthMinutes
integer
Duration of the encounter in minutes. Maximum 10080 (one week).
​
location
string
Location where the encounter took place. Maximum 200 characters.
​
serviceProvider
string
Providing organization name. Maximum 200 characters.
​
diagnosis
array
Diagnoses associated with this encounter. Maximum 20 items.

​
Response

Returns 201 Created with the new encounter resource.
​
data.id
string
Generated encounter ID.
​
data.status
string
Encounter status.
​
data.class
string
Visit class code.
​
data.patientId
string
Patient ID linked to this encounter.
​
meta
object
Standard response metadata.

​
Examples

​
curl

curl -X POST https://api.clinikapi.com/v1/encounters \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "finished",
    "class": "AMB",
    "patientId": "pt_abc123",
    "practitionerId": "prac_xyz789",
    "reasonCode": "Annual wellness visit",
    "period": {
      "start": "2025-01-15T09:00:00.000Z",
      "end": "2025-01-15T09:30:00.000Z"
    },
    "lengthMinutes": 30,
    "location": "Main Clinic — Room 3"
  }'

​
TypeScript SDK

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

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

const encounter = await client.encounters.create({
  status: "finished",
  class: "AMB",
  patientId: "pt_abc123",
  practitionerId: "prac_xyz789",
  reasonCode: "Annual wellness visit",
  period: {
    start: "2025-01-15T09:00:00.000Z",
    end: "2025-01-15T09:30:00.000Z",
  },
  lengthMinutes: 30,
});

console.log(encounter.data.id);