# List Patients (v3)

Retrieve a list of patients for the practice group using explicit patient filters.

This endpoint is intended for structured patient search flows where partners can provide named filters such as first_name, last_name, dob, nhs_number, or ehr_partner_id.

Compared with the v2 patients endpoint, v3 supports multi-field search in a single request instead of the older field + search format.

At least one filter must be supplied.

Endpoint: GET /v3/patients
Version: 1.0.0
Security: apiKeyAuth, practiceGroupId

## Query parameters:

  - `page_index` (string)
    Zero-based page index for paginated results.

  - `page_size` (string)
    Number of results to return per page.

  - `first_name` (string)
    Filter by patient first name.

  - `last_name` (string)
    Filter by patient last name.

  - `dob` (string)
    Filter by exact date of birth in YYYY-MM-DD format.
    Example: "1990-12-31"

  - `nhs_number` (string)
    Filter by NHS number.

  - `ehr_partner_id` (string)
    Filter by the patient identifier used by the connected EHR.

## Response 200 fields (application/json):

  - `data` (array, required)

  - `data.ehr_partner_id` (string,null)

  - `data.emis_id` (string,null)

  - `data.deceased_at` (string,null)

  - `data.ods_code` (string,null)

  - `data.dob` (string,null, required)
    ISO 8601 date format
    Example: "1989-04-11"

  - `data.title` (string,null)
    Enum: "Baron", "Baroness", "Brigadier", "Count", "Colonel", "Countess", "Captain", "Dame", "The Dowager Viscountess", "Dr", "Duchess", "Duke", "Earl", "His Excellency", "Father", "H.E. Ambassador Mr", "H.E. Mr", "H.E. Mrs", "Her Grace", "His Grace", "The Hon", "The Hon Mr", "The Hon Mrs", "HRH", "HRH Prince", "HRH Princess", "Insurance", "HM King", "Lady", "Lord", "Major", "Master", "Miss", "Mr", "Mrs", "Ms", "Mss", "Mx", "Pr", "Professor", "HM Queen", "Rabbi", "Reverend", "Sheikh", "Sheikha", "Sir", "The", "", "Viscount", "Viscountess"

  - `data.first_name` (string,null)

  - `data.last_name` (string,null)

  - `data.sex` (string,null)
    Enum: "Not known", "Not specified", "Male", "Female", "Other"

  - `data.nhs_number` (string,null)

  - `data.email` (string,null)

  - `data.mobile` (string,null)

  - `data.last_sync_at` (string,null)

  - `data.data_source` (string,null)
    Enum: "hero", "emis", "pds", "gha", "systm_one"

  - `data.restricted` (boolean)

  - `data.line_1` (string,null)

  - `data.line_2` (string,null)

  - `data.line_3` (string,null)

  - `data.town` (string,null)

  - `data.county` (string,null)

  - `data.postcode` (string,null)

  - `data.hero_id` (string,null)

  - `data.hero_uid` (string,null)

  - `data.identifiers` (array, required)

  - `data.identifiers.source` (string, required)
    Enum: "nhs", "gha", "ehr_partner", "hero"

  - `data.identifiers.name` (string, required)
    Enum: "nhs_number", "gha_number", "ehr_partner_id", "hero_id", "hero_uid"

  - `data.identifiers.role` (string, required)
    Enum: "main", "secondary"

  - `data.identifiers.label` (string, required)
    Enum: "NHS", "GHA", "EMIS", "Hero", "Systm One"

  - `data.identifiers.value` (string, required)

  - `data.ehr_registered` (boolean,null, required)

  - `count` (number, required)

## Response 400 fields (application/json):

  - `error` (boolean, required)
    Example: true

  - `statusCode` (number, required)
    Example: 400

  - `message` (array, required)

  - `message.code` (string, required)
    Example: "invalid_type"

  - `message.expected` (string, required)
    Example: "string"

  - `message.path` (array, required)
    Example: ["patient_id"]


## Response 401 fields

## Response 404 fields

## Response 422 fields

## Response 500 fields