Skip to content
API reference
/
/
Search patients

Search patients

Request

Returns a paginated list of patients for a practice, with optional filters.

When no query filters are provided, all patients for the practice are returned (subject to pagination), ordered for keyset paging.

When one or more filters are provided, patients matching any of those filters are included (logical OR). Filters combine only with each other under this OR rule.

When family_id is provided, only patients in that family are considered. Any other filters are OR-combined within that family. Behaviour without family_id is unchanged.

Filter semantics:

  • family_id — exact UUID match limiting results to patients in that family.
  • id — primary key equality.
  • first_name — case-insensitive prefix match on first name.
  • last_name — case-insensitive prefix match on last name.
  • date_of_birth — exact calendar date match (YYYY-MM-DD).
  • email_address — case-insensitive prefix match on stored email.
  • mobile_phone — match against mobile number (substring match, case-insensitive).

Response body matches GET /patients (same data items and meta.cursor pagination). Visibility of email, address, and phone fields still depends on the token scopes, as for the patient list endpoint.

Security
oauth2(Required scopes: patient:read)
Query
limitinteger, [ 1 .. 100 ]

Maximum number of records to return per page.

Default:20
cursorstring

Cursor reference to the next page of records.

family_idstring, (uuid)

Exact family UUID. Other filters are OR-combined within the matching family.

idstring

Filter by patient id.

first_namestring

Case-insensitive prefix filter on first name.

last_namestring

Case-insensitive prefix filter on last name.

date_of_birthstring, (date)

Exact date of birth (YYYY-MM-DD).

email_addressstring, (email)

Case-insensitive prefix filter on email address.

mobile_phonestring

Filter using mobile number (substring match).

created_date_fromstring, (date)

Inclusive start of a created date range filter. Calendar date only (YYYY-MM-DD). Use together with created_date_to for explicit date range control.

  • When used together with created_date_to, the range between the two values must not exceed 90 days.
  • When used without created_date_to, returns records from created_date_from up to 90 days later (or up to the current date-time if it is earlier).
Example:created_date_from=2026-01-01
created_date_tostring, (date)

Inclusive end of a created date range filter. Calendar date only (YYYY-MM-DD). Use together with created_date_from for explicit date range control.

  • When used together with created_date_from, the range between the two values must not exceed 90 days.
  • When used without created_date_from, returns records from 90 days before created_date_to (or from the earliest available date if less than 90 days of data exists) up to created_date_to.
Example:created_date_to=2026-01-01
updated_date_fromstring, (date)

Inclusive start of an updated date range filter. Calendar date only (YYYY-MM-DD). Use together with updated_date_to for explicit date range control.

  • When used together with updated_date_to, the range between the two values must not exceed 90 days.
  • When used without updated_date_to, returns records from updated_date_from up to 90 days later (or up to the current date-time if it is earlier).
Example:updated_date_from=2026-01-01
updated_date_tostring, (date)

Inclusive end of an updated date range filter. Calendar date only (YYYY-MM-DD). Use together with updated_date_from for explicit date range control.

  • When used together with updated_date_from, the range between the two values must not exceed 90 days.
  • When used without updated_date_from, returns records from 90 days before updated_date_to (or from the earliest available date if less than 90 days of data exists) up to updated_date_to.
Example:updated_date_to=2026-01-01
Headers
X-Practice-Idstring, (uuid)required

UUID of the practice in whose context the request is executed. The API uses this to resolve data the caller is permitted to access for that practice.

curl -i -X GET \
  'https://docs.api.dentally.com/_mock/docs/versions/2026-01-01/nexgen/patients/search?limit=20&cursor=string&family_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&id=string&first_name=string&last_name=string&date_of_birth=2019-08-24&email_address=user%40example.com&mobile_phone=string&created_date_from=2026-01-01&created_date_to=2026-01-01&updated_date_from=2026-01-01&updated_date_to=2026-01-01' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Practice-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Responses

Paginated list of patients for the requested practice, ordered by creation time (latest first) and then by ID for a stable sort.

Bodyapplication/json
dataArray of objects(patient)required

List of patients.

metaobject(meta)required

Cursor-based pagination metadata. When an operation supports paging, pass cursor from this object on a subsequent request to continue after the current page.

Response
{
  "data": [
    { … }
  ],
  "meta": {
    "cursor": "eyJjdXJzb3IiOiJuZXh0In0"
  }
}