> ## 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.
# Fetch Patients
> Performs a live fetch of patient data from the connected EMR system based on search criteria.
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`
* `problems`
* `medical_history`
* `labs`
* `labs.results` (orders plus discrete result values; implies `labs`)
* `tasks`
* `tasks.notes` (tasks plus attatched notes; implies `tasks`)
`tasks.notes` implies `tasks` — you do not need to pass both. Requesting `tasks.notes` makes an extra live fetch per task to pull its note history, so only request it when you need the notes.
### Example Request
```bash theme={null}
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", "problems", "medical_history", "labs.results"]
}'
```
### Response Data
Patient data includes comprehensive information including active medications and associated pharmacies:
```json theme={null}
{
"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",
"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": "3fa85f6457174562b3fc2c963f66afa6",
"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",
"problems": [
{
"id": "293199",
"icd10": "I10",
"icd_version": "10",
"name": "Essential (primary) hypertension",
"status": "confirmed",
"severity": "2",
"onset_date": "",
"added_date": "09/01/2025",
"provider_name": "Nguyen, Alice",
"encounter_id": "428763",
"notes": "",
"inactive": false
}
],
"medical_history": {
"vitals": [
{ "name": "BP", "date": "05/12/2025", "value": "120/80" },
{ "name": "HR", "date": "05/12/2025", "value": "70" }
],
"allergies": ["N.K.D.A"],
"surgical_history": [
{ "date": "2022", "reason": "Appendectomy" }
],
"hospitalization": [
{ "date": "2020", "reason": "Observation" }
],
"family_history": [
{ "relation": "Father", "description": "alive" },
{ "relation": "Mother", "description": "alive" }
],
"past_medical_history": ["Hypertension"],
"health_maintenance": [
{
"name": "Influenza",
"last_done": "01/01/2025",
"frequency": "1Y",
"due_date": "01/01/2026",
"status": "Compliant",
"notes": ""
}
]
},
"labs": {
"orders": [
{
"id": "519286",
"report_id": "519286",
"name": "CBC",
"type": 0,
"order_date": "05/12/2025",
"collection_date": "05/12/2025",
"result_date": "05/13/2025",
"ordering_physician": "Nguyen, Alice",
"interface_status": "Received",
"encounter_id": "461655",
"facility_id": "3",
"received": true,
"reviewed": false
}
],
"results": [
{
"name": "Metabolic Panel",
"result_date": "05/13/2025",
"analytes": [
{
"name": "Glucose",
"value": "95",
"units": "mg/dL",
"range": "70-99",
"loinc": "2345-7",
"previous_value": "",
"status": "F"
}
]
}
]
},
"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 | Cobalt appointment ID for the encounter |
| `ehr_appointment_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.
### Tasks Array
ModMed Gastro only. Returned only when `include` contains `tasks` (or `tasks.notes`). Each entry is a task from the patient's chart. ModMed Gastro models telephone encounters as tasks with `category: "Telephone Encounter"` — use `category` to distinguish task types. All task types are returned; filter client-side on `category` if you only want a subset.
| Field | Type | Description |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `emr_task_id` | string | The task's EMR ID. Use this value as `emr_task_id` when calling `POST /v1/tasks/notes`. |
| `follow_up_date` | string \| null | Follow-up date for the task |
| `status` | string \| null | Task status (e.g. `New`, `Complete`) |
| `tasking_id` | string \| null | Recipient tasking identifier |
| `priority` | string \| null | Task priority |
| `datetime` | string \| null | Task creation date/time |
| `subject` | string \| null | Task subject line |
| `recipients` | string \| null | Display names of the task recipients |
| `recipient_ids` | string \| null | Recipient identifiers |
| `category` | string \| null | Task type/category (e.g. `General`, `Telephone Encounter`) |
| `sent_by` | string \| null | Who the task was sent by |
| `notes` | array | Note history for the task. Present only when `include` contains `tasks.notes`. See below. |
#### Task Notes Array
Each task's `notes[]` (present only with `tasks.notes`) contains its note history, most recent first:
| Field | Type | Description |
| -------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `emr_note_id` | string | The note's EMR ID |
| `created_date` | string \| null | When the note was created |
| `description` | string \| null | Note body. ModMed Gastro prefixes the author, e.g. `"ACME Health AI Account - call back tomorrow"`. |
```json theme={null}
{
"tasks": [
{
"emr_task_id": "9bef4113-e9ce-4895-9a17-2c18cd625116",
"follow_up_date": "6/15/2026",
"status": "New",
"tasking_id": "3610210f-6f36-4cfc-b7b5-79fe7fc42d83",
"priority": "Normal",
"datetime": "6/15/2026 12:02 PM",
"subject": "Follow up call",
"recipients": "ACME Management",
"recipient_ids": "3610210f-6f36-4cfc-b7b5-79fe7fc42d83",
"category": "Telephone Encounter",
"sent_by": "ACME Health AI Account",
"notes": [
{
"emr_note_id": "f862b0a0-d820-418c-9e30-412bb62bde34",
"created_date": "6/15/2026 12:02 PM",
"description": "ACME Health AI Account - patient called back, scheduled for next week"
}
]
}
]
}
```
### 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:
```json theme={null}
{
"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"
}
]
}
}
```
## OpenAPI
````yaml POST /patients/fetch
openapi: 3.0.0
info:
title: Cobalt API
version: 1.0.1
description: API for interacting with Cobalt's EHR integration services
servers:
- url: https://api.usecobalt.com/v1
security:
- ClientCredentials: []
ClientSecret: []
AccessToken: []
paths:
/patients/fetch:
post:
summary: Fetch Patients
description: >-
Performs a live fetch of patient data from the connected EMR system
based on search criteria. This is an asynchronous operation that returns
results via webhook.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- search_by
properties:
search_by:
type: string
enum:
- dob
- name
- phone
- mrn
description: Identifies the search method or criteria being used.
dob:
type: string
format: date
description: Date of birth in ISO 8601 format (YYYY-MM-DD).
first_name:
type: string
description: Patient's first name.
last_name:
type: string
description: Patient's last name.
phone:
type: string
pattern: ^\d{3}-\d{3}-\d{4}$
description: Phone number in format XXX-XXX-XXXX (e.g., "555-123-4567").
mrn:
type: string
description: >-
Medical Record Number (MRN) to search for a specific
patient.
include:
description: >-
Optional related resources to include in the live-fetch
payload. Supports different values depending on your
connected EMR system:
**eClinicalWorks:** `insurances`, `problems`,
`medical_history`, `labs`, `labs.results` (orders plus
discrete result values; implies `labs`).
**Credible:** `insurances`, `documents`, `encounters`,
`episodes`, `notes`, `assessments`, `care_plans`,
`clinical_notes`.
**ModMed Gastro:** `tasks`, `tasks.notes` (implies `tasks`).
Only include values supported by your EMR — an unsupported
value will return a 400 error with the list of valid values
for your system. Accepts either a comma-delimited string or
an array of strings.
oneOf:
- type: string
example: problems,medical_history,labs.results
- type: array
items:
type: string
enum:
- insurances
- problems
- medical_history
- labs
- labs.results
- tasks
- tasks.notes
- documents
- encounters
- episodes
- notes
- assessments
- care_plans
- clinical_notes
example:
- insurances
- problems
- medical_history
- labs.results
responses:
'202':
description: Request accepted for processing
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
job_id:
type: string
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
components:
securitySchemes:
ClientCredentials:
type: apiKey
in: header
name: client_id
ClientSecret:
type: apiKey
in: header
name: client_secret
AccessToken:
type: apiKey
in: header
name: access_token
````