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 [email protected].

API

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

Conventions

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.

Authentication Headers

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

Endpoints

GET Appointments

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"
	        },
	        ...
        ],
    }
}

GET Appointment

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

POST Appointments

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

PATCH Appointments

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