Skip to main content

​
PracticeSuite Upload Document

This document covers practicesuite_upload_document, the native PracticeSuite document-attachment 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_upload_document

Attaches a document to a patient’s Documents tab via POST /v2/api/patient/patientDocUpload. This is a mutating tool.

​
The identifier this tool requires

patient_id here is PracticeSuite’s internal patient UUID (e.g. 196CCD0A90FB2053E0630100007FD249), obtained from practicesuite_get_patient. The natural key (patient_pcref) used by the patient and appointment tools is not accepted and would target the wrong record. The parameters are deliberately named differently to keep them apart.

​
Inputs

Required:
  • account_id — practice tenant holding the patient.
  • patient_id — PracticeSuite’s internal UUID from practicesuite_get_patient.
  • file_url — URL of the file to attach. The platform downloads it and sends it Base64-encoded.
Optional:
  • file_name — name to store the document under. Defaults to the file’s own name from the URL.
  • document_type — PracticeSuite document type. Defaults to Other.
  • document_date — MM/DD/YYYY. Defaults to today.
  • description
  • provider_code — file the document under a specific provider.
access_token, client_id, client_secret and environment are injected from the integration and hidden from the model.

​
Output

A successful call returns an empty response_code; codes are populated on failure and are bare numbers (1013, 1020). Some failures carry no code at all and put everything in the message — save_appointment reports an unknown provider as Code: 100. Message: Provider Not Found. The rendered result also reports the uploaded file name and size. A success: false body becomes a tool error carrying response_code and response_msg.

​
Limits and caveats

  • The file is base64-encoded and sent in a single JSON request, so the whole document is held in memory. Uploads are capped at 50 MB by the tool. The check runs after the file is fetched — the platform’s file service buffers the whole thing and takes no limit — so the cap bounds the base64 and JSON encoding that follows (~2.3× the raw bytes) rather than the download itself. PracticeSuite’s own maximum is undocumented and may be lower.
  • The tool has no dedupe key: a retried step re-attaches the document. Prefer resolving patient_id once and uploading once per task.
  • The request timeout is 120 seconds.
  • The document data type is inferred from the file extension (PDF when there is none). Only PDF is verified against PracticeSuite — other extensions are passed through uppercased and may not match its accepted vocabulary.
  • An empty or unreachable file_url is a tool error; nothing is written.

​
Agent Instruction Guidance

Always resolve the UUID first: practicesuite_save_patient → practicesuite_get_patient → practicesuite_upload_document, passing the patient_id the lookup returned. If practicesuite_get_patient reported found: false, stop — do not attempt the upload with a natural key.