Skip to main content

​
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 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:
pcp_code is the patient’s primary care provider code, and is a valid physician_code for practicesuite_save_appointment 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:
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.