Patient Demographics/Information

Datasets

US Core 6.1.0 maps each USCDI data element onto a FHIR element.

Dataset	US Core 6.1.0 target profile(s)
`patients`	US Core Patient
`related_persons`	US Core RelatedPerson
`social_history`	US Core Observation Occupation, US Core Smoking Status, US Core Observation Pregnancy Status, US Core Observation Pregnancy Intent

patients

One row per member, and all the tables in this section describe that same single row: each table is one group of its columns, split up only for readability. Send every column you maintain from every group together in the one patients file.

Column group	What it carries
Identity	the primary key your other rows reference, and how it is issued
Additional identifiers	other identifiers the member is known by — member number, Medicare or Medicaid ID
Name	current and previous names
Demographics	gender, sex, birth date, race, ethnicity, tribal affiliation, language
Address and contact	current and previous address, phone, email

Identity

Column	Required	Format / values	Example
`patient_identifier`	Yes	your most stable patient key; must not change for a person or be reused for another	`MRN-4471903`
`patient_identifier_system`	Yes	URI of the identifier system; a URL you control or an OID	`http://example.org/mrns`
`patient_identifier_type`	Recommended	`MR` medical record, `MB` member number, `MC` Medicare, `MA` Medicaid v2-0203	`MR`
`patient_identifier_use`	Recommended	`usual`, `official`, `temp`, `secondary`, `old` identifier-use	`official`
`patient_identifier_assigner_org_npi`	Recommended	10 digits, Luhn-valid over the `80840` prefix	`9999999979`
`is_deleted`	If retracting	`true` retracts this row	`true`

Additional identifiers

Column	Required	Format / values	Example
`identifier_<n>_value`	Yes	the identifier as issued	`HSX9930012`
`identifier_<n>_system`	Yes	URI of the identifier system; a URL you control or an OID	`http://example.org/member-ids`
`identifier_<n>_type`	Recommended	v2-0203 code	`MB`
`identifier_<n>_use`	Recommended	`usual`, `official`, `temp`, `secondary`, `old` identifier-use	`official`
`identifier_<n>_period_start`	Recommended	date	`2024-01-01`
`identifier_<n>_period_end`	Recommended	date	`2025-12-31`
`identifier_<n>_assigner_org_npi`	Recommended	10 digits, Luhn-valid over the `80840` prefix	`9999999979`

If you use a slot, fill both value and system. A value without a system is rejected. A slot left blank is ignored.
<n> is a slot number starting at 2, because the Identity columns are slot 1: the first extra identifier goes in identifier_2_value + identifier_2_system, the next in identifier_3_…, and so on. Keep the numbers consecutive — three extra identifiers use slots 2, 3, and 4; skipping a number (2 and 4 with no 3) is invalid.

Name

Column	Required	Format / values	Example
`last_name`	Yes	text	`Doe`
`first_name`	Yes	text	`Jane`
`middle_name`	Recommended	text	`L`
`name_suffix`	Recommended	Jr. / Sr. / III
`previous_name`	Recommended	`family, given`	`Smith, Jane`

Demographics

Column	Required	Format / values	Example
`gender`	Yes	`male`, `female`, `other`, `unknown` AdministrativeGender	`female`
`sex`	Recommended	`248152002` Female, `248153007` Male US Core Sex	`248152002`
`birth_date`	Recommended	YYYY-MM-DD	`1957-03-11`
`deceased_date`	If applicable	datetime
`race_omb_code`	Recommended	`2106-3` White, `2054-5` Black or African American, `2028-9` Asian, `1002-5` American Indian or Alaska Native, `2076-8` Native Hawaiian or Other Pacific Islander, `UNK` unknown, `ASKU` asked but declined; `;`-separated OMB race categories	`2106-3`
`race_detailed_code`	If available	CDC race code(s), `;`-separated detailed race	`2108-9`
`ethnicity_omb_code`	Recommended	`2135-2` Hispanic or Latino, `2186-5` Not Hispanic or Latino, `UNK` unknown, `ASKU` asked but declined OMB ethnicity categories	`2186-5`
`ethnicity_detailed_code`	If available	CDC ethnicity code(s) detailed ethnicity
`tribal_affiliation_code`	Recommended	tribal-entity code TribalEntityUS
`preferred_language`	Recommended	BCP 47 simple-language	`en`

Address and contact

Column	Required	Format / values	Example
`address_line1`	Recommended	text	`123 Main St`
`address_line2`	No	text	`Apt 3`
`city`	Recommended	text	`Anytown`
`state`	Recommended	2-letter USPS USPS states	`NY`
`zip`	Recommended	5 or 9 digits, as a string	`12345`
`phone`	Recommended	10 digits	`5551234567`
`phone_type`	Recommended	`home`, `work`, `mobile`, `temp`, `old` ContactPointUse	`mobile`
`email`	Recommended	email address
`previous_address`	Recommended	`line, city, state, zip`	`45 Oak St, Anytown, NY, 12345`
`previous_address_end`	If available	date	`2024-08-31`

Contacts and non-clinician care-team members, such as a daughter, spouse, or guardian. One row per person per patient.

Column	Required	Format / values	Example
`record_id`	Yes	your stable key for this person; `care_team` references it	`RP-3310`
`patient_identifier`	Yes	patient key	`MRN-4471903`
`relationship_code`	Recommended	`DAU` daughter, `SPS` spouse, `CHILD` child v3-RoleCode, v2-0131	`DAU`
`last_name`	Recommended	text	`Doe`
`first_name`	Recommended	text	`Mary`
`phone`	If available	10 digits	`5559876543`
`address_line1`	If available	text	`45 Oak St`
`city`	If available	text	`Anytown`
`state`	If available	2-letter USPS USPS states	`NY`
`zip`	If available	5 digits, as a string	`12345`
`active`	Yes	`true` / `false`; `false` retires a contact without deleting them	`true`
`is_deleted`	If retracting	`true` retracts this row	`true`

Column	Required	Format / values	Example
`record_id`	Yes	your stable key for this row	`SH-0001`
`patient_identifier`	Yes	patient key	`MRN-4471903`
`observation_type`	Yes	`occupation` for the demographics rows; `smoking-status`, `pregnancy-status`, `pregnancy-intent` are Health Status/Assessments	`occupation`
`status`	Yes	`registered`, `preliminary`, `final`, `amended`, `corrected`, `cancelled`, `entered-in-error`, `unknown` observation-status	`final`
`value_code`	Yes	the value for this `observation_type`, with `value_system`	`29-1141.00.005678`, `266919005`
`value_system`	Yes for `occupation`; blank means SNOMED CT for the others	`http://terminology.hl7.org/CodeSystem/PHOccupationalDataForHealthODH` for `occupation`, SNOMED CT for `smoking-status`, `pregnancy-status` and `pregnancy-intent`	`http://terminology.hl7.org/CodeSystem/PHOccupationalDataForHealthODH`
`industry_code`	occupation only	Occupational Data for Health industry code Industry NAICS Detail	`622110.004411`
`effective_datetime`	Yes, except on `occupation` rows	datetime	`2026-04-18`
`is_deleted`	If retracting	`true` retracts this row	`true`

occupation is the one row shape with no default value_system: send the ODH system URI explicitly. A plain ONET-SOC code (29-1141.00) is not the same code space as an ODH composite code (29-1141.00.005678) — sending the bare ONET-SOC value or leaving value_system blank is rejected rather than guessed at.

These resources are served by Patient Access, Provider Access, and Payer-to-Payer.