Contact Import and Export Formats
Supported CSV, VCF, PracticeRunner JSON, and FHIR R4 formats for contact and case import/export.
Use Settings → Contacts for contact and supported case-membership import/export. This is a self-service way to add or update contacts and reconstruct supported cases from a compatible VCF without running a complete practice migration.
- Import:
.csv,.vcf,.json, or.fhir.json - Export: CSV, VCF, PracticeRunner JSON, or FHIR R4
This article explains which spreadsheet and contact file formats work best and how PracticeRunner reads them.
Choose a format
| Format | Best for | What it preserves |
|---|---|---|
| CSV | Editing a contact list in Excel, Numbers, or another spreadsheet | Contact and demographic fields only |
| Individual VCF | Moving ordinary contacts between address books | Contact fields only |
| PracticeRunner-compatible VCF | Moving contacts between PracticeRunner organizations or systems that retain vCard groups and custom fields | Contact fields plus supported case membership and member roles |
| Legacy combined couple VCF | Importing a combined couple card, including supported SimplePractice-style cards | Two contacts and one inferred couple case |
| PracticeRunner JSON | The closest contact-and-case round trip between PracticeRunner organizations | All exported email and phone entries, optional address/DOB and notes, contact type, supported case membership, and member roles |
| FHIR R4 | Exchanging contacts and cases with systems that accept FHIR bundles | Patient contacts and Group cases, with PracticeRunner extensions for contact type, case type, and member roles |
PracticeRunner JSON uses the versioned practicerunner-transfer contract, scoped to contacts and supported cases. FHIR exports are R4 collection bundles. PracticeRunner-specific extensions provide the case meaning that base FHIR resources cannot express on their own.
If you need appointments, clinical notes, billing history, forms, uploaded files, or payments, use the appropriate data import or data export workflow instead.
Contact Import (CSV)
Supported CSV layouts
- Split-name format (for example:
First Name,Middle Name,Last Name) - Full-name format (for example:
ClientorFull Name) - SimplePractice Client Details Report format
At minimum, each row needs either:
First Name+Last Name, orClient/Full Name
CSV field mapping
| CSV column (accepted names) | Imported to |
|---|---|
First Name, Firstname, Given Name |
Client.firstName |
Middle Name, Middlename |
Client.middleName |
Last Name, Lastname, Surname, Family Name |
Client.lastName |
Client, Name, Full Name, Client Name |
Split into firstName, middleName, lastName |
Email |
Main client email (ClientEmail.address) |
Phone |
Client.phone and main ClientPhone.number |
Date of Birth, DOB |
Client.dob |
Address, Street |
Client.street |
City |
Client.city |
State |
Client.state |
Zip, Postal |
Client.zip |
Country |
Client.country |
Notes |
Client.notes |
Date Added |
Client.dateFirstSeen |
Status (Active, Archived, Prospect) |
Client.status (normalized to ACTIVE, ARCHIVED, PROSPECT) |
Primary Clinician, Clinician |
Matched to the clinician by full name. If no match is found, the importing user is assigned |
Primary Insurance, Insurance, Payer |
ClientInsurance.payer |
Insurance ID, Member ID |
ClientInsurance.memberId |
Notes:
- New contacts default to
ACTIVEunless the file says otherwise. - Insurance details are only created when the file includes insurance information.
Contact Import (VCF)
Supported VCF expectations
- Standard individual vCard 3.0 and 4.0 cards
- Individual cards
- Legacy couple cards with
&/＆in name fields - PracticeRunner vCard 4.0 group cards for couples, families, therapy groups, individual consultations, and consultation groups
VCF field mapping
| VCF field | Imported to |
|---|---|
N: family/given/additional |
lastName, firstName, middleName |
FN: |
Used when separate name fields are missing and to normalize full names |
EMAIL |
Main client email (ClientEmail.address) |
TEL |
Client.phone and main ClientPhone.number |
BDAY |
Client.dob |
ADR |
street, city, state, zip, country |
NOTE |
Client.notes |
UID and MEMBER |
Links individual cards to a supported case group |
KIND:group |
Identifies a case group card |
X-PRACTICERUNNER-CONTACT-TYPE |
Distinguishes therapy clients from consultation clients |
X-PRACTICERUNNER-CASE-TYPE |
Identifies the supported case type |
X-PRACTICERUNNER-MEMBER;ROLE=... |
Preserves each person’s role in the case |
Additional VCF behaviors:
- Middle initials/names are normalized into
middleName. - If the middle name is missing in the card fields, PracticeRunner can use the filename when it includes the missing name.
- Legacy combined couple cards are split into two contacts and one couple case. PracticeRunner does not create additional individual cases for newly imported couple members.
- PracticeRunner group cards can create or reuse a couple, family, therapy group, individual consultation, or consultation group and link the imported contacts as members.
- Consultation cases import their members as consultation clients. Therapy cases import their members as therapy clients.
- Couples require exactly two members, individual consultations require exactly one, and families or groups require at least two.
- Case reconstruction depends on group and custom VCF fields. A contacts app that removes those fields may leave the individual contacts intact but remove the information needed to rebuild the case.
What happens when a case is imported
- PracticeRunner matches or creates each contact first, then creates the supported case from the resolved contacts.
- If an active case of the same type already has exactly the same members, PracticeRunner reuses it instead of creating a duplicate.
- If a matched contact already has an individual case, that individual case remains available. Import does not close or delete existing cases.
- Couples, families, and individual consultations begin with the first listed member as the billing contact and payer.
- Therapy groups and consultation groups begin with billing tracked separately for each participant.
- Review case roles and billing after import, especially when the source was a legacy combined couple card.
The contact workflow does not preserve appointments, clinical notes, billing history, forms, uploaded files, payments, case-specific fees, selected services, identified-client settings, a separately chosen billing contact, or inactive and historical membership periods. The optional contact note is a non-clinical contact field and is separate from clinical notes.
Download sample VCF files
- Couple case sample
- Family case sample
- Therapy group sample
- Individual consultation sample
- Consultation group sample
You can open these files in a text editor and replace the sample names and contact details. Keep each UID unique within the file, and make sure every MEMBER value matches the UID of one individual card in that file.
De-duplication and Merge Behavior
When importing, PracticeRunner tries to match an existing contact in this order:
- Same first+last name and same email
- Same first+last name and same phone
- Unique first+last match (only when no email/phone provided)
- Unique email match when name matching is not enough
- Unique phone match when name and email matching are not enough
If PracticeRunner finds a match, it updates the existing contact. If not, it creates a new one.
Contact Export
Exports include active clients from your organization. VCF, PracticeRunner JSON, and FHIR exports also include supported active cases whose active members are included in the export.
CSV exports do not include case membership. Use PracticeRunner JSON for the closest PracticeRunner-to-PracticeRunner contact and case round trip, VCF for contact-app compatibility, or FHIR R4 for standards-based exchange.
PracticeRunner JSON and FHIR R4
- PracticeRunner JSON preserves every exported email and phone entry, rather than only one primary value.
- Both formats preserve supported active cases and current member roles.
- Consultation case members retain their consultation-client contact type.
- Address/DOB and the non-clinical contact note are included only when you select those export options.
- FHIR uses
Patientfor contacts andGroupfor cases. Keep PracticeRunner extensions intact when another system stores or forwards the bundle if you need a later case-aware round trip. - Files are previewed before import, and duplicate contacts and cases follow the same matching rules as VCF imports.
CSV export columns
| CSV column | Source |
|---|---|
First Name |
Client.firstName |
Last Name |
Client.lastName |
Email |
Main ClientEmail.address |
Phone |
Client.phone |
Date of Birth |
Client.dob |
Street |
Client.street |
City |
Client.city |
State |
Client.state |
Zip |
Client.zip |
Country |
Client.country |
Notes |
Client.notes |
VCF export fields
| VCF field | Source |
|---|---|
N:last;first;middle;; |
Client.lastName, Client.firstName, Client.middleName |
FN:first middle last |
Name display field |
EMAIL;TYPE=INTERNET |
Main ClientEmail.address |
TEL;TYPE=CELL |
Client.phone |
KIND:individual |
Identifies a person card |
UID |
Stable reference used by case group cards |
X-PRACTICERUNNER-CONTACT-TYPE |
Therapy or consultation contact type |
KIND:group and MEMBER |
Supported case and its members |
X-PRACTICERUNNER-CASE-TYPE |
COUPLE, FAMILY, THERAPY_GROUP, INDIVIDUAL_CONSULTATION, or CONSULTATION_GROUP |
X-PRACTICERUNNER-MEMBER;ROLE=... |
Case member role |