Help / Admin & billing

Practice Data Import CSV templates and column reference

Use this column-by-column reference when preparing spreadsheets for the Practice Onboarding importer at /administrator/practice-onboarding (Practice Onboarding in the Administrator sidebar). Every column name, required flag, accepted value, validation rule, and fallback default below matches the live importer and downloadable CSV templates.

For the step-by-step upload walkthrough and silent video overview, see:

• Onboard a practice with the Practice Onboarding importer
• How do I move my practice's patient data into Medipyxis? (What's new video guide)

Templates overview

Download the latest template directly from each step's Upload screen on /administrator/practice-onboarding. Templates include a UTF-8 byte-order mark (BOM) and a leading sep=, hint line so Microsoft Excel opens them cleanly; the importer strips sep=, automatically when you upload the file back.

Step	Module	Template file name	Prerequisite	Produces ID column	Status
1	Patients	patient_import_template.csv	—	patient_uid (patients_import_results.csv)	Active
2	Insurance	insurance_import_template.csv	Step 1 (patient_uid)	—	Active
3	Medications	medications_import_template.csv	Step 1 (patient_uid)	—	Active
4	Allergies	allergies_import_template.csv	Step 1 (patient_uid)	—	Active
5	Comorbidities	comorbidities_import_template.csv	Step 1 (patient_uid)	—	Active
6	Emergency Contacts	contacts_import_template.csv	Step 1 (patient_uid)	—	Active
7	Wounds (read-only history)	wounds_import_template.csv	Step 1 (patient_uid)	wound_uid (wounds_import_results.csv)	Active
8	Documents & Historical Wound Photos	documents_import_template.csv	Step 1 (patient_uid; optional wound_uid / wound_id from Step 7)	—	Active
9	Visit History (read-only history)	visit_history_import_template.csv	Step 7 (patient_uid, optional wound_uid / wound_id)	—	Active

Step 1 — Patients (patient_import_template.csv)

The Patients template contains 22 columns across three groups:

1. Core demographic and provider fields (11 columns — 3 required, 8 optional)
2. Identity and duplicate-handling fields (3 optional columns)
3. Patient consent attestation fields (consent_*, 8 optional columns)

Core demographic and provider columns

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
first_name	Required	Text	Non-empty patient first name.	Row is rejected on Confirm if blank.
last_name	Required	Text	Non-empty patient last name.	Row is rejected on Confirm if blank.
date_of_birth	Required	Date (YYYY-MM-DD)	Valid calendar date in YYYY-MM-DD (recommended) or MM/DD/YYYY. Rollover dates such as 2026-02-31 are rejected before write.	Row is rejected if blank or not a real calendar date.
phone	Optional	Text	Patient phone number (e.g., 555-123-4567).	Stored as null if blank.
email	Optional	Email	Must match name@domain.tld if provided.	Stored as null if blank; invalid format triggers a validation error.
address_street	Optional	Text	Street address (e.g., 123 Main St).	Stored as null if blank.
address_city	Optional	Text	City name (e.g., Springfield).	Stored as null if blank.
address_state	Optional	Text (2-letter US state)	Validated against standard 2-letter US state and territory codes (AL–WY, DC, PR, VI, GU, AS, MP), case-insensitive.	Normalized to uppercase; stored as null if blank. Invalid state codes are flagged on Confirm.
address_zip	Optional	Text (ZIP code)	5-digit (62701) or 9-digit (62701-1234) US ZIP code.	Stored as null if blank. Invalid formats are flagged on Confirm.
provider_email	Optional	Email	Email address of an existing clinician/provider in the facility (user_profile / providers).	Matched: Assigns the provider and sets patient status to ASSIGNED. Blank or unmatched: Imports the patient unassigned (status = NEW) and adds a non-blocking Needs Follow-Up warning so an admin can assign a provider later.
notes	Optional	Text	Free-text onboarding or chart note (e.g., Transferred from Dr. Adams).	Saved to the patient's standalone notes table (note_date = import date, deduplicated by (source, external_id) on re-import).

