Skip to main content
GET
/
v1
/
patients
List Patients
curl --request GET \
  --url https://api.example.com/v1/patients \
  --header 'X-API-Key: <api-key>'
{
  "data": [
    {
      "active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "date_of_birth": "1990-01-15",
      "email": "john.doe@example.com",
      "first_name": "John",
      "id": "550e8400-e29b-41d4-a716-446655440009",
      "last_name": "Doe",
      "phone_number": "+1234567890",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "limit": 50,
    "page": 1,
    "total": 1
  }
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
workflow_stage_ids[]
string<uuid>[] | null

Filter by multiple workflow stage IDs (OR)

​
include_unassigned
boolean
default:false

Include patients with no workflow stage (combines with workflow_stage_ids via OR)

​
tags[]
string[] | null

Filter by tag IDs

​
insurance_ids[]
string[] | null

Filter by insurance IDs

​
states[]
enum<string>[] | null

Filter by states

US States enum matching Prisma @map values

Available options:
alabama,
alaska,
arizona,
arkansas,
california,
colorado,
connecticut,
delaware,
florida,
georgia,
hawaii,
idaho,
illinois,
indiana,
iowa,
kansas,
kentucky,
louisiana,
maine,
maryland,
massachusetts,
michigan,
minnesota,
mississippi,
missouri,
montana,
nebraska,
nevada,
new_hampshire,
new_jersey,
new_mexico,
new_york,
north_carolina,
north_dakota,
ohio,
oklahoma,
oregon,
pennsylvania,
rhode_island,
south_carolina,
south_dakota,
tennessee,
texas,
utah,
vermont,
virginia,
washington,
west_virginia,
wisconsin,
wyoming,
district_of_columbia,
puerto_rico,
virgin_islands,
guam,
northern_mariana_islands,
american_samoa
​
location_ids[]
string<uuid>[] | null

Filter by company location IDs

​
created_from[]
enum<string>[] | null

Filter by created_from sources

Patient creation source enum matching Prisma

Available options:
form,
call,
api,
file,
sms,
fax,
chat_agent,
manual,
bulk_import,
eligibility
​
eligibility_status[]
enum<string>[] | null

Filter by eligibility check status

Eligibility check status enum matching Prisma EligibilityStatus.

Note: this Python enum has FAILED but the Postgres eligibility_check_status type does not — pre-existing drift between Prisma and the DB. Don't use pg_enum(EligibilityStatus) for the DB column; declare the column with the DB's actual values via a literal ENUM(...).

Available options:
active,
inactive,
pending,
failed
​
eligibility_filter_mode
enum<string> | null

Eligibility filter mode Eligibility filter mode — which payor tier to check, or any

Available options:
any,
primary,
secondary,
tertiary,
quaternary
​
sync_status[]
enum<string>[] | null

Filter by sync status

Sync status filter for patient list queries

Available options:
pending,
completed
​
plan_name
string | null

Filter by plan name (partial match)

​
plan_types[]
enum<string>[] | null

Filter by plan types

Insurance plan type enum matching Prisma - X12 standard codes

Available options:
01,
02,
03,
12,
13,
14,
15,
16,
17,
18,
19,
41,
42,
43,
47,
48,
49,
AP,
C1,
CO,
CP,
D,
DB,
EP,
FF,
GP,
HB,
HD,
HG,
HM,
HN,
HP,
HS,
IN,
IP,
LC,
LD,
LI,
LT,
M,
MA,
MB,
MC,
MD,
ME,
MH,
MI,
MJ,
MK,
ML,
MM,
MN,
MO,
MP,
MR,
MT,
OA,
OT,
PE,
PL,
PP,
PR,
PS,
QM,
RP,
SA,
SP,
TF,
WC,
WU
​
group_description
string | null

Filter by group description (partial match)

​
group_number
string | null

Filter by group number (partial match)

​
expand[]
enum<string>[] | null

Fields to expand in the response

Allowed expand values for patient endpoints

Available options:
tags,
workflow_stage,
assigned_user,
referrals,
payors,
external_id_values
​
page
integer | null
default:1
Required range: x >= 1
​
limit
integer | null
default:50
Required range: 1 <= x <= 100
​
q
string | null
​
id
string<uuid> | null
​
workflow_stage_id
string | null
​
assigned_to
string | null
​
status
enum<string> | null
default:active

Filter options for patient status (active/inactive/all)

Available options:
active,
inactive,
all
​
phone_number
string | null
​
email
string | null
​
external_id
string | null
​
first_name
string | null
​
last_name
string | null
​
date_of_birth
string | null
​
tag_filter_mode
enum<string> | null
default:any

Tag filter mode for patient queries

Available options:
any,
all,
exclude_any,
exclude_all
​
created_gte
string<date-time> | null
​
created_lte
string<date-time> | null
​
updated_gte
string<date-time> | null
​
updated_lte
string<date-time> | null

Response

Successful Response

List response for patients

​
data
Patient · object[]
required
​
pagination
Pagination · object
required

Pagination information for list responses.

Fields:

  • has_more: Whether more items exist beyond this page
  • total: Total number of items across all pages
  • page: Current page number (1-based)
  • limit: Number of items per page