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.
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"
}'
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"
}'
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."
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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."
}
}