Identity & duplicate handling (prior_ehr_* and duplicate_decision)

When migrating from another EHR, two different patients can legitimately share a first name, last name, and date of birth, or the same CSV may be uploaded more than once. Medipyxis uses three optional columns to prevent both silent wrong-person merges and accidental duplicate charts:

Column (key)	Required	Type / Format	How it works
prior_ehr_system	Optional	Text	Name of the source EHR (for example, DrChrono, PointClickCare, Athena). Namespaces prior_ehr_mrn in patient.external_id as <prior_ehr_system>:<mrn> (lowercased, colons removed).
prior_ehr_mrn	Optional	Text	Patient's chart number or MRN in the prior EHR. Leading zeros are normalized (001842 and 1842 match the same ID). When re-importing, a matching prior_ehr_mrn + first_name + date_of_birth is recognized as the same patient and counted as Skipped (existing) while still returning patient_uid. If prior_ehr_mrn matches an existing patient whose first_name or date_of_birth differs, the row is blocked with an error unless explicitly confirmed via duplicate_decision so a mistyped MRN never merges two different people.
duplicate_decision	Optional	UUID or NEW	Resolves a row held for review when first_name + last_name + date_of_birth matches an existing patient in the facility without a matching prior_ehr_mrn: Enter the existing patient_uid UUID (shown in the error message) to link/reuse that existing chart and backfill its external_id. Enter NEW (case-insensitive) to confirm this row is a different person with the same name and date of birth and create a separate patient record. (If the existing same-name patient was also imported without a prior_ehr_mrn, provide prior_ehr_mrn alongside NEW so subsequent runs can tell the two charts apart.)

Patient consent attestation columns (consent_*)

All 8 consent_* columns in patient_import_template.csv are optional and let an administrator record that the practice already holds a signed treatment and billing consent form on file for an incoming patient.

Gating rule (consent_on_file)

Everything gates on consent_on_file:

• If consent_on_file is blank or no (false, 0, n), no consent attestation is created and the other 7 consent_* columns are completely ignored—even if those 7 columns contain values.
• If consent_on_file contains an unrecognized value (anything other than yes/no, true/false, 1/0, y/n), the patient still imports, no consent is recorded, and a non-blocking warning is added to the Needs Follow-Up list.

