Create Appointments - Documentation

Create an appointment

curl --request POST \
  --url https://api.usecobalt.com/v1/appointments \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "mrn": "12345",
  "patient_name": "Jane Doe",
  "location": "location-1",
  "datetime": "2026-06-15T14:30:00-07:00",
  "date": "2026-06-15",
  "time": "2:30 pm",
  "timezone": "America/Chicago",
  "provider": "provider-123",
  "secondary_provider": "provider-456",
  "type": "NP",
  "note": "Purpose of visit: Annual checkup",
  "duration": "30",
  "reason": "Annual checkup",
  "billing_note": "Copay collected at check-in",
  "complaint_type": "complaint-123",
  "practice_id": "practice-1",
  "department_id": "department-1",
  "recall_id": "recall-abc-123",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/appointments"

payload = {
    "mrn": "12345",
    "patient_name": "Jane Doe",
    "location": "location-1",
    "datetime": "2026-06-15T14:30:00-07:00",
    "date": "2026-06-15",
    "time": "2:30 pm",
    "timezone": "America/Chicago",
    "provider": "provider-123",
    "secondary_provider": "provider-456",
    "type": "NP",
    "note": "Purpose of visit: Annual checkup",
    "duration": "30",
    "reason": "Annual checkup",
    "billing_note": "Copay collected at check-in",
    "complaint_type": "complaint-123",
    "practice_id": "practice-1",
    "department_id": "department-1",
    "recall_id": "recall-abc-123",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mrn: '12345',
    patient_name: 'Jane Doe',
    location: 'location-1',
    datetime: '2026-06-15T14:30:00-07:00',
    date: '2026-06-15',
    time: '2:30 pm',
    timezone: 'America/Chicago',
    provider: 'provider-123',
    secondary_provider: 'provider-456',
    type: 'NP',
    note: 'Purpose of visit: Annual checkup',
    duration: '30',
    reason: 'Annual checkup',
    billing_note: 'Copay collected at check-in',
    complaint_type: 'complaint-123',
    practice_id: 'practice-1',
    department_id: 'department-1',
    recall_id: 'recall-abc-123',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/appointments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/appointments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'mrn' => '12345',
    'patient_name' => 'Jane Doe',
    'location' => 'location-1',
    'datetime' => '2026-06-15T14:30:00-07:00',
    'date' => '2026-06-15',
    'time' => '2:30 pm',
    'timezone' => 'America/Chicago',
    'provider' => 'provider-123',
    'secondary_provider' => 'provider-456',
    'type' => 'NP',
    'note' => 'Purpose of visit: Annual checkup',
    'duration' => '30',
    'reason' => 'Annual checkup',
    'billing_note' => 'Copay collected at check-in',
    'complaint_type' => 'complaint-123',
    'practice_id' => 'practice-1',
    'department_id' => 'department-1',
    'recall_id' => 'recall-abc-123',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/appointments"

	payload := strings.NewReader("{\n  \"mrn\": \"12345\",\n  \"patient_name\": \"Jane Doe\",\n  \"location\": \"location-1\",\n  \"datetime\": \"2026-06-15T14:30:00-07:00\",\n  \"date\": \"2026-06-15\",\n  \"time\": \"2:30 pm\",\n  \"timezone\": \"America/Chicago\",\n  \"provider\": \"provider-123\",\n  \"secondary_provider\": \"provider-456\",\n  \"type\": \"NP\",\n  \"note\": \"Purpose of visit: Annual checkup\",\n  \"duration\": \"30\",\n  \"reason\": \"Annual checkup\",\n  \"billing_note\": \"Copay collected at check-in\",\n  \"complaint_type\": \"complaint-123\",\n  \"practice_id\": \"practice-1\",\n  \"department_id\": \"department-1\",\n  \"recall_id\": \"recall-abc-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/appointments")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mrn\": \"12345\",\n  \"patient_name\": \"Jane Doe\",\n  \"location\": \"location-1\",\n  \"datetime\": \"2026-06-15T14:30:00-07:00\",\n  \"date\": \"2026-06-15\",\n  \"time\": \"2:30 pm\",\n  \"timezone\": \"America/Chicago\",\n  \"provider\": \"provider-123\",\n  \"secondary_provider\": \"provider-456\",\n  \"type\": \"NP\",\n  \"note\": \"Purpose of visit: Annual checkup\",\n  \"duration\": \"30\",\n  \"reason\": \"Annual checkup\",\n  \"billing_note\": \"Copay collected at check-in\",\n  \"complaint_type\": \"complaint-123\",\n  \"practice_id\": \"practice-1\",\n  \"department_id\": \"department-1\",\n  \"recall_id\": \"recall-abc-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/appointments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mrn\": \"12345\",\n  \"patient_name\": \"Jane Doe\",\n  \"location\": \"location-1\",\n  \"datetime\": \"2026-06-15T14:30:00-07:00\",\n  \"date\": \"2026-06-15\",\n  \"time\": \"2:30 pm\",\n  \"timezone\": \"America/Chicago\",\n  \"provider\": \"provider-123\",\n  \"secondary_provider\": \"provider-456\",\n  \"type\": \"NP\",\n  \"note\": \"Purpose of visit: Annual checkup\",\n  \"duration\": \"30\",\n  \"reason\": \"Annual checkup\",\n  \"billing_note\": \"Copay collected at check-in\",\n  \"complaint_type\": \"complaint-123\",\n  \"practice_id\": \"practice-1\",\n  \"department_id\": \"department-1\",\n  \"recall_id\": \"recall-abc-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "appointment_id": "<string>",
  "job_id": 123
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "appointment_id": null
}

