> For the complete documentation index, see [llms.txt](https://docs.mdintegrations.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mdintegrations.com/partner/key-concepts/patients-and-encounters.md). # Patients & Encounters Every clinical interaction in MDI is built around two core records: a **Patient** and an **Encounter**. The Patient stores identity and health history — who this person is and what MDI already knows about them. The Encounter represents a single physician review, and it's the record that actually moves through clinical work. ## Patient MDI creates a Patient record automatically the first time someone completes a Voucher-driven intake flow. If you're using your own intake form solution instead of MDI's, you'll need to create that patient record yourself through the API. Either way, the record ends up containing: * Demographic data (name, date of birth, contact details, address) * Identity proofing (vouched, drivers license photo) * Medical history and allergies * Height, weight, and other health indicators * Links to that person's Encounters, messages, and files Patient records persist over time, which matters most for returning customers. For a returning patient, pass their existing `patient_id` in the Voucher rather than creating a new record — doing so reuses the existing Patient and skips the demographic questions they've already answered. ## Encounter An **Encounter** is one physician review or consultation, created whenever a treatment plan needs clinical evaluation. It's essentially the container that brings together everything a physician needs to make a decision: * Intake answers (from the associated Questionnaire) * Attachments (photos, documents) * Lab results, if applicable * Chart notes * Prescriptions (the offerings requested by the patient) A single Patient can have many Encounters over time — a new medication request, a refill, a dosage change are all separate Encounters, each linked back to the same underlying Patient record. Note that an Encounter becomes billable as soon as a physician reviews it or does any work on it at all; whether that review ends in approval or rejection doesn't change the consultation charge, since the physician's time was spent either way. {% hint style="info" %} **Note**: Encounters are also referred to as Cases or Visits. These are simply different names for the same underlying record, depending on where you're looking: * In API responses and JSON payloads, it's a **case**. Fields such as `case_id`, `case_offerings`, and `case_questions` all refer to an Encounter. * In the Patient App, patients may see it labeled a **Visit**. {% endhint %} ## Encounter status lifecycle From the moment it's created to the moment it's resolved, an Encounter moves through a defined sequence of statuses as it gets assigned, reviewed, and either approved or cancelled. {% code expandable="true" %} ```mermaid stateDiagram-v2 direction LR [*] --> Created Created --> Assigned Assigned --> Approved Approved --> Processing Processing --> Completed Completed --> [*] Assigned --> Support Support --> Assigned Assigned --> Waiting Waiting --> Assigned state Cancel { direction LR Status --> Cancelled Cancelled --> [*] } ``` {% endcode %}
StatusMeaning
CreatedThe Encounter was added but has no assigned clinician. This state normally lasts seconds, until a physician becomes available.
AssignedThe active queue where a physician works the Encounter. If the assigned physician does not act for several hours, MDI automatically reassigns it.
SupportThe Encounter needs operational help, such as shipping, billing, or missing information. Support staff can assist after it moves here.
WaitingThe physician has messaged the patient and is waiting for their reply.
ApprovedThe physician has approved the treatment. From here Prior Authorization flows can be executed or the encounter gets moved forward automatically.
ProcessingThe prescription is being submitted to the pharmacy. No user action is available in this state.
CompletedThe prescription was approved and confirmed by the pharmacy.
CancelledFinal state. The physician rejected the Encounter, or it was set up incorrectly. It is usually still billed because the physician reviewed the patient's details.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.mdintegrations.com/partner/key-concepts/patients-and-encounters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.