Export Cohort Patients

curl --request GET \
  --url https://api.decodahealth.com/comms/cohorts/{cohort_id}/export \
  --header 'API-KEY: <api-key>' \
  --header 'TENANT: <tenant>'

import requests

url = "https://api.decodahealth.com/comms/cohorts/{cohort_id}/export"

headers = {
    "TENANT": "<tenant>",
    "API-KEY": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {TENANT: '<tenant>', 'API-KEY': '<api-key>'}};

fetch('https://api.decodahealth.com/comms/cohorts/{cohort_id}/export', 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.decodahealth.com/comms/cohorts/{cohort_id}/export",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "API-KEY: <api-key>",
    "TENANT: <tenant>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.decodahealth.com/comms/cohorts/{cohort_id}/export"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("TENANT", "<tenant>")
	req.Header.Add("API-KEY", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.decodahealth.com/comms/cohorts/{cohort_id}/export")

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

request = Net::HTTP::Get.new(url)
request["TENANT"] = '<tenant>'
request["API-KEY"] = '<api-key>'

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

{
  "data": [
    {
      "id": "<string>",
      "externalId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "dateOfBirth": "2023-12-25",
      "gender": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "address": "<string>",
      "addressLineTwo": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipCode": "<string>",
      "primaryLocationName": "<string>",
      "optedInToSmsMarketing": true,
      "optedInToEmailMarketing": true,
      "createdDate": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Audience Cohorts

Export Cohort Patients

Export-shaped page of a cohort’s membership.

Resolved server-side from filter_criteria so both cohort kinds (dynamic filters and custom lists) export the exact membership the cohort resolves to — the patient table can’t express a custom list. Paged (not one dump) because production cohorts run to thousands of patients. Ignores query_params.sort_by — export paging always uses the stable name/id order below, since re-sorting a wide PII export isn’t a feature this endpoint offers.

GET

comms

cohorts

{cohort_id}

export

Export Cohort Patients

curl --request GET \
  --url https://api.decodahealth.com/comms/cohorts/{cohort_id}/export \
  --header 'API-KEY: <api-key>' \
  --header 'TENANT: <tenant>'

import requests

url = "https://api.decodahealth.com/comms/cohorts/{cohort_id}/export"

headers = {
    "TENANT": "<tenant>",
    "API-KEY": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {TENANT: '<tenant>', 'API-KEY': '<api-key>'}};

fetch('https://api.decodahealth.com/comms/cohorts/{cohort_id}/export', 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.decodahealth.com/comms/cohorts/{cohort_id}/export",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "API-KEY: <api-key>",
    "TENANT: <tenant>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.decodahealth.com/comms/cohorts/{cohort_id}/export"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("TENANT", "<tenant>")
	req.Header.Add("API-KEY", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.decodahealth.com/comms/cohorts/{cohort_id}/export")

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

request = Net::HTTP::Get.new(url)
request["TENANT"] = '<tenant>'
request["API-KEY"] = '<api-key>'

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

{
  "data": [
    {
      "id": "<string>",
      "externalId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "dateOfBirth": "2023-12-25",
      "gender": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "address": "<string>",
      "addressLineTwo": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipCode": "<string>",
      "primaryLocationName": "<string>",
      "optedInToSmsMarketing": true,
      "optedInToEmailMarketing": true,
      "createdDate": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Headers

TENANT

string

required

The tenant you are making this request on behalf of

API-KEY

string

required

Your api key

Path Parameters

cohort_id

string

required

Query Parameters

page

integer | null

per_page

integer | null

sort_by

string | null

sort_direction

enum<string> | null

Available options:

asc,

desc

location_id

string | null

external_id

string | null

name

string | null

phone_number

string | null

date_of_birth

(string<date-time> | string)[] | null

birthday

string[] | null

created_date

tag_ids

string[] | null

Filter by patient tag IDs

tag_ids_exclude

string[] | null

Exclude patients with ANY of these tag IDs

tag_ids_mode

enum<string> | null

Match mode for tag_ids: 'any' (has ANY) or 'all' (has ALL). Default: 'all'

Available options:

any,

all

location_ids

string[] | null

Filter by primary location IDs

location_ids_exclude

string[] | null

Exclude patients at these location IDs

lead_source

string[] | null

Filter by lead source

lead_source_exclude

string[] | null

Exclude patients with these lead sources

string | null

sms_opt_out

string[] | null

Filter by combined SMS opt-out status ('true' or 'false')

on_scheduling_blacklist

string[] | null

Filter by scheduling blacklist status ('true' or 'false')

opted_in_to_sms_marketing

string[] | null

Filter by SMS marketing opt-in status ('true', 'false', or 'not_set')

opted_in_to_email_marketing

string[] | null

Filter by email marketing opt-in status ('true', 'false', or 'not_set')

opted_in_to_social_media

string[] | null

Filter by social media consent status ('true' or 'false')

appointment_count

(integer | null)[] | null

Filter by appointment count [min, max], null = unbounded

last_appointment_days

(integer | null)[] | null

Filter by days since last appointment [min, max], null = unbounded

last_appointment_service_ids

string[] | null

Scope the 'time since last appointment' recency to these service IDs. Omit to measure recency across all appointments.

visit_span_days

(integer | null)[] | null

Filter by visit span in days (last appointment − first appointment) [min, max], null = unbounded

total_spent

(integer | null)[] | null

Filter by total spent in cents [min, max], null = unbounded

membership_ids

string[] | null

Filter by active membership IDs

membership_ids_exclude

string[] | null

Exclude patients with these active memberships

membership_ids_mode

enum<string> | null

Match mode for membership_ids: 'any' or 'all'. Default: 'any'

Available options:

any,

all

enrolled_membership_date_range

Window [start, end] in which a membership enrollment must have STARTED (member.start_date), in any status. Narrowed to specific memberships when enrolled_membership_ids is set.

enrolled_membership_ids

string[] | null

Membership IDs the patient must have enrolled in within enrolled_membership_date_range. Omit to match an enrollment in any membership in the window.

membership_anniversary

string[] | null

Year-agnostic enrollment anniversary: ['--MM-DD', '--MM-DD'] month/day range matching member.start_date in ANY year and ANY status.

membership_anniversary_membership_ids

string[] | null

Membership IDs the anniversary must belong to. Omit to match an enrollment anniversary in any membership.

package_ids

string[] | null

Filter by active package IDs

package_ids_exclude

string[] | null

Exclude patients with these active packages

package_ids_mode

enum<string> | null

Match mode for package_ids: 'any' or 'all'. Default: 'any'

Available options:

any,

all

appointment_type_ids

string[] | null

Filter by service IDs from completed appointments

appointment_type_ids_exclude

string[] | null

Exclude patients who completed these appointment types

appointment_type_ids_mode

enum<string> | null

Match mode for appointment_type_ids: 'any' or 'all'. Default: 'any'

Available options:

any,

all

appointment_date_range

Filter by appointment date range [start, end]

appointment_service_ids

string[] | null

Restrict appointment_date_range to appointments for these service IDs. Omit to match any appointment in the window.

appointment_statuses

enum<string>[] | null

Appointment statuses that count inside appointment_date_range. Omit both this and appointment_statuses_exclude to count every status except CANCELLED.

Available options:

PENDING,

RESERVED,

CONFIRMED,

CANCELLED,

COMPLETED,

OVERRIDABLE,

NO_SHOW

appointment_statuses_exclude

enum<string>[] | null

Appointment statuses that do NOT count inside appointment_date_range. ANDs with appointment_statuses when both are set; omitting both excludes CANCELLED only.

Available options:

PENDING,

RESERVED,

CONFIRMED,

CANCELLED,

COMPLETED,

OVERRIDABLE,

NO_SHOW

completed_appointment_service_ids

string[] | null

Service IDs that must have been COMPLETED within completed_appointment_date_range. Omit to match any completed appointment in the window.

completed_appointment_date_range

Window [start, end] in which an appointment must have been COMPLETED. Narrowed to specific services when completed_appointment_service_ids is set.

created_appointment_service_ids

string[] | null

Service IDs that must have been BOOKED within created_appointment_date_range. Omit to match any appointment booked in the window.

created_appointment_date_range

Window [start, end] in which an appointment must have been BOOKED (created), keyed on the appointment's creation timestamp rather than its scheduled date. Narrowed to specific services when created_appointment_service_ids is set.

no_appointment_service_ids

string[] | null

Restrict no_appointment_date_range to appointments for these service IDs. Omit to match any appointment in the window.

no_appointment_date_range

Patients with NO non-cancelled appointment (optionally for no_appointment_service_ids) in this date range [start, end]

weight

(number | null)[] | null

Filter by latest weight in lbs [min, max], null = unbounded

gender

string[] | null

Filter by gender values

gender_exclude

string[] | null

Exclude patients with these genders

patient_source

string[] | null

Filter by patient source

patient_source_exclude

string[] | null

Exclude patients from these sources

preferred_provider_id

string[] | null

Filter by preferred provider IDs

preferred_provider_id_exclude

string[] | null

Exclude patients with these preferred providers

most_recent_provider_id

string[] | null

Filter by provider IDs from most recent completed appointment

most_recent_provider_id_exclude

string[] | null

Exclude patients whose most recent completed appointment was with these providers

credit_balance

(integer | null)[] | null

Filter by credit balance in cents [min, max]

hide_unconverted_leads

boolean

default:true

Hide patients that are thin comms identities for open opportunities (default: True)

city

string | null

state

string | null

zip_code

string | null

last_active_days

(integer | null)[] | null

Filter by days since last active [min, max]

opted_out_of_email

string[] | null

Filter by email opt-out status ('true' or 'false')

age

(integer | null)[] | null

Filter by current age in years [min, max], null = unbounded

height

(number | null)[] | null

Filter by latest height in inches [min, max], null = unbounded

goal_weight

(number | null)[] | null

Filter by goal weight in lbs [min, max], null = unbounded

systolic_bp

(number | null)[] | null

Filter by latest systolic BP in mmHg [min, max], null = unbounded

diastolic_bp

(number | null)[] | null

Filter by latest diastolic BP in mmHg [min, max], null = unbounded

waist_circumference

(number | null)[] | null

Filter by latest waist circumference in inches [min, max], null = unbounded

pulse

(number | null)[] | null

Filter by latest pulse in BPM [min, max], null = unbounded

temperature

(number | null)[] | null

Filter by latest temperature in °F [min, max], null = unbounded

has_profile_picture

string[] | null

Filter by profile picture presence ('true' or 'false')

pronouns

string | null

Filter by pronouns text

preferred_name

string | null

Filter by preferred name text

surcharge_disabled

string[] | null

Filter by surcharge disabled status ('true' or 'false')

has_notes

string[] | null

Filter by note presence ('true' or 'false')

has_active_chat

string[] | null

Filter by active chat presence ('true' or 'false')

medication_count

(integer | null)[] | null

Filter by active medication count [min, max], null = unbounded

has_email

string[] | null

Filter by email presence ('true' or 'false')

has_phone_number

string[] | null

Filter by phone number presence ('true' or 'false')

has_membership

string[] | null

Filter by active, frozen, or delinquent membership presence ('true' or 'false')

has_tags

string[] | null

Filter by tag presence ('true' or 'false')

has_future_appointments

string[] | null

Filter by future appointment presence ('true' or 'false')

cancelled_appointment_date_range

Filter by cancelled appointment date range [start, end]

cancelled_appointment_days

(integer | null)[] | null

Days since last cancelled appointment [min, max], null = unbounded

last_appointment_status

string[] | null

Status of patient's most recent appointment

outstanding_balance

(integer | null)[] | null

Filter by outstanding balance in cents [min, max]

outstanding_balance_days

(integer | null)[] | null

Filter by days since oldest outstanding charge [min, max]

purchased_item_ids

string[] | null

Filter by purchased item IDs from charges

purchased_item_ids_exclude

string[] | null

Exclude patients who purchased these items

purchased_item_ids_mode

enum<string> | null

Match mode for purchased_item_ids: 'any' or 'all'. Default: 'any'

Available options:

any,

all

has_payment_plan

string[] | null

Filter by payment plan presence ('true' or 'false')

last_payment_days

(integer | null)[] | null

Filter by days since last successful payment [min, max]

last_payment_status

enum<string>[] | null

Status of patient's most recent payment

Status of a Payment or Refund.

NOTE for any "cash collected / refunded" or settlement-style query: both SUCCEEDED AND PROCESSING count as money committed. SUCCEEDED means cleared in the bank account; PROCESSING means the transaction is in flight (e.g. ACH still settling) but the clinic should expect it. Most accounting / analytics aggregates that filter only on status == SUCCEEDED silently undercount real cash flow — use status IN (SUCCEEDED, PROCESSING) unless you specifically want only fully-cleared funds.

Use COMMITTED_PAYMENT_STATUSES below for the common case.

Available options:

CANCELED,

CREATED,

FAILED,

IN_REVIEW,

PRESENTING,

PROCESSING,

SUCCEEDED

last_payment_status_exclude

enum<string>[] | null

Exclude patients whose last payment status matches

Status of a Payment or Refund.

Use COMMITTED_PAYMENT_STATUSES below for the common case.

Available options:

CANCELED,

CREATED,

FAILED,

IN_REVIEW,

PRESENTING,

PROCESSING,

SUCCEEDED

has_payment_method

string[] | null

Filter by saved payment method presence ('true' or 'false')

membership_statuses

enum<string>[] | null

Filter by membership status values

Available options:

ACTIVE,

EXPIRED,

CANCELLED,

DELINQUENT,

FROZEN,

INACTIVE,

PENDING,

AWAITING_FORM,

SWITCHED

membership_statuses_exclude

enum<string>[] | null

Exclude patients with memberships in these statuses

Available options:

ACTIVE,

EXPIRED,

CANCELLED,

DELINQUENT,

FROZEN,

INACTIVE,

PENDING,

AWAITING_FORM,

SWITCHED

membership_statuses_membership_ids

string[] | null

Narrow membership_statuses / membership_statuses_exclude to these memberships. Omit to match a membership in those statuses regardless of plan.

discount_types

enum<string>[] | null

Filter by patients who hold a currently-redeemable discount of these source types (e.g. MEMBERSHIP, PACKAGE, PROMOTION)

Available options:

GLOBAL,

CUSTOM,

MEMBERSHIP,

PACKAGE,

SAVED_ITEM,

PROMOTION,

CASH_DISCOUNT

discount_types_exclude

enum<string>[] | null

Exclude patients who hold a currently-redeemable discount of these source types

Available options:

GLOBAL,

CUSTOM,

MEMBERSHIP,

PACKAGE,

SAVED_ITEM,

PROMOTION,

CASH_DISCOUNT

discount_template_ids

string[] | null

Filter by patients who hold a currently-redeemable discount from these discount templates

discount_template_ids_exclude

string[] | null

Exclude patients who hold a currently-redeemable discount from these discount templates

discount_template_ids_mode

enum<string> | null

Match mode for discount_template_ids: 'any' or 'all'. Default: 'any'

Available options:

any,

all

discount_benefit_item_ids

string[] | null

Filter by patients who hold a currently-redeemable discount targeting these items (e.g. a Nutrition consult included in their package/membership)

discount_benefit_item_ids_exclude

string[] | null

Exclude patients who hold a currently-redeemable discount targeting these items

discount_benefit_item_ids_mode

enum<string> | null

Match mode for discount_benefit_item_ids: 'any' or 'all'. Default: 'any'

Available options:

any,

all

Response

Successful Response

data

CohortExportPatient · object[]

required

Show child attributes

total

integer

required

Getting Started

API Guides

Patient Management

Billing & Payments

Catalog & Inventory

Growth

Clinical & Scheduling

Communications

Platform

Export Cohort Patients

Headers

Path Parameters

Query Parameters

Response