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

import requests

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

payload = {
    "dob": "2023-12-25",
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "mrn": "<string>",
    "include": "problems,medical_history,labs.results"
}
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({
    dob: '2023-12-25',
    first_name: '<string>',
    last_name: '<string>',
    phone: '<string>',
    mrn: '<string>',
    include: 'problems,medical_history,labs.results'
  })
};

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([
    'dob' => '2023-12-25',
    'first_name' => '<string>',
    'last_name' => '<string>',
    'phone' => '<string>',
    'mrn' => '<string>',
    'include' => 'problems,medical_history,labs.results'
  ]),
  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  \"dob\": \"2023-12-25\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"mrn\": \"<string>\",\n  \"include\": \"problems,medical_history,labs.results\"\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  \"dob\": \"2023-12-25\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"mrn\": \"<string>\",\n  \"include\": \"problems,medical_history,labs.results\"\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  \"dob\": \"2023-12-25\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"mrn\": \"<string>\",\n  \"include\": \"problems,medical_history,labs.results\"\n}"

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

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

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

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

import requests

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

payload = {
    "dob": "2023-12-25",
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "mrn": "<string>",
    "include": "problems,medical_history,labs.results"
}
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({
    dob: '2023-12-25',
    first_name: '<string>',
    last_name: '<string>',
    phone: '<string>',
    mrn: '<string>',
    include: 'problems,medical_history,labs.results'
  })
};

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([
    'dob' => '2023-12-25',
    'first_name' => '<string>',
    'last_name' => '<string>',
    'phone' => '<string>',
    'mrn' => '<string>',
    'include' => 'problems,medical_history,labs.results'
  ]),
  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  \"dob\": \"2023-12-25\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"mrn\": \"<string>\",\n  \"include\": \"problems,medical_history,labs.results\"\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  \"dob\": \"2023-12-25\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"mrn\": \"<string>\",\n  \"include\": \"problems,medical_history,labs.results\"\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  \"dob\": \"2023-12-25\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"mrn\": \"<string>\",\n  \"include\": \"problems,medical_history,labs.results\"\n}"

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

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

{
  "success": true,
  "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)
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

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:

{
    "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"`.

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

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.

Example:

"problems,medical_history,labs.results"

Response

Request accepted for processing

success

boolean

message

string

job_id

string

​Optional Includes

​Example Request

​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

Response Data

Insurances Array

Guarantors Array

Alerts Object

Medications Array

Pharmacies Array

Encounters Array

Tasks Array

Task Notes Array

Webhook Notifications