Clinical and compliance rule (practice's own consent only)

Setting consent_on_file = yes writes a patient_consents record (collection_method = 'external_attested', text_version = 'external', status = 'current', consent_to_treatment = true, consent_to_bill = true) attested under the signed-in administrator's user account (obtained_by_user_id).

• Only set consent_on_file = yes when your practice holds its own signed treatment and billing consent form for that patient (signed by the patient or their legal POA / healthcare surrogate).
• Never use a skilled nursing facility's (SNF) admission paperwork to satisfy consent_on_file = yes, and never list facility staff as the signer. Nursing facility admission packets authorize the facility, not an independent wound-care practice, and facility staff cannot legally consent on a resident's behalf.
• If a patient already has a current consent record in Medipyxis, re-importing with consent_on_file = yes leaves the existing consent untouched and logs a non-blocking warning.

All 8 consent_* columns and defaults

Column (key)	Required	Accepted values	Behavior & exact default when consent_on_file = yes
consent_on_file	Optional	yes / no (also accepts true / false, 1 / 0, y / n, case-insensitive)	Master gate. When blank or no, no consent row is created and all other consent_* columns are ignored. When yes, records an external_attested treatment + billing consent.
consent_signed_on	Optional	Date (YYYY-MM-DD or MM/DD/YYYY)	Stored in external_signed_on (YYYY-MM-DD) and sets signed_at to YYYY-MM-DDT00:00:00Z. Default if blank or unreadable: external_signed_on = null and signed_at defaults to the import timestamp (now). An unreadable date logs a warning on the Confirm screen and never blocks the patient import.
consent_signer_capacity	Optional	patient, poa, or surrogate (case-insensitive)	Indicates who signed the form (patient, legal power of attorney poa, or healthcare surrogate). Default if blank or any other value: patient (unrecognized values also log a Needs Follow-Up warning).
consent_signer_name	Optional	Text (full name of signer)	Stored in signer_name. Required in practice workflows when consent_signer_capacity is poa or surrogate. Default if blank: <first_name> <last_name> from the same CSV row.
consent_witnessed	Optional	yes / no (true / false, 1 / 0, y / n)	Stored in external_witnessed. Default if blank: null (not recorded). yes stores true; no stores false.
consent_location	Optional	Text (where the signed form is kept, e.g., Paper chart, DrChrono archive)	Stored in external_document_location. Default if blank: practice records (onboarding import).
consent_photo	Optional	yes / no (true / false, 1 / 0, y / n)	Clinical wound photography consent (consent_to_photo). Default if blank or no: false (photography consent is off unless explicitly attested yes).
consent_npp_acknowledged	Optional	yes / no (true / false, 1 / 0, y / n)	HIPAA Notice of Privacy Practices acknowledgement (npp_acknowledged). Default if blank or no: false (off unless explicitly attested yes).

Persistent patient_uid download & idempotent re-imports

Downloading patient_uid (and wound_uid) mappings anytime

Steps 2 through 9 link every row back to a patient using patient_uid (the Medipyxis UUID generated in Step 1), and Steps 8 and 9 optionally link historical wound photos, wound-specific documents, and visits to wounds using wound_uid / wound_id (generated in Step 7). You can download those IDs in two places:

1. Immediately after an import finishes: Click Download Results CSV in the blue banner on the Results screen to download patients_import_results.csv or wounds_import_results.csv.
2. Anytime later on /administrator/practice-onboarding: Completed Step 1 — Patients and Step 7 — Wounds cards display a persistent Download results CSV action (rebuilt server-side via batch_results from the saved batch mapping). This lets you re-download patient_uid and wound_uid mappings even after clicking Done, refreshing the browser, or signing in from another computer.
   • patients_import_results.csv columns: csv_row, first_name, last_name, date_of_birth, patient_uid
   • wounds_import_results.csv columns: csv_row, patient_uid, wound_location, wound_type, first_seen_date, wound_uid

How re-importing works (Skipped (existing) and batch statuses)

Every active step in the Practice Onboarding importer is idempotent:

• Natural-key deduplication: If you re-upload the same CSV (or a superset CSV containing previously imported rows alongside new rows), Medipyxis checks whether each record already exists for that patient/facility:
  • Step 1 (Patients): Matches on (facility_id, external_id) + first_name + date_of_birth, or explicit duplicate_decision = <patient_uid>, or an already-imported identical (first_name, last_name, date_of_birth) when external_id is blank on both.
  • Step 2 (Insurance): Matches on (patient_id, insurance_provider, policy_number) (case-insensitive).
  • Step 3 (Medications): Matches on (patient_id, name) (case-insensitive).
  • Step 4 (Allergies): Matches on (patient_id, allergen_name) (case-insensitive).
  • Step 5 (Comorbidities): Merges and deduplicates condition strings (case-insensitive) into patient.conditions[].
  • Step 6 (Emergency Contacts): Matches on (patient_id, contact_name, phone_number) (case-insensitive).
  • Step 7 (Wounds): Matches on (patient_id, wound_location, wound_type, first_seen_date) in wound_import_history.
  • Step 8 (Documents & Historical Wound Photos): Deduplicates by SHA-256 content hash (external_id = po_<sha256>) in public.documents and wound_import_history.photo_urls.
  • Step 9 (Visit History): Matches on (patient_id, service_date, visit_number, provider_name, visit_summary) in visit_import_history.
• Skipped (existing) count & UID return: Rows that already exist are not duplicated; they increment the Skipped counter (skipped_count). For Step 1 (Patients) and Step 7 (Wounds), skipped existing rows still return their existing patient_uid or wound_uid in the results CSV so you never lose your ID mapping.
• Step card progress & batch status:
  • Each step card shows cumulative imported rows across all batches plus the latest run breakdown: <N> imported total · last run: X imported, Y skipped, Z errors.
  • Complete (completed): All importable rows were imported or skipped with 0 errors.
  • Completed with errors (Import Completed with Errors): At least 1 row was imported or skipped, and 1 or more rows had errors. Good rows are committed immediately; you can fix only the failed rows and re-upload without duplicating the rows that succeeded.
  • Failed (failed): Recorded only when success_count = 0, skipped_count = 0, and error_count > 0 (no rows could be imported at all).

Steps 2–9 column-by-column reference tables

Step 2 — Insurance (insurance_import_template.csv)

Creates patient coverage records in patient_insurances with coverage_order = 1 (primary) and is_active = true.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid UUID from Step 1 patients_import_results.csv belonging to a patient in the active facility.	Row is rejected if missing, not a UUID, or not found in the facility.
insurance_provider	Required	Text	Payer / insurance company name (e.g., BlueCross BlueShield, Medicare).	Row is rejected if blank.
policy_number	Required	Text	Policy or subscriber ID number (e.g., BCBS-998877).	Row is rejected if blank.
group_number	Optional	Text	Plan group number (e.g., GRP-001).	Stored as null if blank.
member_id	Optional	Text	Member ID if distinct from policy_number.	Stored as null if blank.
effective_date	Optional	Date (YYYY-MM-DD)	Coverage effective start date (YYYY-MM-DD or MM/DD/YYYY).	Stored as null if blank.
subscriber_name	Optional	Text	Full name of the policy subscriber (e.g., Jane Doe).	Stored as null if blank.
subscriber_dob	Optional	Date (YYYY-MM-DD)	Subscriber's date of birth (YYYY-MM-DD or MM/DD/YYYY).	Stored as null if blank.
subscriber_relationship	Optional	Text	Relationship of the patient to the subscriber (e.g., Self, Spouse, Child).	Stored as null if blank (downstream billing readers treat null as Self).

Step 3 — Medications (medications_import_template.csv)

Creates records in patient_medications with source = 'imported'.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid patient_uid in the active facility.	Row is rejected if invalid or not found.
name	Required	Text	Medication name (e.g., Metformin).	Row is rejected if blank.
dosage	Optional	Text	Strength / dose (e.g., 500mg).	Stored as null if blank.
frequency	Optional	Text	Dosing schedule (e.g., Twice daily, BID).	Stored as null if blank.
route	Optional	Text	Administration route (e.g., Oral, Topical, IV).	Stored as null if blank.
prescribing_physician	Optional	Text	Prescriber name (e.g., Dr. Smith).	Stored as null if blank.
start_date	Optional	Date (YYYY-MM-DD)	Date medication was started/prescribed.	Populates both start_date and date_prescribed; null if blank.
status	Optional	Text	active, discontinued (aliases: stopped, inactive, d/c, dc), or held (aliases: hold, on_hold).	Defaults to active if blank. Unrecognized values default to active and log a non-blocking warning.

Step 4 — Allergies (allergies_import_template.csv)

Creates records in patient_allergies with source = 'imported'.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid patient_uid in the active facility.	Row is rejected if invalid or not found.
allergen_name	Required	Text	Allergen name (e.g., Penicillin, Latex).	Row is rejected if blank.
allergy_type	Optional	Text	medication, food, environmental, latex, insect, other, or nkda (case-insensitive).	Defaults to other if blank. Unrecognized values default to other with a warning.
severity	Required	Text	mild (aliases: low, minor), moderate, severe, life_threatening (aliases: life-threatening, life threatening, high, critical, anaphylaxis), or none.	Required on the Confirm screen; if an unrecognized value reaches the backend, it defaults to moderate with a warning.
reaction_description	Optional	Text	Description of the reaction (e.g., Hives and swelling, Anaphylaxis).	Stored as null if blank.
status	Optional	Text	active, inactive, resolved, unknown, or not_applicable (alias: n/a).	Defaults to active if blank (or active with a warning if unrecognized).

Step 5 — Medical History / Comorbidities (comorbidities_import_template.csv)

Appends deduplicated condition names to the conditions array on the patient record (patient.conditions). Include one condition per row; multiple rows for the same patient_uid are grouped together automatically.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid patient_uid in the active facility.	Row is rejected if invalid or not found.
condition	Required	Text	Condition or diagnosis name (e.g., Type 2 Diabetes, Peripheral Vascular Disease, Hypertension).	Row is rejected if blank. Duplicate conditions already on the patient chart (case-insensitive) are skipped idempotently.

Step 6 — Emergency Contacts (contacts_import_template.csv)

Creates records in patient_emergency_contacts.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid patient_uid in the active facility.	Row is rejected if invalid or not found.
contact_name	Required	Text	Emergency contact's full name (e.g., John Doe).	Row is rejected if blank.
relationship	Optional	Text	Relationship to the patient (e.g., Spouse, Daughter, POA).	Stored as null if blank.
phone_number	Optional	Text	Contact phone number (e.g., 555-987-6543).	Stored as null if blank.
email	Optional	Email	Contact email address (name@domain.tld).	Stored as null if blank; invalid format is flagged on Confirm.
is_primary	Optional	Boolean	true / false, yes / no, 1 / 0 (case-insensitive).	Defaults to false if blank.

Step 7 — Wounds (wounds_import_template.csv) & Step 8 — Documents & Historical Wound Photos (documents_import_template.csv)

Step 7 (Documents) is currently disabled on /administrator/practice-onboarding and displays Not available yet. Documents and wound photographs are not migrated via CSV; upload clinical documents directly to the patient's chart after onboarding. If the documents import endpoint is invoked directly, it returns Document import is not available yet. No documents were imported.

For schema reference, the template columns defined in documentsImportConfig.ts are:

Column (key)	Required	Type / Format	Accepted values
patient_uid	Required	UUID	Valid patient_uid from Step 1.
file_name	Required	Text	Document file name (e.g., referral_jane_doe.pdf).
document_type	Optional	Text	referral, consent, lab_result, imaging, prior_auth, or other.
document_date	Optional	Date (YYYY-MM-DD)	Document date (YYYY-MM-DD).

Step 7 — Wounds, Step 8 — Documents & Historical Wound Photos, & Step 9 — Visit History

Read-only clinical history: Both imported wounds (Step 8) and imported visits (Step 9) are stored in dedicated read-only history tables (wound_import_history and visit_import_history). Clinicians can view them on the patient's chart for historical context, but imported history records cannot be edited, signed, or billed as active Medipyxis visits, and wound photos are not migrated. To document and bill a new encounter in Medipyxis, start a new visit on the patient's active chart.

Step 7 — Wounds (wounds_import_template.csv)

Produces wound_uid in wounds_import_results.csv so Step 8 (Documents & Historical Wound Photos, via wound_uid or wound_id) and Step 9 (Visit History) can link historical wound photos, wound-specific documents, and historical visits to specific historical wounds.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid patient_uid in the active facility.	Row is rejected if invalid or not found.
wound_location	Required	Text	Anatomical wound location (e.g., Left lower extremity, medial malleolus).	Row is rejected if blank.
wound_type	Optional	Text	Wound classification (e.g., Venous ulcer, Diabetic foot ulcer, Pressure injury).	Stored as null if blank.
wound_etiology	Optional	Text	Underlying etiology (e.g., Chronic venous insufficiency).	Stored as null if blank.
wound_status	Optional	Text	Status in prior EHR (e.g., active, healed, improving).	Defaults to active if blank.
length_cm	Optional	Number (decimal)	Length in centimeters using a period decimal (e.g., 3.2). Must be >= 0.	Stored as null if blank; non-numeric or negative values fail validation.
width_cm	Optional	Number (decimal)	Width in centimeters (e.g., 2.1). Must be >= 0.	Stored as null if blank; non-numeric or negative values fail validation.
depth_cm	Optional	Number (decimal)	Depth in centimeters (e.g., 0.4). Must be >= 0.	Stored as null if blank; non-numeric or negative values fail validation.
first_seen_date	Optional	Date (YYYY-MM-DD)	Date the wound was first documented (YYYY-MM-DD or MM/DD/YYYY).	Stored as null if blank.
prior_treatments	Optional	Text (comma- or semicolon-separated)	List of prior treatments (e.g., Compression therapy, Foam dressing). Split on , or ; into a text[] array.	Stored as null if blank.
diagnosis_codes	Optional	Text (comma- or semicolon-separated)	ICD-10 codes associated with the wound (e.g., I87.2, L97.429). Split on , or ; into a text[] array.	Stored as null if blank.
notes	Optional	Text	Free-text wound summary or prior treatment note.	Saved to treatment_notes on wound_import_history (null if blank).

Step 9 — Visit History (visit_history_import_template.csv)

Creates read-only historical encounter summaries in visit_import_history.

Column (key)	Required	Type / Format	Accepted values & validation	Default / Fallback behavior
patient_uid	Required	UUID	Valid patient_uid in the active facility.	Row is rejected if invalid or not found.
wound_uid	Optional	UUID (or comma/semicolon-separated UUIDs)	One or more wound_uid (or wound_id) values from Step 7's wounds_import_results.csv (stored in wound_import_ids[]).	Stored as null if blank. Any non-UUID token is dropped with a non-blocking warning so the visit row still imports.
service_date	Required	Date (YYYY-MM-DD)	Date of the historical visit (YYYY-MM-DD or MM/DD/YYYY).	Row is rejected if blank or invalid.
visit_number	Optional	Integer	Sequential visit number from the prior EHR (e.g., 1, 2). Must be a positive whole number.	Stored as null if blank; non-integer values are dropped with a warning on the backend or flagged on Confirm.
provider_name	Optional	Text	Name of the clinician who performed the historical visit (e.g., Dr. Jane Smith).	Stored as null if blank.
visit_summary	Optional	Text	Free-text clinical summary of the historical visit.	Stored as null if blank.

Date, number & CSV formatting checklist

Before uploading any CSV into the Practice Onboarding importer, verify the following formatting rules:

1. Format all dates as ISO YYYY-MM-DD (recommended):
   • Always prefer YYYY-MM-DD (for example, 2026-06-15) across date_of_birth, consent_signed_on, effective_date, subscriber_dob, start_date, first_seen_date, and service_date.
   • Avoid mixing MM/DD/YYYY and DD/MM/YYYY in the same file: Opening a CSV in Microsoft Excel under different regional settings can silently rewrite some cells as MM/DD/YYYY and others as DD/MM/YYYY. While the Confirm screen inspects every date column and converts unambiguous slash dates (15/06/2026 vs 06/15/2026), ambiguous dates where both numbers are 12 or below (such as 03/04/2026) default to US month-first (MM/DD/YYYY) and raise an amber warning banner on the Confirm screen. Because a transposed date_of_birth breaks payer eligibility and claim submission, format date columns as YYYY-MM-DD text before saving.
2. Impossible calendar / rollover dates are rejected before write:
   • Both the Confirm screen validator and the backend importer check exact calendar month lengths and leap years. Rollover dates that do not exist on the calendar—such as 2026-02-31, 2026-02-29 (non-leap year), or 2026-04-31—are rejected with Invalid calendar date rather than rolling into the following month.
3. Use a period (.) for decimal numbers:
   • Wound dimensions (length_cm, width_cm, depth_cm) must use a period decimal (3.2, not 3,2) and must be zero or greater.
4. Wrap fields containing commas in double quotes:
   • Any free-text cell that contains commas—such as wound_location ("Left lower extremity, medial malleolus"), prior_treatments ("Compression therapy, Foam dressing"), diagnosis_codes ("I87.2, L97.429"), or notes—must be enclosed in standard CSV double quotes ("...") so commas inside a field do not shift subsequent columns.
5. Leave the template header row intact:
   • Keep the exact lowercase snake_case column names on the header row so the Map Columns step auto-matches every field with 100% confidence. (If a downloaded template starts with Excel's sep=, hint line above the header row, you can leave it as-is—Medipyxis strips sep=, automatically on upload.)

Related

Auto-rendered from related: in frontmatter.