Skip to main content
POST
/
appointments
Create 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": "<string>",
  "location": "<string>",
  "date": "<string>",
  "time": "<string>",
  "provider": "<string>",
  "type": "<string>",
  "secondary_provider": "<string>",
  "note": "<string>",
  "reason": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "appointment_id": "<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: 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.

​
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"
}'

​
Example Response

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

​
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 combination. Please update the visit type using the PATCH /v1/appointments/:id endpoint.",
        "visit_type": "Annual Wellness Visit"
    }
}
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"
    }
}
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
required
​
location
string
required
​
date
string
required
​
time
string
required
​
provider
string
required
​
type
string
required
​
secondary_provider
string
​
note
string
​
reason
string

Response

200 - application/json

Successful response

​
success
boolean
​
message
string
​
data
object