{
  "success": false,
  "message": "<string>"
}

POST

appointments

Create an appointment

curl --request POST \
  --url https://api.usecobalt.com/v1/appointments \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "mrn": "12345",
  "patient_name": "Jane Doe",
  "location": "location-1",
  "datetime": "2026-06-15T14:30:00-07:00",
  "date": "2026-06-15",
  "time": "2:30 pm",
  "timezone": "America/Chicago",
  "provider": "provider-123",
  "secondary_provider": "provider-456",
  "type": "NP",
  "note": "Purpose of visit: Annual checkup",
  "duration": "30",
  "reason": "Annual checkup",
  "billing_note": "Copay collected at check-in",
  "complaint_type": "complaint-123",
  "practice_id": "practice-1",
  "department_id": "department-1",
  "recall_id": "recall-abc-123",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/appointments"

payload = {
    "mrn": "12345",
    "patient_name": "Jane Doe",
    "location": "location-1",
    "datetime": "2026-06-15T14:30:00-07:00",
    "date": "2026-06-15",
    "time": "2:30 pm",
    "timezone": "America/Chicago",
    "provider": "provider-123",
    "secondary_provider": "provider-456",
    "type": "NP",
    "note": "Purpose of visit: Annual checkup",
    "duration": "30",
    "reason": "Annual checkup",
    "billing_note": "Copay collected at check-in",
    "complaint_type": "complaint-123",
    "practice_id": "practice-1",
    "department_id": "department-1",
    "recall_id": "recall-abc-123",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mrn: '12345',
    patient_name: 'Jane Doe',
    location: 'location-1',
    datetime: '2026-06-15T14:30:00-07:00',
    date: '2026-06-15',
    time: '2:30 pm',
    timezone: 'America/Chicago',
    provider: 'provider-123',
    secondary_provider: 'provider-456',
    type: 'NP',
    note: 'Purpose of visit: Annual checkup',
    duration: '30',
    reason: 'Annual checkup',
    billing_note: 'Copay collected at check-in',
    complaint_type: 'complaint-123',
    practice_id: 'practice-1',
    department_id: 'department-1',
    recall_id: 'recall-abc-123',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/appointments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/appointments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'mrn' => '12345',
    'patient_name' => 'Jane Doe',
    'location' => 'location-1',
    'datetime' => '2026-06-15T14:30:00-07:00',
    'date' => '2026-06-15',
    'time' => '2:30 pm',
    'timezone' => 'America/Chicago',
    'provider' => 'provider-123',
    'secondary_provider' => 'provider-456',
    'type' => 'NP',
    'note' => 'Purpose of visit: Annual checkup',
    'duration' => '30',
    'reason' => 'Annual checkup',
    'billing_note' => 'Copay collected at check-in',
    'complaint_type' => 'complaint-123',
    'practice_id' => 'practice-1',
    'department_id' => 'department-1',
    'recall_id' => 'recall-abc-123',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/appointments"

	payload := strings.NewReader("{\n  \"mrn\": \"12345\",\n  \"patient_name\": \"Jane Doe\",\n  \"location\": \"location-1\",\n  \"datetime\": \"2026-06-15T14:30:00-07:00\",\n  \"date\": \"2026-06-15\",\n  \"time\": \"2:30 pm\",\n  \"timezone\": \"America/Chicago\",\n  \"provider\": \"provider-123\",\n  \"secondary_provider\": \"provider-456\",\n  \"type\": \"NP\",\n  \"note\": \"Purpose of visit: Annual checkup\",\n  \"duration\": \"30\",\n  \"reason\": \"Annual checkup\",\n  \"billing_note\": \"Copay collected at check-in\",\n  \"complaint_type\": \"complaint-123\",\n  \"practice_id\": \"practice-1\",\n  \"department_id\": \"department-1\",\n  \"recall_id\": \"recall-abc-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/appointments")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mrn\": \"12345\",\n  \"patient_name\": \"Jane Doe\",\n  \"location\": \"location-1\",\n  \"datetime\": \"2026-06-15T14:30:00-07:00\",\n  \"date\": \"2026-06-15\",\n  \"time\": \"2:30 pm\",\n  \"timezone\": \"America/Chicago\",\n  \"provider\": \"provider-123\",\n  \"secondary_provider\": \"provider-456\",\n  \"type\": \"NP\",\n  \"note\": \"Purpose of visit: Annual checkup\",\n  \"duration\": \"30\",\n  \"reason\": \"Annual checkup\",\n  \"billing_note\": \"Copay collected at check-in\",\n  \"complaint_type\": \"complaint-123\",\n  \"practice_id\": \"practice-1\",\n  \"department_id\": \"department-1\",\n  \"recall_id\": \"recall-abc-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/appointments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mrn\": \"12345\",\n  \"patient_name\": \"Jane Doe\",\n  \"location\": \"location-1\",\n  \"datetime\": \"2026-06-15T14:30:00-07:00\",\n  \"date\": \"2026-06-15\",\n  \"time\": \"2:30 pm\",\n  \"timezone\": \"America/Chicago\",\n  \"provider\": \"provider-123\",\n  \"secondary_provider\": \"provider-456\",\n  \"type\": \"NP\",\n  \"note\": \"Purpose of visit: Annual checkup\",\n  \"duration\": \"30\",\n  \"reason\": \"Annual checkup\",\n  \"billing_note\": \"Copay collected at check-in\",\n  \"complaint_type\": \"complaint-123\",\n  \"practice_id\": \"practice-1\",\n  \"department_id\": \"department-1\",\n  \"recall_id\": \"recall-abc-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "appointment_id": "<string>",
  "job_id": 123
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "appointment_id": null
}

