If you get stuck at any point and need assistance, please don’t hesitate to message us in our shared communication channel (eg. Slack) or contact Bryan at bryan@usecobalt.com.
<aside>
❗ You need a client_id and client_secret to interact with the Cobalt API. You will also need an access_token for each user which can be obtained in through the Cobalt Link flow.
</aside>
The base URL to send all API requests is https://api.usecobalt.com/v1. HTTPS is required for all API requests.The API follows RESTful conventions when possible. Request and response bodies are encoded as JSON.
| Parameter | Type | Description |
|---|---|---|
| client_id | string | Your Cobalt API client id |
| client_secret | string | Your Cobalt API secret |
| access_token | string | The access token for the individual provider that was obtained during the Link flow |
Example request:
curl -X GET <https://api.usecobalt.com/v1/appointments\\>
-H 'Content-Type: application/json' \\
-H 'client_id: "%COBALT_CLIENT_ID%"' \\
-H 'client_secret: "%COBALT_CLIENT_SECRET%"' \\
-H 'access_token: "%USER_ACCESS_TOKEN%"' \\
-d '{
...
}'
The /appointments endpoint gets schedule data for a given clinic or provider.
| Parameter | Type | Required | Description |
|---|---|---|---|
| start_date | string | Yes | The start of the date range (ISO 8601 format) |
| end_date | string | Yes | The end of the date range (ISO 8601 format) |
| patient_mrn | string | No | The mrn of the the patient to filter appointments by. |
| patient_name | string | No | The name of the the patient to filter appointments by (case-insensitive, partial match) |
| patient_phone | string | No | The phone number of the the patient to filter appointments by. |
| include_note | string | No | Indicate whether progress notes should be included when available. Options are “true” or “false”. Default is “false” to reduce the transfer of PII when not needed. |
| appointment_mode | string | No | Filter by “office” or “telemedicine” appointments. Default is to include all appointments. |
Example request:
curl -X GET <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' \\
-G \\
--data-urlencode "start_date=2024-03-14" \\
--data-urlencode "end_date=2024-04-14"
Example response:
{
"success": true,
"results": {
"appointments": [
{
"id": "2109607",
"datetime": "2024-03-14T00:00:00-07:00",
"duration": 15,
"ehr_appointment_id": "536444",
"appointment_mode": "office",
"appointment_type": "f/u",
"location": "54252",
"patient_name": "Jane Doe",
"patient_mrn": "414421",
"patient_dob": "1994-08-12",
"patient_phone": "222-333-4444",
"patient_gender": "female",
"insurance": "Blue Shield",
"insurance_subscriber": "John Doe",
"insurance_number": "19228934",
"insurance_group_number": "FDL992829qe",
"provider_ehr_id": "6644",
"provider_npi": "2453453453",
"status": "completed"
},
...
],
}
}
The /appointment/{id} endpoint get an individual appointment.
Example request:
curl -X GET <https://api.usecobalt.com/v1/appointments/1276397812> \\
-H 'Content-Type: application/json' \\
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \\
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \\
-H 'access_token: 493JKLHIU98789hLKH9HHJH'
Example response:
{
"success": true,
"appointments": {
"id": "1276397812",
"datetime": "2024-03-14T00:00:00-07:00",
"appointment_mode": "office",
"appointment_type": "f/u",
"location": "54252",
"patient_name": "Jane Doe",
"patient_mrn": "414421",
"patient_dob": "1994-08-12",
"patient_sex": "female",
"insurance": "Blue Shield",
"insurance_subscriber": "John Doe",
"insurance_number": "19228934",
"insurance_group_number": "FDL992829qe",
"provider_ehr_id": "6644",
"provider_npi": "2453453453",
"status": "completed"
}
}
The /appointments endpoint creates a new appointment for a patient.
| Parameter | Type | Required | Description |
|---|---|---|---|
| mrn | string | Yes, if patient_name empty. | The MRN of the patient. One of mrn/patient_name is required. |
| patient_name | string | Yes, if mrn empty. | The first and last name of the patient (eg. “Jane Doe”). One of mrn/patient_name is required. |
| location | string | Yes | The location of the visit. |
| datetime | string | Yes | The date of the visit in ISO 8601 format (eg. "2024-03-14T00:00:00-07:00"). |
| date | string | ——— | DEPRECATED. The date of the visit (ISO 8601 format). |
| time | string | ——— | DEPRECATED. The time of the visit (HH:MM AM/PM). |
| duration | string | No | Th duration of the visit in minutes. If not included, the duration will use the default value for the appointment type in the EHR. |
| provider | string | Yes | The provider for the visit. |
| type | string | Yes | See table below for definitions. Use value from table in your request. |
| note | string | No | This can be any text that you want added to the appointment (eg. a note on symptoms discussed with the patient over the phone). |
| reason | string | No | This can be any text that you want to use to describe the reason for the appointment. |
Visit Type Options for eCW
| Value | Definition |
|---|---|
| bh pre-adm | Behavioral Health Pre-Admission |
| bh visit | Behavioral Health Admission & Treatment |
| f/u | Follow Up Visit |
| hosp | Hospital Follow up |
| hss | Home Sleep Study |
| mask | Mask Fitting |
| np | New Patient |
| nv | Nurse Visit |
| ovp | Overnight Pulse |
| pdr | PFT Dr Appointment |
| pft | Pulmonary Function Test |
| sk | SickLine |
| telephone | Televisit Phone |
| televisit | Televisit |
| televisit1 | Televisit / OSA |
| televisit2 | Televisit / Review Tests |
| televisit3 | TeleVisit / Discuss medications |
Visit Type Options for WebPT
| Value | Definition |
|---|---|
| f/u | Follow-Up |
| ie | Initial Examination |
| re | Re-Examination |
| c | Consultation |
| of | Orthosis Fabrication |
| ce | Calendar End |
| cs | Calendar Start |
| ava | Available |
| oth | Other |
| is | Injury Screen |
| te | Telehealth eval |
| tf | Telehealth followup |
| pel | Pelvic |
| tmj | TMJ |
| spe | Specialty |
| ope | Open |
| ct | Co Treat |
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": "9988776655443322",
"location": "Good Clinic",
"date": "2024-01-15",
"time": "1:30 PM",
"provider": "Good Doctor",
"type": "FollowUp"
}'
Example response:
{
"success": true,
"message": "Appointment created.",
"data": {
"appointment_id": "23456789"
}
}
The /appointments/{id} endpoint updates an existing appointment for a patient. The update process differs based on the current status of the appointment.
1. Updating Pending or Failed Appointments
For appointments with a status of 'pending' or 'failed', you can update any attribute of the appointment.
| --- | --- | --- | --- |
2. Updating Scheduled Appointments
For appointments with a status of 'scheduled', you can only update the status or note property.
| --- | --- | --- | --- |
Example request for updating a pending/failed appointment:
curl -X PATCH <https://api.usecobalt.com/v1/appointments/23456789> \\
-H 'Content-Type: application/json' \\
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \\
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \\
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \\
-d '{
"appointment_datetime": "2024-01-15T14:00:00-07:00",
"location": "New Clinic",
"type": "f/u"
}'
Example request for updating a scheduled appointment:
curl -X PATCH <https://api.usecobalt.com/v1/appointments/23456789> \\
-H 'Content-Type: application/json' \\
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \\
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \\
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \\
-d '{
"status": "cancelled"
}'
Example response for a successful update:
{
"success": true,
"message": "Appointment updated successfully.",
"appointment_id": "23456789"
}