Skip to main content
POST
/
patients
/
fetch
Fetch Patients
curl --request POST \
  --url https://api.usecobalt.com/v1/patients/fetch \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "search_by": "dob",
  "dob": "2023-12-25",
  "first_name": "<string>",
  "last_name": "<string>",
  "phone": "<string>",
  "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 an async operation that fetches up-to-date patient data directly from the EMR system. If the newest data is not critical, consider using the GET /patients endpoint instead for faster results from cached data.

​
Response Data

Patient data includes comprehensive information including active medications and associated pharmacies: 
{
    "id": "pat_123",
    "mrn": "123456789",
    "first_name": "Jane",
    "last_name": "Smith",
    "middle_name": "Marie",
    "date_of_birth": "1985-03-15",
    "address_street": "123 Market St",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_zip": "94102",
    "phone": "415-555-1234",
    "cell_phone": "415-555-5678",
    "sex": "female",
    "email": "jane.smith@example.com",
    "insurance_name": "Blue Shield of California",
    "insurance_subscriber_number": "ABC123456789",
    "rendering_provider_id": "67890",
    "medications": [
        {
            "name": "Lisinopril",
            "strength": "10 MG",
            "frequency": "Once a day",
            "start_date": "2025-01-21",
            "encounter_date": "2025-01-21",
            "refills": "3",
            "notes": "Take with food"
        }
    ],
    "pharmacies": [
        {
            "pharmacy_ehr_id": "5001",
            "is_primary": "1",
            "name": "Walgreens Pharmacy",
            "address": "500 Geary St",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94102",
            "phone": "415-555-9000"
        }
    ],
    "encounters": [
        {
            "id": "987654",
            "date": "2025-10-14",
            "start_time": "09:30",
            "visit_type": "OV",
            "status": "Checked Out",
            "provider_ehr_id": "67890",
            "provider_first_name": "Alice",
            "provider_last_name": "Nguyen",
            "reason": "Follow-up",
            "facility_name": "Market Street Clinic",
            "facility_id": "12",
            "locked": "true"
        }
    ],
    "last_appointment_date": "2025-10-14",
    "alerts": {
        "billing_alert": false,
        "billing_notes": null,
        "global_alerts": [
            {
                "name": "Allergy: Penicillin",
                "alert_type": "Allergy",
                "notes": "Hives",
                "priority": "High",
                "expiry_date": null
            }
        ]
    },
    "guarantors": [
        {
            "id": "12345",
            "name": "John Smith",
            "dob": "1960-04-22",
            "relationship": "spouse",
            "is_guarantor_patient": false
        }
    ],
    "patient_balance": 0,
    "account_balance": 125.50
}

​
Guarantors Array

eClinicalWorks only. Each entry represents a guarantor on the patient’s account. Empty array if the lookup fails.
FieldTypeDescription
idstringGuarantor’s EMR patient ID (if the guarantor is also a patient)
namestringGuarantor’s full name
dobstringDate of birth
relationshipstringRelationship to the patient: self, spouse, child, or other
is_guarantor_patientbooleanWhether this guarantor is also the patient on the account
The top-level patient_balance and account_balance fields (numbers, in dollars) are returned alongside the guarantors. Both are null if the lookup fails.

​
Alerts Object

eClinicalWorks only. Contains the patient’s billing and global alerts. May be null if the alerts lookup fails.
FieldTypeDescription
billing_alertbooleanWhether a billing alert is set on the patient
billing_notesstring | nullFree-text notes attached to the billing alert
global_alertsarrayGlobal alerts; each has name, alert_type, notes, priority, expiry_date

​
Medications Array

Each patient includes an array of active medications with the following fields:
FieldTypeDescription
namestringMedication name
strengthstringMedication strength/dosage
frequencystringHow often to take the medication
start_datestringDate medication was started (MM/DD/YYYY)
refillsstringNumber of refills remaining
notesstringAdditional notes about the medication

​
Pharmacies Array

Each patient includes an array of associated pharmacies with the following fields:
FieldTypeDescription
pharmacy_idstringPharmacy’s EMR ID
is_primarystringWhether this is the patient’s primary pharmacy (“0” or “1”)
namestringPharmacy name
addressstringPharmacy street address
citystringPharmacy city
statestringPharmacy state code
zipstringPharmacy ZIP code
phonestringPharmacy phone number

​
Encounters Array

Each patient includes an array of encounters (past and upcoming appointments) returned by the EMR. Field availability varies by EMR and visit type.
FieldTypeDescription
idstringEncounter ID in the EMR
datestringEncounter date (YYYY-MM-DD)
start_timestringScheduled start time (HH:MM, 24-hour)
visit_typestringEMR visit type code (e.g. OV for office visit, TEL for telephone encounter)
statusstringEncounter status (e.g. Checked Out, Scheduled)
provider_ehr_idstringRendering provider’s EMR ID
provider_first_namestringRendering provider’s first name
provider_last_namestringRendering provider’s last name
reasonstringReason for visit
facility_namestringFacility name
facility_idstringFacility EMR ID
lockedstringWhether the encounter is locked ("true" / "false")
Telephone encounters (visit_type: "TEL") are enriched with additional fields including caller, message, actions, notes, assigned_to, answered_by, priority, and has_attachment. The top-level last_appointment_date field is derived from the encounters array and reflects the most recent appointment date for the patient.

​
Webhook Notifications

When the patient fetch is complete, we will send a webhook to your registered endpoint. Here is an example of what the webhook payload will look like: 
{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "patient.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "patient_count": 15,
        "patients": [
            {
                "id": "pat_123",
                "mrn": "123456789",
                "first_name": "Jane",
                "last_name": "Smith",
                "date_of_birth": "1985-03-15",
                "medications": [...],
                "pharmacies": [...],
                "encounters": [...],
                "last_appointment_date": "2025-10-14"
            }
        ]
    }
}

Authorizations

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

Body

application/json
​
search_by
enum<string>
required

Identifies the search method or criteria being used.

Available options:
dob,
name,
phone,
mrn
​
dob
string<date>

Date of birth in ISO 8601 format (YYYY-MM-DD).

​
first_name
string

Patient's first name.

​
last_name
string

Patient's last name.

​
phone
string

Phone number in format XXX-XXX-XXXX (e.g., "555-123-4567").

Pattern: ^\d{3}-\d{3}-\d{4}$
​
mrn
string

Medical Record Number (MRN) to search for a specific patient.

Response

Request accepted for processing

​
success
boolean
​
message
string
​
job_id
string