# List patients

Operation ID: `fieldagent.listPatients`

List FHIR patients visible to the field agent, scoped to the caller's tenant (resolved from the Bearer JWT) — not to the calling agent's own registrations, unless ?created_by= is also supplied. Supplying family/given switches to a name search and disables cursor pagination (next_page_token is always null); created_by is applied client-side after either the name search or the default page fetch, over-fetching up to 10x limit (capped at 200) to backfill the requested page size.

## Public method

`listPatients`

Signature: `fieldAgent.listPatients(query)`

Return type: `Promise<ListAgentPatientsResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`GET /patients`

## Path parameters

None.

## Query parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `created_by` | `string` | No |  |  |  | No | Person FHIR ID — only patients registered by this agent |
| `family` | `string` | No |  |  |  | No | Filter by family (last) name |
| `given` | `string` | No |  |  |  | No | Filter by given (first) name |
| `limit` | `integer` | No |  |  | `20` | No |  |
| `page_token` | `string` | No |  |  |  | No | Pagination token from a previous response |

## Body parameters

None.

Request model: None.

## Request example

None declared in canonical OpenAPI.

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`ListPatientsResponse`](../models/ListPatientsResponse.md) | application/json | Tenant-scoped patient list |

## Success response examples

### 200

```json
{
  "created_by": "string",
  "next_page_token": "string",
  "patients": [
    {
      "active": true,
      "addresses": [],
      "athena_patient_id": "string",
      "athena_practice_id": "string",
      "attributes": {},
      "communications": [
        {
          "language": "string",
          "preferred": false
        }
      ],
      "created_by": "self",
      "created_date": "2026-01-01T09:00:00Z",
      "date_of_birth": "2026-01-01",
      "deceased": false,
      "deceased_cause": "string",
      "deceased_date": "2026-01-01",
      "drivers_license": {
        "expiration_date": "2026-01-01",
        "number": "string",
        "state": "st"
      },
      "email": "user@example.com",
      "emergency_contacts": [],
      "ethnicity": "hispanic_or_latino",
      "fhir_id": "string",
      "flags": {},
      "gender": "male",
      "gender_identity": "man",
      "insurance": [
        {
          "copay": 0,
          "deductible": 0,
          "effective_date": "2026-01-01",
          "group_number": "string",
          "member_id": "string",
          "payer_id": "string",
          "payer_name": "string",
          "plan_name": "string",
          "plan_type": "string",
          "priority": "primary",
          "subscriber_date_of_birth": "2026-01-01",
          "subscriber_first_name": "string",
          "subscriber_id": "string",
          "subscriber_last_name": "string",
          "subscriber_relationship": "self",
          "termination_date": "2026-01-01"
        }
      ],
      "links": [
        {
          "other_patient_fhir_id": "string",
          "type": "seealso"
        }
      ],
      "managing_organization_id": "string",
      "marital_status": "single",
      "mrn": "string",
      "name": {
        "first_name": "string",
        "last_name": "string",
        "middle_name": "string",
        "preferred_name": "string",
        "prefix": "string",
        "suffix": "string",
        "use": "official"
      },
      "nationality": "st",
      "openloop_dietitian_id": "string",
      "openloop_patient_id": "string",
      "patient_id": "00000000-0000-0000-0000-000000000000",
      "phones": [],
      "photo_binary_id": "string",
      "preferred_language": "en",
      "preferred_pharmacy": {
        "address_city": "string",
        "address_state": "string",
        "address_street1": "string",
        "address_street2": "string",
        "address_zip": "string",
        "fax": "string",
        "is_mail_order": false,
        "name": "string",
        "ncpdp_id": "string",
        "notes": "string",
        "npi": "string",
        "pharmacy_id": "string",
        "phone": "string"
      },
      "race": [
        "american_indian_or_alaska_native"
      ],
      "sex_at_birth": "male",
      "steadymd_patient_guid": "string",
      "steadymd_program_guid": "string"
    }
  ],
  "total": 0
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `401` | [`fieldagent.ErrorResponse`](../models/fieldagent.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
| `500` | [`fieldagent.ErrorResponse`](../models/fieldagent.ErrorResponse.md) | application/json | Internal server error |

## Error examples

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 500 — Unexpected service failure (sanitized example)

```json
{
  "error": "Internal server error"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
```

```ts
const query = {
  "created_by": "<CREATED_BY>",
  "family": "<FAMILY>",
  "given": "<GIVEN>",
  "limit": 20,
  "page_token": "<PAGE_TOKEN>"
};

const result = await fieldAgent.listPatients(query);
```

## cURL

```bash
curl -X GET \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  'https://dev-api-fieldagent.health.cloud/patients?created_by=%3CCREATED_BY%3E&family=%3CFAMILY%3E&given=%3CGIVEN%3E&limit=20&page_token=%3CPAGE_TOKEN%3E'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.