Skip to main content
Use this endpoint to book a new appointment for a patient. You must provide a status and the patientId. Optionally link a practitioner, specify the appointment window, service type, priority, and any patient instructions.

​
Request

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

​
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
Appointment status. One of: proposed, pending, booked, arrived, fulfilled, cancelled, noshow, checked-in, waitlist.
​
patientId
string
required
ID of the patient for this appointment.
​
practitionerId
string
ID of the practitioner assigned to this appointment.
​
start
string
Appointment start date-time in ISO 8601 format.
​
end
string
Appointment end date-time in ISO 8601 format.
​
minutesDuration
integer
Duration in minutes. Maximum 1440 (24 hours).
​
appointmentType
string
Type of appointment (e.g. ROUTINE, FOLLOWUP). Maximum 100 characters.
​
serviceType
string
Service type (e.g. General Practice). Maximum 200 characters.
​
serviceCategory
string
Service category. Maximum 200 characters.
​
specialty
string
Clinical specialty. Maximum 200 characters.
​
reasonCode
string
Reason for the appointment. Maximum 500 characters.
​
priority
integer
Scheduling priority (0 = lowest, 9 = highest).
​
description
string
Free-text description. Maximum 2000 characters.
​
comment
string
Internal scheduling comment. Maximum 2000 characters.
​
patientInstruction
string
Instructions for the patient (e.g. preparation steps). Maximum 2000 characters.
​
cancelationReason
string
Reason for cancellation, if applicable. Maximum 500 characters.

​
Response

Returns 201 Created with the new appointment resource.
​
data.id
string
Generated appointment ID.
​
data.status
string
Appointment status.
​
data.patientId
string
Patient ID.
​
data.start
string
Appointment start time.
​
meta
object
Standard response metadata.

​
Examples

​
curl

curl -X POST https://api.clinikapi.com/v1/appointments \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "booked",
    "patientId": "pt_abc123",
    "practitionerId": "prac_xyz789",
    "start": "2025-02-10T10:00:00.000Z",
    "end": "2025-02-10T10:30:00.000Z",
    "minutesDuration": 30,
    "appointmentType": "FOLLOWUP",
    "serviceType": "Cardiology",
    "reasonCode": "Post-procedure follow-up",
    "patientInstruction": "Please arrive 10 minutes early and bring your medication list."
  }'

​
TypeScript SDK

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

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

const appointment = await client.appointments.create({
  status: "booked",
  patientId: "pt_abc123",
  practitionerId: "prac_xyz789",
  start: "2025-02-10T10:00:00.000Z",
  end: "2025-02-10T10:30:00.000Z",
  minutesDuration: 30,
  appointmentType: "FOLLOWUP",
  serviceType: "Cardiology",
  reasonCode: "Post-procedure follow-up",
});

console.log(appointment.data.id);