Skip to main content
POST
Create Appointment

Provider and Location IDs

When creating appointments, use the ehr_id values from your providers and locations:
  • provider: Use the ehr_id from GET /v1/providers (not the id)
  • location: Use the ehr_id from GET /v1/locations (not the id)
  • secondary_provider: Use the ehr_id from GET /v1/providers (not the id)
These values represent the identifiers your EMR system uses. Cobalt passes them directly to your EMR when creating the appointment.
Don’t use the Cobalt id here. The id field from GET responses is Cobalt’s internal UUID, used only for updating provider/location settings via PATCH endpoints.

Date and Time Formats

You have two options for specifying the appointment date and time: Use the datetime parameter with full ISO 8601 timestamp including timezone:
Format: YYYY-MM-DDTHH:mm:ss±HH:MM (24-hour time with timezone offset)

Option 2: Separate Date and Time

Use date and time parameters separately. Important: When using this option, the time must be in 12-hour format with am or pm.
Date Format: YYYY-MM-DD Time Format: h:mm am/pm or hh:mm am/pm (12-hour format, must include am/pm)
Common mistake: Using "time": "10:00" without am or pm will result in an error. Always include am or pm when using separate date and time parameters.

Preventing Double Bookings

Set prevent_double_booking to "true" to have Cobalt check the provider’s schedule for conflicts before submitting the appointment to your EHR. If the requested time slot overlaps with an existing patient visit or a schedule block, the appointment fails immediately with a descriptive error rather than being submitted.
Supported EMRs: eClinicalWorks, Practice Fusion. This field is accepted but ignored for all other EHR systems.
When a conflict is detected, you will receive an appointment.failed webhook with the conflict_type and conflict_details fields populated (see Failure Examples below).
If Cobalt is unable to check the provider’s schedule due to a network or EHR connectivity issue, the appointment proceeds normally rather than blocking. The conflict check is a best-effort safeguard.

Complete Example Request

Example Response

Webhook Notifications

When the appointment processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:

Success

Failure Examples

The appointment.failed webhook event includes a failure_reason and can contain additional fields in the data object depending on the cause of the failure. Patient Not Found:
Visit Type Not Found:
If the visit type is bookable in your EHR but not part of the resource’s configured visit type list (for example, visit types offered through availability slots), re-create the appointment with skip_visit_type_validation set to "true" and an explicit duration. Provider Not Found:
Schedule Block Conflict:
Appointment Conflict (Permission Denied):
Double Booking Conflict — Existing Patient Visit:
Double Booking Conflict — Schedule Block:
Generic Failure (Max Retries):

Authorizations

client_id
string
header
required
client_secret
string
header
required
access_token
string
header
required

Body

application/json
mrn
string
required
location
string
required
date
string
required
time
string
required
provider
string
required
type
string
required
secondary_provider
string
note
string
duration
string

Optional appointment duration in minutes, as a string of digits (e.g. "30"). Where the EHR supports it, this overrides the default visit-type duration.

reason
string
new_patient
enum<string>
Available options:
true,
false
prevent_double_booking
enum<string>

When set to "true", Cobalt checks the provider's schedule for conflicts before submitting the appointment to the EHR. If an overlap is detected with an existing patient visit or schedule block, the appointment fails immediately with a structured error rather than being submitted. Supported for eClinicalWorks and Practice Fusion; ignored for all other EHR systems. Defaults to no conflict check when omitted.

Available options:
true,
false
skip_visit_type_validation
enum<string>

eClinicalWorks only. When "true", skips the check that the visit type is configured for the selected provider/resource in the EHR. Use this for visit types that are bookable in the EHR (for example via availability slots) but not part of the resource's configured visit type list. Requires duration, since the visit type's configured duration cannot be read when validation is skipped. Defaults to "false".

Available options:
true,
false
department_id
string

eClinicalWorks only. The EHR department to book the appointment under, given as the ehr_id of a department from GET /v1/settings (the departments array; match the one whose location_ehr_id equals this appointment's location). Validated against the chosen location's departments; an invalid value is rejected with a 400. Ignored for other EHR systems.

non_billable
enum<string>

eClinicalWorks only. When "true", the created encounter is marked non-billable (no claim required). Ignored for other EHR systems.

Available options:
true,
false
recall_id
string

ModMed Gastro only. Links the created appointment to an existing recall (the recall id from GET /v1/recalls).

Response

200 - application/json

Successful response

success
boolean
message
string
appointment_id
string
job_id
integer