> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PracticeSuite Get Patient

> Looks up a PracticeSuite patient by natural key and returns the internal patient UUID.

# PracticeSuite Get Patient

This document covers `practicesuite_get_patient`, the native PracticeSuite patient lookup tool exposed through the Agents Platform.

## Authentication

Uses the PracticeSuite connector (`client_id`, `client_secret`, `environment`). See [practicesuite-save-patient.md](practicesuite-save-patient.md) for connection details and for the canonical `patient_pcref` derivation algorithm.

## `practicesuite_get_patient`

Looks a patient up via `POST /v2/api/patient/getPatient`. Read-only.

This tool exists to **bridge the two identifier lanes**: you search by the agent-computed natural key (`patient_pcref`, stored by PracticeSuite in its `PCREF` field) and it returns PracticeSuite's internal patient UUID (`patient_id`). That UUID is the only value `practicesuite_upload_document` accepts, so this call is a required step before attaching any document.

### Inputs

Required:

* `account_id` — practice tenant to search.
* `first_name`, `last_name`, `dob` — the tool derives the lookup key from these, identically to `practicesuite_save_patient`. **Or** pass `patient_pcref` on its own: this tool never sends the names anywhere, so an override makes them unnecessary.

`access_token`, `client_id`, `client_secret` and `environment` are injected from the integration and hidden from the model.

### Output

Found:

```json theme={null}
{
  "found": true,
  "patient_id": "196CCD0A90FB2053E0630100007FD249",
  "pcref": "tylerheath04131989",
  "mrn": "MRN-42",
  "pcp_code": "VHA32",
  "pcp_name": "Vashanda Hunter-Austin"
}
```

`pcp_code` is the patient's primary care provider code, and is a **valid `physician_code` for [`practicesuite_save_appointment`](practicesuite-save-appointment.md)** in that account. PracticeSuite exposes no provider-listing endpoint, so this is the only programmatic way to discover a usable provider code when no mapping has been supplied.

Not found:

```json theme={null}
{
  "found": false,
  "response_code": "1020",
  "response_msg": "There is no patient associated with this ID"
}
```

A patient that does not exist is a **normal outcome, not a tool error** — `found: false` lets the agent branch to `practicesuite_save_patient` and retry the lookup. Genuine failures (a rejected token with no way to re-mint, a malformed response, a success payload with no `patientId`) do surface as tool errors.

### Limits and caveats

* Verified against the sandbox: a patient saved as `zztest…01011990` came back with a distinct internal `patient_id` and an `MRN`, confirming the two identifier lanes are genuinely different values.
* Lookup is by `PCREF` only. PracticeSuite also exposes a `searchPatient` endpoint; it is not wired into this connector.
* `patient_id` is opaque — persist it for the duration of the task rather than re-deriving it.

## Agent Instruction Guidance

Call this after `practicesuite_save_patient` and before `practicesuite_upload_document`. Pass the returned `patient_id` — not the `patient_pcref` you searched with — to the upload tool; the two values are different and swapping them silently attaches the document to the wrong chart. If `found` is `false`, the patient was not created; do not proceed to the upload.