Fetch Patients - Documentation

Live-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 '
{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1980-01-15",
  "phone": "555-123-4567",
  "mrn": "12345",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/patients/fetch"

payload = {
    "first_name": "Jane",
    "last_name": "Doe",
    "dob": "1980-01-15",
    "phone": "555-123-4567",
    "mrn": "12345",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Doe',
    dob: '1980-01-15',
    phone: '555-123-4567',
    mrn: '12345',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/patients/fetch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/patients/fetch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'dob' => '1980-01-15',
    'phone' => '555-123-4567',
    'mrn' => '12345',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/patients/fetch"

	payload := strings.NewReader("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"dob\": \"1980-01-15\",\n  \"phone\": \"555-123-4567\",\n  \"mrn\": \"12345\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/patients/fetch")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"dob\": \"1980-01-15\",\n  \"phone\": \"555-123-4567\",\n  \"mrn\": \"12345\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/patients/fetch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"dob\": \"1980-01-15\",\n  \"phone\": \"555-123-4567\",\n  \"mrn\": \"12345\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

POST

patients

fetch

Live-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 '
{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1980-01-15",
  "phone": "555-123-4567",
  "mrn": "12345",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/patients/fetch"

payload = {
    "first_name": "Jane",
    "last_name": "Doe",
    "dob": "1980-01-15",
    "phone": "555-123-4567",
    "mrn": "12345",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Doe',
    dob: '1980-01-15',
    phone: '555-123-4567',
    mrn: '12345',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/patients/fetch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/patients/fetch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'dob' => '1980-01-15',
    'phone' => '555-123-4567',
    'mrn' => '12345',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/patients/fetch"

	payload := strings.NewReader("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"dob\": \"1980-01-15\",\n  \"phone\": \"555-123-4567\",\n  \"mrn\": \"12345\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/patients/fetch")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"dob\": \"1980-01-15\",\n  \"phone\": \"555-123-4567\",\n  \"mrn\": \"12345\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/patients/fetch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"dob\": \"1980-01-15\",\n  \"phone\": \"555-123-4567\",\n  \"mrn\": \"12345\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<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
problems
medical_history
labs
labs.results (orders plus discrete result values; implies labs)
referrals (eClinicalWorks; the patient’s incoming, outgoing, and external referrals, each with diagnoses)
tasks
tasks.notes (tasks plus attatched notes; implies tasks)
all_pages (eClinicalWorks; fetch every page of a name or dob search instead of just the first — see below)

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

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", "referrals"]
  }'

Narrowing a Search (eClinicalWorks)

A name or dob search returns a single page of matches (eClinicalWorks caps this at 20). 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.

# Narrow a busy date of birth by name
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 '{
    "search_by": "dob",
    "dob": "1985-03-15",
    "last_name": "Smith"
  }'

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",
    "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"
                    }
                ]
            }
        ]
    },
    "referrals": [
        {
            "emr_referral_id": "100611",
            "direction": "incoming",
            "referral_date": "2026-08-19",
            "referred_from": null,
            "referred_to": "Stone, Danielle M",
            "specialty": "Cardiology",
            "status": "insuranceAuth",
            "subtype": "Visit",
            "reason": "PLAQUE 75577 AUTH APPROVED TO BE DONE SHC",
            "diagnoses": [
                { "ehr_id": "507464", "code": "I10", "description": "HTN (hypertension)" }
            ]
        }
    ],
    "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"`.

{
    "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:

{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "object": "event",
    "created": "2023-10-28T11:00:00Z",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "patient.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "patient_count": 20,
        "has_more": true,
        "message": "More results are available than were returned. Narrow the search with an additional filter (for example dob or name), or set include=all_pages to retrieve every page.",
        "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"
            }
        ]
    }
}

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.

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

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,

problems,

medical_history,

labs,

labs.results,

referrals,

documents,

encounters,

encounters.details,

encounters.appointment_notes,

encounters.referral,

episodes,

notes,

assessments,

care_plans,

clinical_notes,

medical,

treatment_plan,

point_of_care,

all_pages

callback_urls

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

Example:

["https://example.com/webhooks/cobalt"]

Response

Live-fetch request accepted; results delivered by webhook

success

boolean

required

message

string

required

job_id

​Optional Includes

​Example Request

​Narrowing a Search (eClinicalWorks)

​Response Data

​Insurances Array

​Guarantors Array

​Alerts Object

​Medications Array

​Pharmacies Array

​Encounters Array

​Tasks Array

​Task Notes Array

​Webhook Notifications

Authorizations

Body

Response

Optional Includes

Example Request

Narrowing a Search (eClinicalWorks)

Response Data

Insurances Array

Guarantors Array

Alerts Object

Medications Array

Pharmacies Array

Encounters Array

Tasks Array

Task Notes Array

Webhook Notifications