Patients V1 — Developer Guide

Reference: Patients (V1) Endpoint Documentation

Patient records are the core identity for scheduling, clinical, and billing integrations. This guide covers the published Patients V1 operations: bulk list, get by id, create, update, calculated fields, and total count.

For GET /v1/patients/async, see Async Endpoints V1 — Developer Guide. Async returns the first 10 results immediately and streams the full result set to the Streaming API. Results on the async endpoint are ordered by id descending (newest first), unlike the synchronous bulk GET which pages by ascending id.

Returns a paginated list of patients matching the filter criteria.

⚠️ Rate Limited: This endpoint is rate limited. See the rate limiting guide for details.

NEW, ACTIVE, NON-PATIENT, INACTIVE, DUPLICATE, DISMISSED, DECEASED

M, F, O

Use a specific location id, a list via ->, or all locations with ALL, *, ->["ALL"], or ->["*"].

⚠️ Upcoming Breaking Change: preferredLocation.id (as a list of IDs or ["ALL"]) will become a required filter. Omitting preferredLocation.id currently defaults to all locations during a transitional period.

⚠️ Date-limiting filters: If you do not supply a date-limiting filter, one may be applied automatically using lastModified. Supply your own date bound for predictable results. The following filter keys count as date-limiting: lastModified, createdDate, and updatedDate.

⚠️ Narrow your query: A very wide lastModified range with no other scoping can return 408 (timeout) on large tenants. Combine name, chart, contact, or location filters with a date bound, or use lastId pagination.

⚠️ Not Recommended: Do not paginate large data sets using the page parameter. Use lastId cursor pagination instead.

Empty results: 200 with data: [] means no patients matched; it does not indicate invalid filter values.

Fetch patients modified after a date at specific locations:

GET /api/v1/patients?pageSize=500&filter=lastModified>=2025-01-01T00:00:00Z,preferredLocation.id->[64000000000004]

Fetch patients for a primary guarantor:

GET /api/v1/patients?filter=primaryGuarantor.id==12000006542062,lastModified>=2025-01-01T00:00:00Z

lastId uses the patient's id as a cursor. When filtering by lastModified, firstVisitDate, or dateOfBirth, combine those filters with lastId for stable pagination. Results are ordered by id for paging.

GET /api/v1/patients?pageSize=500&filter=lastModified>=2025-01-01T00:00:00Z,preferredLocation.id->[64000000000004]

Pass the id of the last record in data as lastId:

GET /api/v1/patients?lastId=22000012345678&pageSize=500&filter=lastModified>=2025-01-01T00:00:00Z,preferredLocation.id->[64000000000004]

Continue until data is empty.

For how meta.pagination.total behaves (including when it is 0 or omitted), see Bulk GET — Total Count Behavior.

Returns a single patient by patientId.

GET /api/v1/patients/12000006542062?responseFields=firstName,lastName,chartNumber

Creates a new patient. Returns 201 with the created resource in data.

{
  "firstName": "Jane",
  "lastName": "Smith",
  "contactMethod": "Email me",
  "languageType": "English",
  "patientStatus": "ACTIVE",
  "gender": "F",
  "dateOfBirth": "1990-03-15",
  "preferredLocation": { "id": "64000000000004" },
  "address1": "123 Maple Street",
  "city": "Anytown",
  "state": "CA",
  "postalCode": "90210",
  "emailAddress": "jane.smith@example.com",
  "phones": [
    {
      "phoneType": "MOBILE",
      "number": "5551234567",
      "sequence": 1
    }
  ]
}

Updates an existing patient. Only fields included in the request body are changed; omitted fields are unchanged.

PUT /api/v1/patients/12000006542062

{
  "patientStatus": "INACTIVE",
  "emailAddress": "jane.smith.new@example.com"
}

GET /api/v1/patients/calculated returns computed fields per patient row.

Both filter and responseFields are required.

GET /api/v1/patients/calculated?filter=patient.id->[12000006542062]&responseFields=lastVisitDate

GET /api/v1/patients/totalcount

Uses the same filter syntax and filter keys as bulk GET. See Bulk GET — Total Count Behavior for how pagination.total behaves on bulk GET responses.

GET /api/v1/patients/totalcount?filter=lastModified>=2025-01-01,preferredLocation.id==64000000000004

Patient billing types are managed on a nested path under the patient:

• GET /api/v1/patients/{patientId}/billingtypes — list billing types for a patient
• POST /api/v1/patients/{patientId}/billingtypes — replace all billing types for the patient (existing types are removed and replaced by the request body)

See the official API reference under Patient Billing Types for schema details.

For real-time patient creates and updates, use the Streaming API instead of polling bulk GET on a fixed schedule. Setup is covered in Creating and Setting Up Webhooks for the StreamAPI.

Patients are streamable under domain type PatientV1.

A successful 200/201 response returns:

For bulk GET, data is an array and includes meta.pagination.

For the authoritative field list, enums, and validation rules, use the PatientV1 and PatientUpdateV1 schemas in the official API reference.