Create Appointments

Creates a new appointment for a patient.

POST /appointments

Create Appointment

cURL

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

200

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

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.

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

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

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 · required

location · string · required

date · string · required

time · string · required

provider · string · required

type · string · required

secondary_provider · string

note · string

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

Response

200 - application/json

Successful response

success · boolean

message · string

appointment_id · string

job_id · integer