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 — a provider's medical record 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. Usually your member number; if you reissue member numbers, use a stable internal person id and send the member number as an additional identifier	`MBR0000012`
`patient_identifier_system`	Yes	URI of the identifier system; a URL you control or an OID	`http://example.org/member-ids`
`patient_identifier_type`	Yes, with `MB`, if you deliver claims	`MB` member number, `MR` medical record, `MC` Medicare, `MA` Medicaid v2-0203	`MB`
`patient_identifier_use`	Recommended	`usual`, `official`, `temp`, `secondary`, `old` identifier-use	`official`
`patient_identifier_assigner_org_identifier`	Recommended	key from `organizations`	`99999`
`is_deleted`	If retracting	`true` retracts this row	`true`

If you deliver claims, one identifier on the row must be typed MB. Every ExplanationOfBenefit references the member through the C4BB Patient profile, which requires a member number identifier that US Core does not. Usually that is this column set to MB; if your key is something else, carry the member number in the additional identifier slot 2 with identifier_2_type = MB. Payerbox marks the Patient as C4BB Patient only when it finds one in either place. A USCDI-only delivery may key members by any stable identifier.

Additional identifiers

Column	Required	Format / values	Example
`identifier_<n>_value`	Yes	the identifier as issued	`MRN-4471903`
`identifier_<n>_system`	Yes	URI of the identifier system; a URL you control or an OID	`http://example.org/mrns`
`identifier_<n>_type`	Recommended	v2-0203 code	`MR`
`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_identifier`	Recommended	key from `organizations`	`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; required for any member with a prior authorization	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	`MBR0000012`
`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	`MBR0000012`
`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.