POST
/
appointments
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>",
  "secondary_provider": "<string>",
  "type": "<string>",
  "note": "<string>"
}'
{
  "success": true,
  "message": "<string>",
  "data": {
    "appointment_id": "<string>"
  }
}

​
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",
    "provider": "123456789",
    "secondary_provider": "123456789",
    "type": "new_patient",
    "note": "This is a test appointment"
}'

​
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

Response

200 - application/json

Successful response

The response is of type object.