{
  "success": false,
  "message": "<string>"
}

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:

Option 1: ISO 8601 Format (Recommended)

Use the datetime parameter with full ISO 8601 timestamp including timezone:

curl -X POST https://api.usecobalt.com/v1/appointments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "mrn": "123456789",
    "location": "123456789",
    "datetime": "2025-01-01T10:00:00-05:00",
    "provider": "123456789",
    "type": "new_patient"
}'

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.

curl -X POST https://api.usecobalt.com/v1/appointments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "mrn": "123456789",
    "location": "123456789",
    "date": "2025-01-01",
    "time": "10:00 am",
    "provider": "123456789",
    "type": "new_patient"
}'

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.

Booking Timezone (eClinicalWorks)

By default the appointment time is interpreted in the account’s timezone. For eClinicalWorks instances whose facilities span multiple timezones, pass an optional timezone (IANA name) to book the appointment at that facility’s local wall-clock time. The time you send (via datetime or date and time) is then treated as local to that zone.

curl -X POST https://api.usecobalt.com/v1/appointments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "mrn": "123456789",
    "location": "123456789",
    "date": "2025-01-01",
    "time": "9:20 am",
    "timezone": "America/Chicago",
    "provider": "123456789",
    "type": "new_patient"
}'

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.

curl -X POST https://api.usecobalt.com/v1/appointments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "mrn": "123456789",
    "location": "123456789",
    "datetime": "2025-01-01T10:00:00-05:00",
    "provider": "123456789",
    "type": "follow_up",
    "prevent_double_booking": "true"
}'

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

