Skip to main content

ModMed

ModMed is a major specialty-medicine EMR (dermatology, ophthalmology, orthopedics, plastic surgery, and others). The ModMed tool lets your assistant act as a phone receptionist that's actually connected to the practice — looking up patients, listing available slots, booking new appointments, and creating new patient records. It talks to ModMed's FHIR v2 API on your firm's behalf.

Healthcare context​

The standard deployment: a medical practice forwards their main phone line (or a specific receptionist line) to an Insighto voice agent. The agent identifies the caller, helps them book or reschedule, and captures new-patient details. Anything off-script is transferred to a real human via the transfer-call tool.

This is a practice operations integration — the assistant doesn't access charts, results, or clinical content. It works with five FHIR resources: Patient, Appointment, Slot, Location, and Practitioner.

Prerequisites​

Healthcare integrations are gated. You'll need:

  • An active ModMed FHIR API contract for your practice.
  • A signed BAA between your practice and Insighto.
  • A ModMed-issued x-api-key and OAuth credentials (username + password) tied to your firm.
  • Your practice's firm_url_prefix (the path segment after ema-prod/firm/ in your ModMed URL — e.g. acmederm).

Contact support before starting — Insighto can help expedite the BAA and the ModMed-side paperwork.

Connecting​

ModMed uses OAuth 2.0 password grant against its FHIR auth endpoint:

  1. In ModMed admin, request the FHIR API credentials for your Insighto integration.
  2. In Insighto: Tools & Integrations → ModMed → Add.
  3. Provide:
    • firm_url_prefix (e.g. acmederm)
    • x-api-key (issued by ModMed)
    • username and password (service-account credentials)
    • location_id — the FHIR Location resource ID for this practice site
    • practitioner_id — the FHIR Practitioner ID
    • appointment_duration (minutes)
    • timezone (IANA, e.g. America/New_York)
    • Optional: email (where booking confirmations are sent), practitioner_name (used in the email subject)
  4. Insighto runs the OAuth grant and stores the refresh token. From then on, every conversation that uses this tool refreshes the access token automatically.

Functions the assistant can call​

The five functions the model can invoke:

search_patient​

Looks up an existing patient.

  • Arguments

    • phone (string, optional) — patient's phone number.
    • email (string, optional) — patient's email.

    One of the two is required.

  • Returns — the patient's ID on a match, undefined on no match.

create_patient​

Creates a new patient record.

  • Arguments
    • given_name (string, required) — first name.
    • family_name (string, required) — last name.
    • birthdate (string, required) — YYYY-MM-DD.
    • email (string, required)
    • phone (string, required)
  • Returns — "Created the patient with ID: <id>".

find_available_slots​

Lists open appointment slots for a given appointment type across a date range.

  • Arguments
    • appointment_start_date (string, required) — YYYY-MM-DD.
    • appointment_end_date (string, required) — YYYY-MM-DD.
    • appointment_type_id (string, required) — the type of visit.
  • Returns — slot times in the configured timezone.

get_earliest_appointments​

Convenience wrapper for the next three days.

  • Arguments
    • appointment_type_id (string, required).
  • Returns — earliest open slots.

create_appointment​

Books an appointment for an identified patient.

  • Arguments
    • appointment_date (string, required) — YYYY-MM-DD.
    • appointment_time (string, required) — HH:MM.
    • appointment_type_id (string, required).
    • summary (string, required) — short reason for the visit.
    • patient_id (string, optional) — if known.
    • phone_number (string, optional) — used to find the patient if patient_id not given.
    • email (string, optional) — used as a fallback to find the patient.
  • Returns — "Created the Appointment with ID: <id>". If an email is configured on the tool, a confirmation email is sent automatically.

Setup-time lookups​

During the Add ModMed flow, Insighto auto-populates dropdowns for Practitioner, Location, and Appointment Type by reading them from ModMed. You don't need to type IDs by hand — pick from the lists.

Example function-call payload​

A create_appointment invocation:

{
  "tool_name": "create_appointment",
  "arguments": {
    "appointment_date": "2026-05-20",
    "appointment_time": "10:00",
    "appointment_type_id": "apt_new_consult_30min",
    "summary": "New patient consultation — concerns about a mole on left arm.",
    "phone_number": "+15551234567"
  }
}

On success: "Created the Appointment with ID: 12345". If email is configured on the tool, a confirmation email is sent automatically with the appointment details.

HIPAA, PHI, and what gets logged​

  • Patient identifiers used in tool calls (name, DOB, phone, email) are encrypted in transit and at rest.
  • Call transcripts and recordings that contain PHI are stored encrypted at rest.
  • A BAA must be in place between your practice and Insighto before this tool is enabled.

If your compliance officer needs more detail, Insighto provides a HIPAA architecture document on request.

Use case: phone receptionist for a dermatology practice​

  1. Patient calls the practice's main number, which rolls to the Insighto-connected line.
  2. Assistant greets, asks if they're an existing patient.
  3. Existing patient: assistant collects phone or email, calls search_patient to find the record.
  4. Caller wants to book: assistant calls find_available_slots for the requested appointment type over a small date window, reads back three options, then create_appointment with the chosen slot.
  5. New patient: assistant collects name, DOB, phone, email, calls create_patient, then create_appointment.
  6. Anything off-script (medication refills, clinical questions) → forward to the on-call line via forward_call.

Provider, location, and appointment types​

These are configured at the tool-instance level, not per-call:

  • location_id and practitioner_id are baked into every create_appointment call.
  • appointment_type_id is per-call — either let the model pick from a list you describe in the system prompt, or hardcode it.

For multi-provider or multi-location practices, create one tool instance per (provider, location) combination — that's the cleanest way given how this tool models the world.

Patient identification — getting it right​

The single biggest correctness issue with EMR voice agents is identifying the wrong patient. search_patient matches by phone or email (one identifier). Practical guardrails:

  • Read back the match before booking: "I have you at the phone number ending in 4422 — is that you?"
  • If the search returns no result, ask the caller to confirm their info; don't book against a stranger.
  • For higher assurance, capture DOB as well, and verify against the patient record the lookup returned.

After-hours mode​

A common deployment pattern is to have the ModMed-connected assistant active only after business hours, with a Workflow toggling it on at 5 PM and off at 8 AM.

Failure modes​

  • Patient not found — search_patient returns undefined. The assistant should ask the caller to confirm spelling or escalate.
  • Slot conflict — Two parallel callers booking the same slot; the second gets a ModMed error returned as the tool result. The model usually re-offers another slot.
  • API downtime — ModMed maintenance windows happen. The tool has no automatic retries; fall back to transferring the call.
  • Token expired — Insighto refreshes the access token on every conversation init. If the refresh token itself is invalidated (password reset, etc.), reconnect with new credentials.

Where to next​

  • Pair with Disconnect & transfer for cases the assistant can't handle.
  • For cancel / reschedule flows, build a Custom tool on top of ModMed's FHIR API.
  • Build practice-specific scheduled flows in Workflows.