Skip to main content
POST
Live-fetch patients
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"]
Every include value:
  • insurances
  • problems
  • medical_history
  • labs
  • labs.results (orders plus discrete result values; implies labs)
  • sogi
  • support_persons (the patient’s support persons: name, relationship, emergency contact and HIPAA flags)
  • collections (returns collection_status)
  • alerts
  • referrals (the patient’s incoming, outgoing, and external referrals, each with diagnoses)
  • rx_logs (the patient’s sent-Rx log for all prescribers)
  • medications.full (full medication history instead of the active list; adds each medication’s linked assessment: assessment_id, assessment_icd10, assessment_name)
  • documents
  • encounters
  • encounters.details (adds each encounter’s duration in minutes; implies encounters)
  • encounters.appointment_notes (implies encounters)
  • encounters.referral (implies encounters)
  • encounters.all (full encounter history instead of the 50 most recent; implies encounters)
  • episodes
  • notes
  • assessments
  • care_plans
  • clinical_notes
  • medical
  • treatment_plan
  • point_of_care
  • tasks
  • tasks.notes (tasks plus attached notes; implies tasks)
  • all_pages (fetch every page of a name or dob search instead of just the first — see below)
Which of these the connected EMR accepts varies. The include field in the OpenAPI spec carries the accepted set per EMR under x-allowed-values-for-emrs.
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

A name or dob search returns a single page of matches. The page size is set by the EMR and can be as low as 20, so a common name, or a busy date of birth, can easily exceed one page. Add one secondary filter to narrow the results at the source:
  • Narrow a name search with dob (YYYY-MM-DD) or phone (222-333-4444).
  • Narrow a dob search with a name (first_name / last_name).
Only one secondary filter is allowed. The filter is applied by the EMR (it intersects both criteria server-side), so it reduces the result set rather than trimming it after the fact. A name plus a date of birth resolves to the same intersection whichever one you use as search_by. If the first page was still capped, the completion webhook returns has_more: true and a message telling you to narrow further. To fetch every page instead of narrowing, add include: ["all_pages"]. This makes one extra EMR call per page, so prefer a secondary filter when you can.

​
Response Data

Patient data includes comprehensive information including active medications and associated pharmacies:

​
Insurances Array

insurances is only returned when include contains insurances.
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

Each entry represents a guarantor on the patient’s account. Empty array if the lookup fails. 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

Contains the patient’s billing and global alerts. May be null if the alerts lookup fails.

​
Medications Array

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

​
Pharmacies Array

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

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

​
Documents Array

Documents in the patient’s chart. Field availability varies by EMR. The file itself is not included in the fetch. GET /documents/{id} returns 409 until the document has been fetched with POST /documents/fetch.

​
Tasks Array

Returned only when include contains tasks (or tasks.notes). Each entry is a task from the patient’s chart. Some EMRs model 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.

​
Task Notes Array

Each task’s notes[] (present only with tasks.notes) contains its note history, most recent first:

​
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:
has_more is true only when a name or dob search was capped and more matches exist (it is absent or false otherwise, and when include: ["all_pages"] fetched everything). message is present only when has_more is true. If some data could not be fetched because requests were rate limited, a successful result includes an issues array of { code, description } objects (for example EHR_RATE_LIMITED) and the results may be incomplete. A failed fetch sends success: false with an error message and, when a code is known, a reasons array of { code, description }. See Failure Codes.

Authorizations

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

Body

application/json
​
search_by
enum<string> | null

Search mode: name, dob, phone, or mrn.

Available options:
name,
dob,
phone,
mrn
Example:

"name"

​
first_name
string | null

Patient first name. At least one of first_name / last_name is required for name mode.

Example:

"Jane"

​
last_name
string | null

Patient last name.

Example:

"Doe"

​
dob
string<date> | null

Date of birth (YYYY-MM-DD). Required for dob mode.

Example:

"1980-01-15"

​
phone
string | null

Phone (222-333-4444). Required for phone mode.

Example:

"555-123-4567"

​
mrn
string | null

Medical Record Number. Required for mrn mode.

Example:

"12345"

​
include
enum<string>

Additional chart sections to enrich, as a comma-separated string or an array of tokens. Accepted tokens depend on the EMR (see x-allowed-values-for-emrs).

Available options:
insurances,
tasks,
tasks.notes,
collections,
alerts,
support_persons,
problems,
medical_history,
labs,
labs.results,
sogi,
medications,
medications.full,
referrals,
rx_logs,
documents,
encounters,
encounters.details,
encounters.appointment_notes,
encounters.referral,
encounters.all,
episodes,
notes,
assessments,
care_plans,
clinical_notes,
medical,
treatment_plan,
point_of_care,
all_pages,
inactive_patients
Example:

"insurances"

​
callback_urls

URL(s) to receive the results webhook for this live fetch, in addition to the account webhook.

Example:
​
expires_at
string<date-time> | null

Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.

Example:

"2027-06-15T14:30:00Z"

Response

Live-fetch request accepted; results delivered by webhook

​
success
boolean
required
Example:

true

​
message
string
required
Example:

"Patient live fetch queued"

​
job_id
Example:

12345