curl -X POST https://api.usecobalt.com/v1/appointments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "mrn": "123456789",
    "location": "123456789",
    "date": "2025-01-01",
    "time": "10:00 am",
    "provider": "123456789",
    "secondary_provider": "123456789",
    "type": "new_patient",
    "note": "This is a test appointment",
    "reason": "Patient requested appointment for routine checkup",
    "department_id": "1",
    "non_billable": "false"
}'

Example Response

{
    "success": true,
    "message": "Appointment processing. A webhook event will be sent upon completion.",
    "appointment_id": "123456789",
    "job_id": 15550942
}

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

{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:00:00Z",
    "type": "appointment.created",
    "data": {
        "appointment_id": "123456789",
        "date_time": "2025-01-01T10:00",
        "timezone": "America/New_York",
        "provider_id": "emr_prov_123",
        "secondary_provider_id": "emr_sec_prov_456",
        "provider_name": "Dr. Smith",
        "mrn": "123456789"
    }
}

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:

{
    "id": "evt_1J9X2q2eZvKYlo2Cwxyz",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:05:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456790",
        "mrn": "000000",
        "failure_reason": "Patient MRN '000000' not found in eCW. Please update the MRN using the PATCH /v1/appointments/:id endpoint."
    }
}

Visit Type Not Found:

{
    "id": "evt_1J9X2q2eZvKYlo2Cabcde",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:10:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456791",
        "mrn": "123456789",
        "failure_reason": "Visit type \"Annual Wellness Visit\" not available for the selected resource/provider/location combination in eCW. Allowed visit types for this resource: New Patient, Follow Up, Telehealth. Please update the visit type using the PATCH /v1/appointments/:id endpoint, or re-create with skip_visit_type_validation: \"true\" if this visit type is bookable in eCW (e.g. via availability slots).",
        "visit_type": "Annual Wellness Visit",
        "allowed_visit_types": ["New Patient", "Follow Up", "Telehealth"]
    }
}

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:

{
    "id": "evt_1J9X2q2eZvKYlo2Cfghij",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:15:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456792",
        "mrn": "123456789",
        "failure_reason": "Provider 'Dr. Unknown' not found in eCW. Please check the provider configuration or use PATCH /v1/appointments/:id endpoint to update.",
        "provider_name": "Dr. Unknown"
    }
}

Schedule Block Conflict:

{
    "id": "evt_1J9X2q2eZvKYlo2Cklmno",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:20:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456793",
        "mrn": "123456789",
        "failure_reason": "Appointment creation failed: The appointment conflicts with a schedule block (Admin Block 9am-12pm). Permission denied. Please choose a different time or resolve the schedule conflict.",
        "conflict_type": "schedule_block",
        "block_details": "Admin Block 9am-12pm"
    }
}

Appointment Conflict (Permission Denied):

{
    "id": "evt_1J9X2q2eZvKYlo2Cpqrst",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:25:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456794",
        "mrn": "123456789",
        "failure_reason": "Appointment creation failed: This appointment conflicts with another existing appointment. Permission denied. Please choose a different time.",
        "conflict_type": "appointment_conflict"
    }
}

Double Booking Conflict — Existing Patient Visit:

{
    "id": "evt_1J9X2q2eZvKYlo2Cuvwxy",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:28:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456796",
        "patient_mrn": "123456789",
        "failure_reason": "Provider already has an appointment with Doe, Jane from 10:00 AM to 10:15 AM",
        "conflict_type": "existing_patient_visit",
        "conflict_details": {
            "patient_name": "Doe, Jane",
            "start_time": "10:00 AM",
            "end_time": "10:15 AM",
            "visit_type": "F/U"
        }
    }
}

Double Booking Conflict — Schedule Block:

