Flat File Integrations - Patients

File Name

When sending the file to the server it should be named using the following format: "patients_{timestamp}.csv"

Which Data

We suggest sending data for all current patients

Notes on Naming Fields


Mirah supports two different kinds of naming fields:

  • Legal Name is used for billing purposes and corresponds with insurance and legal.
  • Preferred Name is that used by the patient in day-to-day life.

For both of these, you may specify either:

  • Full name as one field
  • First (Given) and Last (Family) name separately.

You cannot specify both a full name as a single field, and a given and family name, of the same type.


Mirah requires at a minimum, one name field to be filled out for each patient.


Emails and Phone Numbers

Mirah does not require you to send a phone number or an email in order for the integration to process.  However, if customers wish to have patients receive notifications for assessments we strongly suggest that both are included.

Data Fields

NOTE: Please follow all field name and note formats, including case sensitivity.

Item Field name Format Req’d Notes
Medical record number mrn string Y This should be a guaranteed-unique identifier for the patient in your EHR. 
identifiers identifiers Identity Unless MRN See ”id” format detailed below.This column is used for systems which have multiple identifiers for a given patient.  If a system just has a single identifier for a patient, this column can be empty and just MRN can be used 
legal given name legalGivenName string Y* Patient's legal first/given name, as used on insurance documentation and legal forms. See above for notes on naming
legal family name legalFamilyName string Y* Patient's legal last/family name, as used on insurance documentation and legal forms. See above for notes on naming
legal full name legalName string Y* Patient's legal full name as a single field, as used on insurance documentation and legal forms. See above for notes on naming
preferred given name preferredGivenName string Y* Patient's preferred first/given name, as used on insurance documentation and legal forms. See above for notes on naming
preferred family name preferredFamilyName string Y* Patient's preferred last/family name, as used on insurance documentation and legal forms. See above for notes on naming
preferred full name preferredName string Y* Patient's preferred full name as a single field, as used on insurance documentation and legal forms. See above for notes on naming
preferred pronouns preferredPronouns string N Patient's preferred gender pronouns, e.g. "he/him", "she/her", "they/them". This is a free text field.
Date of birth birthDate FHIR date Y E.g. 1998-08-14See https://www.hl7.org/fhir/datatypes.html#date
ssn ssn string Y* This is required for the default patient kiosk sign-in method.  If unavailable, please contact Mirah to discuss alternatives
email email string Y** This is required if email assessments are planned to be sent for this patient
phone phone string Y** E.g.  (617) 5551212 See http://www.itu.int/rec/T-REC-E.123-200102-I/e for more complex casesThis is required if text messages are planned to be sent. If possible, send only cell phone numbers
Gender gender M/F/O/U n See https://www.hl7.org/fhir/valueset-administrative-gender.html
Gender Identity fhir gender_identity_fhir string n

Used for more granular detail on how a patient identifies themselves (fhir terminology).

See https://support.mirah.com/article/332-flat-file-integrations-gender-identity-information for accepted values.
Gender Identity gender_identity string n Used for more granular detail on how a patient identifies themselves (free text).
Primary provider providerId string n
Primary Language language BCP-47 language n

This is the primary communication language of the patient. This uses the same format as FIHR (BCP-47): https://www.hl7.org/fhir/valueset-languages.html

BCP-47:

http://tools.ietf.org/html/bcp47
Race race string n As specified by (Use Lvl 1): https://terminology.hl7.org/2.0.0/CodeSystem-v3-Race.html
Ethnicity ethnicity string n As specified by: https://terminology.hl7.org/5.1.0/CodeSystem-v3-Ethnicity.html
Managing Organization managingOrganizationId string n The organization that manages this record. This is useful to show the ‘home’ of a patient when they are not in active treatment.
Timezone timezone Tz db timezone n From https://en.wikipedia.org/wiki/Tz_database
State state string N Either state full name (e.g., “Rhode Island”) or two-letter postcode (e.g., “RI”). 
Zip Code zipCode string N Either 5-digit zip code (e.g., “12201”) or 9-digit zip+4 code (e.g. “12201-7050”).

https://phinvads.cdc.gov/vads/ViewValueSet.action?oid=2.16.840.1.114222.4.11.6065(*) At least one name field is required.

(**) Either email or phone is required in order to send assessments to clients.

Related Articles