Skip to main content
This document covers advancedmd_create_patient, the native AdvancedMD patient-creation tool exposed through the Agents Platform.

​
Authentication

AdvancedMD tools use the existing AdvancedMD connector (office_code, username, password). See advancedmd-find-patient.md for details.

​
advancedmd_create_patient

Creates a new patient in AdvancedMD with the addpatient API. This is a mutating tool. dry_run defaults to false: the tool creates the patient. Set dry_run=true to only build and return the payload without writing anything. By default the patient is created as their own responsible party (relationship self). To bill a separate guarantor — for example a parent for a minor — pass responsible_party (see below).

​
Inputs

Required:
  • first_name
  • last_name
  • dob: Date of birth in ISO-8601 format (YYYY-MM-DD).
Required for a non-dry-run create:
  • profile_id: The AdvancedMD location/office profile id. This is tenant-specific — it identifies the office the patient belongs to.
Optional:
  • dry_run: Defaults to false (the patient is created). Set true to preview only.
  • sex: M, F, or U (male/female also accepted).
  • financial_class_id: AdvancedMD financial class (finclass) id; tenant-specific.
  • chart: Chart number. Defaults to AUTO so AdvancedMD assigns one.
  • email
  • phone: +1/+ prefixes are stripped automatically.
  • phone_type: AdvancedMD othertype code, e.g. C (cell). Defaults to C.
  • address1, address2, city, state, zip
  • responsible_party: a separate guarantor (object). See below.

​
Responsible party (guarantor)

Omit responsible_party to make the patient their own responsible party (relationship self → AdvancedMD @relationship=4, @hipaarelationship=18). When responsible_party is supplied, the guarantor is created with their own demographics and the patient is linked as their dependent. Fields:
  • first_name, last_name: required when responsible_party is set.
  • relationship: the patient’s relationship to this guarantor. One of spouse, child, other. For a minor whose guarantor is their parent, use child (the patient is the guarantor’s child). This sets the standard HIPAA relationship code on the patient. Required unless hipaa_relationship is supplied directly.
  • dob, sex, ssn, phone, phone_type, email, address1/address2/city/state/zip: optional guarantor demographics.
  • account_type: AdvancedMD accttype. Defaults to 4.
  • hipaa_relationship: raw HIPAA relationship code override (e.g. 01 spouse, 19 child, G8 other). Overrides relationship.
  • amd_relationship_code: raw override for AdvancedMD’s internal @relationship master-file id.
Relationship codes. The friendly relationship enum maps to the standard HIPAA individual-relationship codes (spouse → 01, child → 19, other → G8), which are stable across tenants. It also sets a best-effort default for AdvancedMD’s internal @relationship code (1/2/5), but those master-file ids are tenant-specific — if a tenant’s master files differ, pass amd_relationship_code. Always inspect the dry_run payload before a real create.

​
Output

Dry run returns the resolved payload under patient with dry_run: true, created: false. A real run returns:
advancedmd_not_connected indicates AdvancedMD is not connected; the agent should ask the user to connect and try again, or stop the task.

​
Agent Instruction Guidance

This tool creates the patient by default (dry_run=false). When you want to verify the resolved payload before committing — especially for a non-self responsible party or an unfamiliar profile_id — call it once with dry_run=true, review the preview, then call again without dry_run. Make sure profile_id is the correct office for the patient — it is required and tenant-specific.