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>",
  "provider_ids": [
    "<string>"
  ]
}
'
{
  "success": true,
  "message": "<string>",
  "job_id": "<string>"
}
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"
}

​
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_date may be up to 5 days after start_date
  • 2-10 providers: start_date must equal end_date
{
    "search_by": "provider",
    "start_date": "2025-01-01",
    "end_date": "2025-01-05",
    "provider_ids": ["prov_789", "prov_790"]
}

​
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": "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
            }
        ]
    }
}

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

​
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",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "appointment.live_fetch_completed",
    "action": "sync",
    "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"
            }
        ]
    }
}

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, mrn to fetch by patient MRN with appointment audit logs, or provider to fetch appointments scoped to one or more EMR providers.

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

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

​
end_date
string<date>

End date for the appointment range in ISO 8601 format (YYYY-MM-DD). For date_range, maximum range is 7 days. For provider, the range may be up to 5 days after start_date when exactly 1 provider is supplied; when 2-10 providers are supplied, end_date must equal start_date. Required when search_by is date_range or provider.

​
mrn
string

Patient Medical Record Number. Required when search_by is mrn.

​
provider_ids
string[]

Array of EMR provider IDs to fetch appointments for (max 10). Required when search_by is provider.

Required array length: 1 - 10 elements

Response

Request accepted for processing

​
success
boolean
​
message
string
​
job_id
string