Live-fetch appointments
curl --request POST \
--url https://api.usecobalt.com/v1/appointments/fetch \
--header 'Content-Type: application/json' \
--header 'access_token: <api-key>' \
--header 'client_id: <api-key>' \
--header 'client_secret: <api-key>' \
--data '
{
"search_by": "date_range",
"start_date": "2026-06-15",
"end_date": "2026-06-15",
"mrn": "12345",
"provider_ids": [
"PROV-1"
],
"include": "ehr_audit_log",
"callback_urls": [
"https://example.com/webhooks/cobalt"
],
"expires_at": "2027-06-15T14:30:00Z"
}
'import requests
url = "https://api.usecobalt.com/v1/appointments/fetch"
payload = {
"search_by": "date_range",
"start_date": "2026-06-15",
"end_date": "2026-06-15",
"mrn": "12345",
"provider_ids": ["PROV-1"],
"include": "ehr_audit_log",
"callback_urls": ["https://example.com/webhooks/cobalt"],
"expires_at": "2027-06-15T14:30:00Z"
}
headers = {
"client_id": "<api-key>",
"client_secret": "<api-key>",
"access_token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
client_id: '<api-key>',
client_secret: '<api-key>',
access_token: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
search_by: 'date_range',
start_date: '2026-06-15',
end_date: '2026-06-15',
mrn: '12345',
provider_ids: ['PROV-1'],
include: 'ehr_audit_log',
callback_urls: ['https://example.com/webhooks/cobalt'],
expires_at: '2027-06-15T14:30:00Z'
})
};
fetch('https://api.usecobalt.com/v1/appointments/fetch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usecobalt.com/v1/appointments/fetch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'search_by' => 'date_range',
'start_date' => '2026-06-15',
'end_date' => '2026-06-15',
'mrn' => '12345',
'provider_ids' => [
'PROV-1'
],
'include' => 'ehr_audit_log',
'callback_urls' => [
'https://example.com/webhooks/cobalt'
],
'expires_at' => '2027-06-15T14:30:00Z'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"access_token: <api-key>",
"client_id: <api-key>",
"client_secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.usecobalt.com/v1/appointments/fetch"
payload := strings.NewReader("{\n \"search_by\": \"date_range\",\n \"start_date\": \"2026-06-15\",\n \"end_date\": \"2026-06-15\",\n \"mrn\": \"12345\",\n \"provider_ids\": [\n \"PROV-1\"\n ],\n \"include\": \"ehr_audit_log\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ],\n \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client_id", "<api-key>")
req.Header.Add("client_secret", "<api-key>")
req.Header.Add("access_token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/appointments/fetch")
.header("client_id", "<api-key>")
.header("client_secret", "<api-key>")
.header("access_token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"search_by\": \"date_range\",\n \"start_date\": \"2026-06-15\",\n \"end_date\": \"2026-06-15\",\n \"mrn\": \"12345\",\n \"provider_ids\": [\n \"PROV-1\"\n ],\n \"include\": \"ehr_audit_log\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ],\n \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecobalt.com/v1/appointments/fetch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"search_by\": \"date_range\",\n \"start_date\": \"2026-06-15\",\n \"end_date\": \"2026-06-15\",\n \"mrn\": \"12345\",\n \"provider_ids\": [\n \"PROV-1\"\n ],\n \"include\": \"ehr_audit_log\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ],\n \"expires_at\": \"2027-06-15T14:30:00Z\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Live fetch request accepted",
"job_id": 12345
}{
"success": false,
"message": "Bad request — missing or invalid parameters"
}{
"success": false,
"message": "Unauthorized — missing or invalid credentials"
}{
"success": false,
"message": "Internal server error"
}Appointments
Fetch Appointments
Performs a live fetch of appointment data from the connected EMR system by date range, patient MRN, or provider.
POST
/
appointments
/
fetch
Live-fetch appointments
curl --request POST \
--url https://api.usecobalt.com/v1/appointments/fetch \
--header 'Content-Type: application/json' \
--header 'access_token: <api-key>' \
--header 'client_id: <api-key>' \
--header 'client_secret: <api-key>' \
--data '
{
"search_by": "date_range",
"start_date": "2026-06-15",
"end_date": "2026-06-15",
"mrn": "12345",
"provider_ids": [
"PROV-1"
],
"include": "ehr_audit_log",
"callback_urls": [
"https://example.com/webhooks/cobalt"
],
"expires_at": "2027-06-15T14:30:00Z"
}
'import requests
url = "https://api.usecobalt.com/v1/appointments/fetch"
payload = {
"search_by": "date_range",
"start_date": "2026-06-15",
"end_date": "2026-06-15",
"mrn": "12345",
"provider_ids": ["PROV-1"],
"include": "ehr_audit_log",
"callback_urls": ["https://example.com/webhooks/cobalt"],
"expires_at": "2027-06-15T14:30:00Z"
}
headers = {
"client_id": "<api-key>",
"client_secret": "<api-key>",
"access_token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
client_id: '<api-key>',
client_secret: '<api-key>',
access_token: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
search_by: 'date_range',
start_date: '2026-06-15',
end_date: '2026-06-15',
mrn: '12345',
provider_ids: ['PROV-1'],
include: 'ehr_audit_log',
callback_urls: ['https://example.com/webhooks/cobalt'],
expires_at: '2027-06-15T14:30:00Z'
})
};
fetch('https://api.usecobalt.com/v1/appointments/fetch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usecobalt.com/v1/appointments/fetch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'search_by' => 'date_range',
'start_date' => '2026-06-15',
'end_date' => '2026-06-15',
'mrn' => '12345',
'provider_ids' => [
'PROV-1'
],
'include' => 'ehr_audit_log',
'callback_urls' => [
'https://example.com/webhooks/cobalt'
],
'expires_at' => '2027-06-15T14:30:00Z'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"access_token: <api-key>",
"client_id: <api-key>",
"client_secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.usecobalt.com/v1/appointments/fetch"
payload := strings.NewReader("{\n \"search_by\": \"date_range\",\n \"start_date\": \"2026-06-15\",\n \"end_date\": \"2026-06-15\",\n \"mrn\": \"12345\",\n \"provider_ids\": [\n \"PROV-1\"\n ],\n \"include\": \"ehr_audit_log\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ],\n \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client_id", "<api-key>")
req.Header.Add("client_secret", "<api-key>")
req.Header.Add("access_token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/appointments/fetch")
.header("client_id", "<api-key>")
.header("client_secret", "<api-key>")
.header("access_token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"search_by\": \"date_range\",\n \"start_date\": \"2026-06-15\",\n \"end_date\": \"2026-06-15\",\n \"mrn\": \"12345\",\n \"provider_ids\": [\n \"PROV-1\"\n ],\n \"include\": \"ehr_audit_log\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ],\n \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecobalt.com/v1/appointments/fetch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"search_by\": \"date_range\",\n \"start_date\": \"2026-06-15\",\n \"end_date\": \"2026-06-15\",\n \"mrn\": \"12345\",\n \"provider_ids\": [\n \"PROV-1\"\n ],\n \"include\": \"ehr_audit_log\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ],\n \"expires_at\": \"2027-06-15T14:30:00Z\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Live fetch request accepted",
"job_id": 12345
}{
"success": false,
"message": "Bad request — missing or invalid parameters"
}{
"success": false,
"message": "Unauthorized — missing or invalid credentials"
}{
"success": false,
"message": "Internal server error"
}This is a slow operation that fetches up-to-date appointment data directly from the EMR system. If the newest data is not critical, consider using the GET /appointments endpoint instead for faster results from cached data.
Search Modes
Date Range (default)
Fetches appointments for a date range (max 7 days). Results are synced to the database and returned via webhook.{
"start_date": "2025-01-01",
"end_date": "2025-01-07",
"include": ["ehr_audit_log"]
}
MRN
Fetches all appointments for a specific patient by MRN, enriched withcreated_at and created_by timestamps.
{
"search_by": "mrn",
"mrn": "12345"
}
Provider
Fetches appointments for one or more providers in a single EMR call. Results are synced to the database (scoped to the requested providers) and returned via webhook.provider_ids: required array of EMR provider IDs (max 10)- 1 provider:
end_datemay be up to 5 days afterstart_date - 2-10 providers:
start_datemust equalend_date
{
"search_by": "provider",
"start_date": "2025-01-01",
"end_date": "2025-01-05",
"provider_ids": ["prov_789", "prov_790"],
"include": ["progress_note", "schedule_blocks"]
}
Visit Notes
Where the EMR supports it, each appointment in the webhook has avisit_note_document_id: the Cobalt document ID of the encounter’s visit note.
Pass it to POST /documents/fetch to get the note
as a PDF. The same encounter has the same ID in the appointment and patient live
fetches.
Webhook Notifications
When the appointment fetch is complete, we will send a webhook to your registered endpoint.Date Range Webhook
When the request includesehr_audit_log, each appointment also carries created_at, created_by, and an ehr_audit_log array of every field change (who changed it, when, and old → new):
{
"id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
"access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
"job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
"object": "event",
"created": "2023-10-28T11:00:00Z",
"timestamp": "2023-10-28T11:00:00Z",
"type": "appointment.live_fetch_completed",
"action": "cobalt_operation",
"data": {
"success": true,
"appointment_count": 42,
"start_date": "2025-01-01",
"end_date": "2025-01-07",
"appointments": [
{
"id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"ehr_appointment_id": "12345678",
"datetime": "2025-01-15T10:00:00-05:00",
"duration": 30,
"appointment_type": "Office Visit",
"appointment_mode": null,
"status": "CHK (Check Out)",
"provider_ehr_id": "prov_789",
"provider_name": "Smith, Jane",
"provider_npi": "1234567890",
"location": "Main Office",
"patient_mrn": "85799",
"patient_first_name": "Alex",
"patient_last_name": "Doe",
"patient_dob": "1985-04-12",
"patient_gender": "M",
"patient_phone": "555-555-5555",
"patient_ehr_id": "PAT123",
"cobalt_patient_id": "bbbbbbbbccccddddeeeeffffffffffff",
"insurance": "Aetna",
"insurances": null,
"insurance_subscriber": null,
"insurance_number": "W123456789",
"insurance_group_number": null,
"secondary_insurance": null,
"secondary_insurance_number": null,
"diagnoses": null,
"created_at": "2025-01-10T09:15:22-05:00",
"created_by": "Doe, John",
"ehr_audit_log": [
{
"field_name": "Visit Status",
"old_value": "READY (Ready To Admit)",
"new_value": "CHK (Check Out)",
"action": "Modified",
"username": "Smith, Jane",
"timestamp": "2025-01-15T10:42:00-05:00"
},
{
"field_name": "Visit Status",
"old_value": "ARR (Check-in)",
"new_value": "READY (Ready To Admit)",
"action": "Modified",
"username": "Roe, Mary",
"timestamp": "2025-01-15T10:18:33-05:00"
},
{
"field_name": "Visit Status",
"old_value": "CON (Confirmed)",
"new_value": "ARR (Check-in)",
"action": "Modified",
"username": "Smith, Jane",
"timestamp": "2025-01-15T09:58:12-05:00"
},
{
"field_name": "Visit Status",
"old_value": "PEN (Pending)",
"new_value": "CON (Confirmed)",
"action": "Modified",
"username": "Doe, John",
"timestamp": "2025-01-11T14:05:40-05:00"
},
{
"field_name": "Visit Status",
"old_value": "",
"new_value": "PEN (Pending)",
"action": "Created",
"username": "Doe, John",
"timestamp": "2025-01-10T09:15:22-05:00"
}
]
}
]
}
}
MRN Webhook
{
"id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
"access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
"job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
"object": "event",
"created": "2023-10-28T11:00:00Z",
"timestamp": "2023-10-28T11:00:00Z",
"type": "appointment.live_fetch_completed",
"action": "cobalt_operation",
"data": {
"success": true,
"search_by": "mrn",
"mrn": "12345",
"appointment_count": 7,
"appointments": [
{
"ehr_appointment_id": "12345678",
"datetime": "2025-04-07T13:00:00.000-07:00",
"appointment_type": "OV (Office Visit)",
"status": "PEN (Pending)",
"provider_ehr_id": "prov_456",
"provider_first_name": "Jane",
"provider_last_name": "Smith",
"reason": "Annual Checkup",
"location": "Main Office",
"locked": false,
"created_at": "2025-02-20T07:52:02.000-08:00",
"created_by": "Doe, John"
}
]
}
}
Provider Webhook
Each appointment uses the same shape as the Date Range Webhook above.{
"id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
"access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
"job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
"object": "event",
"created": "2023-10-28T11:00:00Z",
"timestamp": "2023-10-28T11:00:00Z",
"type": "appointment.live_fetch_completed",
"action": "cobalt_operation",
"data": {
"success": true,
"search_by": "provider",
"provider_ids": ["prov_789", "prov_790"],
"start_date": "2025-01-01",
"end_date": "2025-01-05",
"appointment_count": 12,
"appointments": [
{
"id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"ehr_appointment_id": "12345678",
"datetime": "2025-01-02T10:00:00-05:00",
"duration": 30,
"appointment_type": "Office Visit",
"status": "CHK (Check Out)",
"provider_ehr_id": "prov_789",
"provider_name": "Smith, Jane",
"provider_npi": "1234567890",
"location": "Main Office",
"patient_mrn": "85799",
"patient_first_name": "Alex",
"patient_last_name": "Doe",
"patient_ehr_id": "PAT123",
"cobalt_patient_id": "bbbbbbbbccccddddeeeeffffffffffff",
"progress_note": "Progress Notes Patient: Doe, Alex DOB: 04/12/1985 PRISMA Summary: External Timeline: The patient has had 1 ER/Hospital visit at an outside facility. External Results: The patient has undergone labs including CBC. Subjective: Chief Complaint(s): Follow up. HPI: Doing well since last visit. Assessment: Hypertension. Treatment: Continue current medication. Follow Up: 3 months",
"schedule_block_label": null,
"schedule_block_color": null
},
{
"id": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3",
"ehr_appointment_id": "blk_98765",
"datetime": "2025-01-02T12:00:00-05:00",
"duration": 60,
"appointment_type": "schedule_block",
"status": null,
"provider_ehr_id": "prov_789",
"provider_name": "Smith, Jane",
"provider_npi": "1234567890",
"location": "Main Office",
"schedule_block_label": "LUNCH",
"schedule_block_color": "#FF9900"
}
]
}
}
Authorizations
Body
application/json
Search mode. Defaults to date_range.
Available options:
date_range, mrn, provider Example:
"date_range"
Start of the date range (YYYY-MM-DD). Required for date_range and provider modes.
Example:
"2026-06-15"
End of the date range (YYYY-MM-DD). Required for date_range and provider modes.
Example:
"2026-06-15"
Patient MRN. Required for mrn mode.
Example:
"12345"
EMR provider IDs (1-10). Required for provider mode.
Example:
["PROV-1"]
Additional data to enrich each appointment with, as a comma-separated string or an array of tokens. Works in every search mode. Accepted tokens depend on the EMR (see x-allowed-values-for-emrs). ehr_audit_log returns the appointment change history (who changed which field from what to what, and when) plus created_at and created_by; one log lookup per appointment. schedule_blocks also returns schedule block rows (appointment_type schedule_block, with schedule_block_label and schedule_block_color); not supported with search_by=mrn.
Available options:
ehr_audit_log, appointment_notes, referral, progress_note, insurances, schedule_blocks Example:
"ehr_audit_log"
URL(s) to receive the completion webhook for this live fetch.
Example:
["https://example.com/webhooks/cobalt"]
Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.
Example:
"2027-06-15T14:30:00Z"