Fetch Patients

Performs a live fetch of patient data from the connected EMR system based on search criteria.

POST /patients/fetch

Fetch Patients

cURL

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 '
{
  "dob": "2023-12-25",
  "first_name": "<string>",
  "last_name": "<string>",
  "phone": "<string>",
  "mrn": "<string>",
  "include": "insurances"
}
'

202

{
  "success": true,
  "message": "<string>",
  "job_id": "<string>"
}

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.

Optional Includes

Use include to opt into additional live-fetch payloads. The API accepts either:

• a comma-delimited string, for example include: "insurances"
• an array of strings, for example include: ["insurances"]

Currently supported include values:

• insurances

Example Request

curl -X POST https://api.usecobalt.com/v1/patients/fetch \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "mrn": "MRN123456",
    "search_by": "mrn",
    "include": ["insurances"]
  }'

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": "[e-mail]",
    "insurance_name": "Blue Shield of California",
    "insurance_subscriber_number": "ABC123456789",
    "insurances": [
        {
            "emr_insurance_id": "51638",
            "priority": 1,
            "insurance_ehr_id": "733",
            "insurance_name": "Blue Shield of California",
            "insurance_subscriber_number": "ABC123456789",
            "group_id": "GRP12345",
            "plan_begin_date": "2025-01-01",
            "copayment": "25.00",
            "relationship_to_subscriber": "self",
            "guarantor_id": "123456",
            "is_guarantor_patient": true
        }
    ],
    "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
            }
        ]
    },
    "collection_status": "C",
    "guarantors": [
        {
            "id": "12345",
            "name": "John Smith",
            "dob": "1960-04-22",
            "relationship": "spouse",
            "is_guarantor_patient": false
        }
    ],
    "patient_balance": 0,
    "account_balance": 125.50
}

Insurances Array

insurances is only returned when include contains insurances. It is currently supported for eClinicalWorks.

Field	Type	Description
emr_insurance_id	string	Stable EMR insurance record ID. Use this value when calling PATCH /v1/patients/:patient_mrn/insurances/:emr_insurance_id.
priority	integer	EMR priority / sequence number for the insurance record
insurance_ehr_id	string	EMR-native carrier/company ID
insurance_name	string	Carrier name for this specific insurance record
insurance_subscriber_number	string	Subscriber/member number for this specific insurance record
group_id	string	Insurance group number
plan_begin_date	string	Coverage start date
copayment	string | null	Copayment value returned by the EMR
relationship_to_subscriber	string | null	Relationship to the subscriber
guarantor_id	string | null	EMR guarantor identifier associated with the insurance
is_guarantor_patient	boolean	Whether the guarantor is the patient

The top-level insurance_name and insurance_subscriber_number fields remain convenience fields on the patient object. When present, prefer insurances[] for record-specific insurance details and update targeting.

Guarantors Array

eClinicalWorks only. Each entry represents a guarantor on the patient’s account. Empty array if the lookup fails.

Field	Type	Description
id	string	Guarantor’s EMR patient ID (if the guarantor is also a patient)
name	string	Guarantor’s full name
dob	string	Date of birth
relationship	string	Relationship to the patient: self, spouse, child, or other
is_guarantor_patient	boolean	Whether 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.

Field	Type	Description
billing_alert	boolean	Whether a billing alert is set on the patient
billing_notes	string | null	Free-text notes attached to the billing alert
global_alerts	array	Global alerts; each has name, alert_type, notes, priority, expiry_date

Medications Array

Each patient includes an array of active medications with the following fields:

Field	Type	Description
name	string	Medication name
strength	string	Medication strength/dosage
frequency	string	How often to take the medication
start_date	string	Date medication was started (MM/DD/YYYY)
refills	string	Number of refills remaining
notes	string	Additional notes about the medication

Pharmacies Array

Each patient includes an array of associated pharmacies with the following fields:

Field	Type	Description
pharmacy_id	string	Pharmacy’s EMR ID
is_primary	string	Whether this is the patient’s primary pharmacy (“0” or “1”)
name	string	Pharmacy name
address	string	Pharmacy street address
city	string	Pharmacy city
state	string	Pharmacy state code
zip	string	Pharmacy ZIP code
phone	string	Pharmacy 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.

Field	Type	Description
id	string	Encounter ID in the EMR
date	string	Encounter date (YYYY-MM-DD)
start_time	string	Scheduled start time (HH:MM, 24-hour)
visit_type	string	EMR visit type code (e.g. OV for office visit, TEL for telephone encounter)
status	string	Encounter status (e.g. Checked Out, Scheduled)
provider_ehr_id	string	Rendering provider’s EMR ID
provider_first_name	string	Rendering provider’s first name
provider_last_name	string	Rendering provider’s last name
reason	string	Reason for visit
facility_name	string	Facility name
facility_id	string	Facility EMR ID
locked	string	Whether 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": [...],
                "document_folders": [...],
                "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.

include · string enum<string>[]

Optional related resources to include in the live-fetch payload. Currently supports only insurances. Accepts either a comma-delimited string or an array of strings.

Example:

"insurances"

Response

202

application/json

Request accepted for processing

success · boolean

message · string

job_id · string