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>"
}
'
{
  "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.

​
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": "[email protected]",
    "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": "01/15/2025",
            "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"
        }
    ]
}

​
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

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

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
​
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").

Response

Request accepted for processing

​
success
boolean
​
message
string
​
job_id
string