---
title: "Search patients by free text"
method: POST
path: "/api/2026-01-01/patients/search"
tags: ["Patients"]
---

# Search patients by free text

`POST /api/2026-01-01/patients/search`

## Request

- Base URL: `https://jdpdocsdemo.jane.qa`
- URL: `https://jdpdocsdemo.jane.qa/api/2026-01-01/patients/search`
- Auth: OAuth 2
  - Authorization code: `https://login.id.janeapp.com/realms/jane_partner_sandbox/protocol/openid-connect/auth?response_type=code&resource=https://jdpdocsdemo.jane.qa&prompt=consent`
  - Token URL: `https://login.id.janeapp.com/realms/jane_partner_sandbox/protocol/openid-connect/token` scopes: `patients:read`

Free-text patient search across name, email, phone number, and patient number.

This is a POST-body endpoint specifically so PII (patient names, email, phone)
does not leak into URL query strings, access logs, browser history, or referrer headers.

Scope is intentionally search-only: the body accepts `search`, `sort`, and `page`.
Structured filters (`public_id`, `created_at`, `updated_at`) are not supported here —
use `GET /patients` for those. Combined search + structured filtering is a deliberate
follow-up if a consumer need materializes.

Filter operators:
- `search`: `co` (contains) only

Pagination: the response returns a `cursor` and `hasNextPage`. To fetch
subsequent pages, re-POST the same body with `page.cursor` set to the
previous response's `cursor`. The `links` object is omitted from this
endpoint's response (GET-style pagination URLs would re-expose filter PII
in query strings).

Example body:
```json
{
  "search": { "co": "Jane Smith" },
  "sort": "-created_at",
  "page": { "limit": 50 }
}
```

## Request body

- PatientsSearchRequest: Request body for POST /patients/search. Free-text search across patient name, email, phone, and patient number, carried in the body so PII does not leak into URLs. Only the `search` field is accepted at this endpoint — structured filtering (public_id, created_at, updated_at) belongs on GET /patients. Combined search + structured filtering is a deliberate follow-up if a consumer need materializes.
  - `search` object, required: Free-text search across patient name, email, phone number, and patient number. Results follow the requested `sort` order (or default ordering when no `sort` is specified).
    - `co` string: Contains-match search term. Maximum 255 characters.
  - `sort` string: Comma-separated list of fields to sort by. Prefix a field with '-' for descending order. Example: `-created_at,updated_at`.
  - `page` object: Cursor-based pagination controls.
    - `cursor` string
    - `limit` integer

## Response `200`

The paginated list of matching patients

- PatientsSearchResponse: Paginated list of matching patients from POST /patients/search. Omits the `links` object that `GET /patients` returns: GET-style pagination URLs would re-serialize search terms into query strings and re-expose PII, which is the whole reason search moved to a POST body. Clients paginate by re-POSTing the same body with `page.cursor` set to the previous response's `cursor`.
  - `items` Patient2[]
    - `id` string, uuid, required: Unique identifier for the patient
    - `first_name` string: Patient's first name
    - `middle_name` string: Patient's middle name
    - `last_name` string: Patient's last name
    - `prefix` string: Patient's name prefix/title
    - `preferred_name` string: Patient's preferred name or nickname
    - `sex` 'male' | 'female' | 'x': Patient's sex which matches what is on their insurance policies
    - `gender` string: Patient's current gender, which may differ from gender indicated on their insurance policies
    - `pronouns` string: Patient's preferred pronouns
    - `date_of_birth` string, date: Patient's date of birth. Format: YYYY-MM-DD
    - `guardian_name` string: Patient's guardian name
    - `patient_since` string, date: Patient's date of registration
    - `patient_number` string: Patient's number
    - `email` string, email: Patient's email address
    - `send_marketing_emails` boolean: Patient's marketing email preferences
    - `do_not_email` boolean: Patient's general email opt-out preference
    - `status` 'active' | 'discharged' | 'deceased' | 'archived': Patient's current lifecycle state
    - `mobile_country_code` string: Deprecated. Use the phone_numbers array instead. This field will be removed in a future version.
    - `mobile_phone_number` string: Deprecated. Use the phone_numbers array instead. This field will be removed in a future version.
    - `phone_numbers` object[]: All phone numbers associated with the patient. Only non-blank numbers are included.
      - `type` 'home' | 'mobile' | 'work' | 'fax', required: The phone number type
      - `number` string, required: The phone number
      - `is_primary` boolean, required: Whether this is the patient's primary phone number
    - `street_address` string: Patient's street address
    - `street_address_2` string: Additional street address information
    - `city` string: Patient's city of residence
    - `province` string: Patient's state/province
    - `postal` string: Postal/ZIP code
    - `country` string: Country code
    - `deep_links` object: Platform-specific links for accessing this patient in different contexts (e.g., admin web app, mobile app)
      - `profile` object: Links to the patient profile resource
        - `web` string, uri: Direct link to the patient's profile in the Jane admin web UI
  - `cursor` string, nullable: The Base64 encoded cursor for the next page. null if this is the last page.
  - `limit` integer
  - `hasNextPage` boolean: Whether there is a next page of patients

## Other responses

- `400`: The request was invalid
- `401`: Unauthorized
- `429`: Rate limit exceeded - 100 requests per minute per endpoint per clinic

## Changes

- **2026-11-03** `01798f613a5e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/jane/apis/jdp-api/changes/api/2026-01-01/patients/search/post.md)

---

[API](https://skmtc.dev/jane/apis/jdp-api.md) - [All operations](https://skmtc.dev/jane/apis/jdp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jane/apis/jdp-api/revisions/01798f613a5e?raw)