Skip to main content
POST
/
appointments
/
fetch
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": "2023-12-25",
  "end_date": "2023-12-25",
  "mrn": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "job_id": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
MRN

Fetches all appointments for a specific patient by MRN, enriched with created_at and created_by timestamps. 
{
    "search_by": "mrn",
    "mrn": "12345"
}

​
Webhook Notifications

When the appointment fetch is complete, we will send a webhook to your registered endpoint.

​
Date Range Webhook

{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "appointment.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "appointment_count": 42,
        "start_date": "2025-01-01",
        "end_date": "2025-01-07",
        "appointments": [
            {
                "id": "appt_123",
                "datetime": "2025-01-15T10:00:00-05:00",
                "appointment_type": "Office Visit",
                "status": "CHK (Check Out)",
                "provider_ehr_id": "prov_789",
                "location": "Main Office"
            }
        ]
    }
}

​
MRN Webhook

{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "appointment.live_fetch_completed",
    "action": "sync",
    "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"
            }
        ]
    }
}

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Body

application/json
​
search_by
enum<string>
default:date_range

Search mode. Use date_range (default) to fetch by date range, or mrn to fetch by patient MRN with appointment audit logs.

Available options:
date_range,
mrn
​
start_date
string<date>

Start date for the appointment range in ISO 8601 format (YYYY-MM-DD). Required when search_by is date_range.

​
end_date
string<date>

End date for the appointment range in ISO 8601 format (YYYY-MM-DD). Maximum range is 7 days. Required when search_by is date_range.

​
mrn
string

Patient Medical Record Number. Required when search_by is mrn.

Response

Request accepted for processing

​
success
boolean
​
message
string
​
job_id
string