{
    "id": "evt_1J9X2q2eZvKYlo2Cuvwxz",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:29:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456797",
        "patient_mrn": "123456789",
        "failure_reason": "Provider has a scheduled block (Admin Block) from 9:00 AM to 12:00 PM",
        "conflict_type": "scheduled_block",
        "conflict_details": {
            "block_description": "Admin Block",
            "start_time": "9:00 AM",
            "end_time": "12:00 PM"
        }
    }
}

Generic Failure (Max Retries):

{
    "id": "evt_1J9X2q2eZvKYlo2Cuvwxyz",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "object": "event",
    "created": "2023-10-28T11:30:00Z",
    "type": "appointment.failed",
    "data": {
        "appointment_id": "123456795",
        "mrn": "123456789",
        "failure_reason": "Appointment creation failed after 3 attempts. Last error: Some internal error message. Please check logs or contact support."
    }
}

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Body

application/json

mrn

string

Patient MRN. One of mrn or patient_name is required (bespoke check).

Example:

"12345"

patient_name

string

Patient name, used when the MRN is not known.

Example:

"Jane Doe"

location

string

EMR location ID. Validated against the account's locations.

Example:

"location-1"

datetime

string<date-time>

Appointment start as an ISO 8601 datetime. Provide either datetime, or date and time.

Example:

"2026-06-15T14:30:00-07:00"

date

string<date>

Appointment date (YYYY-MM-DD). Used together with time.

Example:

"2026-06-15"

time

string

Appointment time (h:mm am/pm). Used together with date.

Example:

"2:30 pm"

timezone

string

IANA time zone name (e.g. "America/Chicago") to book the appointment in, overriding the account timezone. Use for eClinicalWorks instances whose facilities span multiple time zones: the datetime (or date and time) is interpreted in this zone and booked at that exact facility-local wall-clock time. Omit to use the account timezone.

Example:

"America/Chicago"

provider

string

Rendering provider EMR ID. Validated against the account's providers.

Example:

"provider-123"

secondary_provider

string

Secondary provider / resource EMR ID.

Example:

"provider-456"

type

string

Visit type code. Validated against the account's visit types.

Example:

"NP"

note

string

Appointment note as a plain string.

Example:

"Purpose of visit: Annual checkup"

duration

Appointment duration in minutes, as a positive integer.

Example:

"30"

reason

string

Reason for the visit.

Example:

"Annual checkup"

billing_note

string

Billing note to set on the appointment. Read it back with the appointment_notes include on the fetch endpoints.

Example:

"Copay collected at check-in"

check_eligibility

enum<string>

Whether to run an eligibility check on creation.

Available options:

true,

false

complaint_type

string

Complaint type ID. Validated against the account's complaint types.

Example:

"complaint-123"

prevent_double_booking

enum<string>

Whether to reject the appointment if the slot is already booked.

Available options:

true,

false

skip_visit_type_validation

enum<string>

Skip visit-type validation. Requires duration, since the visit type is not read.

Available options:

true,

false

new_patient

enum<string>

Whether the patient is new.

Available options:

true,

false

practice_id

eClinicalWorks practice ID (for multi-practice provider/location pairs).

Example:

"practice-1"

department_id

eClinicalWorks department ID, validated against the synced departments.

Example:

"department-1"

non_billable

enum<string>

Whether the appointment is non-billable.

Available options:

true,

false

recall_id

string

Cobalt recall ID to link the new appointment to (from GET /v1/recalls).

Example:

"recall-abc-123"

callback_urls

URL(s) to receive the completion webhook for this appointment, in addition to the account webhook.

Example:

["https://example.com/webhooks/cobalt"]

Response

Appointment queued for creation

success

boolean

required

message

string

required

appointment_id

string

required

job_id

integer

​Provider and Location IDs

​Date and Time Formats

​Option 1: ISO 8601 Format (Recommended)

​Option 2: Separate Date and Time

​Booking Timezone (eClinicalWorks)

​Preventing Double Bookings

​Complete Example Request

​Example Response

​Webhook Notifications

​Success

​Failure Examples

Authorizations

Body

Response

Provider and Location IDs

Date and Time Formats

Option 1: ISO 8601 Format (Recommended)

Option 2: Separate Date and Time

Booking Timezone (eClinicalWorks)

Preventing Double Bookings

Complete Example Request

Example Response

Webhook Notifications

Success

Failure Examples