Data dictionary

Limited-availability beta

Partner EHR / registry-API integration is currently in a limited-availability beta — enabled for participating practices while the lane is validated. Contact your BirthTracks representative to request access.

A submitted Bundle maps into BirthTracks’ canonical spine — a small set of entities shared by every input path (FHIR push, CSV import, structured web form). This is the common shape that downstream filing and benchmarking read from.

A course of care is one Submission with one Mother, one or more Children, up to three clinical Encounter records (the antepartum maternity encounter, the labour-and-delivery birth encounter, and zero or more postpartum postpartum encounters), and zero or more Transfers of care.

Note

The FHIR ingestion endpoint lands the fields marked mapped from FHIR below — the core maternal demographics (including race and ethnicity), the newborn measures, and the actual and planned place of birth — plus transfers of care, the consent decision and, on a partner feed, provider attribution (see Two lanes). The remaining clinical fields are part of the same canonical model and are captured via the CSV importer or the structured web form (the long-tail path). USCDI/FHIR covers only a fraction of birth-record fields by design.

Submission (course of care)

Field	Type	Notes
uuid	string (uuid)	Stable id for the course of care.
status	string	Lifecycle: draft · enrolled · complete · locked · amended · voided. A FHIR push enrolls the record; a locked or voided record is corrected only by amendment, never edited in place.
source	string	Input path — manual, csv, fhir_push, or ehr_pull (an EHR-prefilled partial from the pull lane).
external_record_id	string	Your record id, from the Bundle identifier.value. Unique per practice.
actual_place	string	Actual place of birth — hospital, birth_center, home, clinic, en_route, other. Mapped from FHIR from the birth Encounter.location → Location.type (place-of-birth codes); required on a practice’s own key.
intended_place	string	Planned place of birth, same values. Mapped from FHIR when the BFDR planned-birthplace Observation is present; optional.
intention_to_treat_flag	boolean	Intention-to-treat marker for benchmarking.
attendant_type	string	Type of attendant for the course.
bfdr_ig_version	string	BFDR IG version declared on the mother’s meta.profile.
enrolled_at / completed_at	datetime	Set as the record progresses.
locked_at / voided_at	datetime	When the record was locked, and when it was voided (a retraction sets it).
version	integer	Starts at 1; advances on each amendment. Returned on the receipt as version.
source_updated_at	datetime	Your meta.lastUpdated (or timestamp), kept for the staleness guard.
global_dedup_key	string	Keyed hash used to detect the same birth arriving from another source. Never the clear-text inputs.
attendant_identity_id	integer	The attending provider identity. Set from a partner feed’s ATND participant, from the CSV importer’s provider mapping, or from the attendant on a birth recorded in the app. A FHIR push under a practice’s own key does not set it.
certifier_identity_id	integer	The certifying provider identity. Set only from a partner feed.

Mother

Field	Type	Source	Notes
maternal_age	integer	mapped from FHIR	Derived from the mother’s birthDate and the newborn date.
residence_zip3	string(3)	mapped from FHIR	First 3 digits of the mother’s address.postalCode (Safe Harbor).
race	json	mapped from FHIR	The ombCategory display values of the US Core race extension (one or more).
ethnicity	string	mapped from FHIR	The first ombCategory display of the US Core ethnicity extension.
race_detailed / racial_ethnic_self_identity	json / text	long-tail	Detailed (REALD) race and free-text self-identity.
education	string	long-tail
marital_status	string	long-tail
primary_payer	string	long-tail
parity / gravidity	integer	long-tail
prepregnancy_bmi	decimal	long-tail
prior_cesarean / prior_cesarean_count	boolean / integer	long-tail
chronic_hypertension	boolean	long-tail
pre_existing_diabetes	boolean	long-tail
tolac_attempted	boolean	long-tail	Trial of labor after cesarean.
perineal_status	string	long-tail
postpartum_hemorrhage	boolean	long-tail
estimated_blood_loss_band	string	long-tail
maternal_icu_admission	boolean	long-tail
maternal_mortality	boolean	long-tail
breastfeeding_at_discharge / breastfeeding_at_six_weeks	string	long-tail
infection_*	boolean	long-tail	The infection panel: gonorrhea, syphilis, chlamydia, hepatitis_b, hepatitis_c, hsv, hiv, covid_19.
occupation / industry	string	long-tail
wic	boolean	long-tail	WIC food received during this pregnancy.
parentage_acknowledged	boolean	long-tail	Acknowledgment of parentage signed.
delivery_weight_lb	integer	long-tail	Mother’s weight at delivery (pounds).

Encounters

The clinical spine is three encounter records, not one — an antepartum maternity encounter, the labour-and-delivery birth encounter, and zero or more postpartum encounters for follow-up visits. The fields below are long-tail — the FHIR push does not map them (it reads the birth Encounter only for the place of birth, transfers and, on a partner feed, the attendant) — so they are captured through the CSV importer or the structured web form.

Maternity encounter (antepartum)

One per course of care.

Field	Type	Notes
ga_at_care_entry_weeks	integer	Gestational age (weeks) at entry to care.
prenatal_visit_count	integer	Number of prenatal visits.
prenatal_care_adequacy	string	Adequacy-of-care index band.
gbs_status	string	Group B strep status.
smoking_before / smoking_during	string	Smoking before and during pregnancy.
prenatal_care_site	text	Where prenatal care was received. (Added 2026-08.)
alcohol_use_during_pregnancy	boolean
cigarettes_per_day_before / _trimester1 / _trimester2 / _trimester3	integer	Average cigarettes per day before and in each trimester.

Birth encounter (labour & delivery)

One per course of care; optionally linked to a specific child.

Field	Type	Notes
labor_onset	string	Spontaneous, induced, etc.
presentation	string	Fetal presentation at birth.
induction / augmentation	boolean
induction_indication	string	Clinical indication for induction. (Added 2026-08.)
induction_agents / augmentation_agents	json	The agents used to induce / augment labour. (Added 2026-08.)
rom_method / rom_at	string / datetime	Rupture of membranes method and time.
fetal_monitoring	string
pain_management	string
birth_position	string	Maternal position at birth. (Added 2026-08.)
doula_present	boolean	Whether a doula attended. (Added 2026-08.)
delayed_cord_clamping	boolean	Whether cord clamping was delayed. (Added 2026-08.)
mode_of_birth	string
cesarean_type	string
stat_cesarean	boolean	Whether a caesarean was a STAT (emergency) caesarean. (Added 2026-08.)
shoulder_dystocia	boolean

Postpartum encounters (follow-up visits)

Zero or more per course of care — legacy encounters parity (EPIC 49). Each is tied to a patient and, when on file, to the birth it follows (which is what makes weeks_since_birth a calculated value).

Field	Type	Notes
encounter_type	string	Kind of visit.
encounter_date	date
start_time / end_time	time
duration_minutes	integer
weeks_since_birth	integer	Calculated from the linked birth; a manual value is the fallback.
encounter_setting	string	Where the visit happened.
mileage	decimal	Travel mileage for a home visit.
bp_systolic / bp_diastolic / heart_rate / temperature	integer / integer / integer / decimal	Vitals — kept plaintext so the stats lane can aggregate them.
Care checklist	boolean (per topic)	What care was covered at the visit (infant–mother bonding, feeding, mother care, family, referrals, other).
Need assessment	boolean + text (per topic)	Whether a need was identified, with free-text detail.
encounter_notes	text	Free-text visit notes (encrypted at rest).

Child

Field	Type	Source	Notes
sequence	integer	mapped from FHIR	Birth order; from multipleBirthInteger when present.
sex	string	mapped from FHIR	From the child Patient.gender.
birth_datetime	datetime	mapped from FHIR	The child Patient’s patient-birthTime extension (valueDateTime) when present, otherwise Patient.birthDate.
birth_weight_g	integer	mapped from FHIR	LOINC 8339-4 Observation. Read in grams; a valueQuantity whose code (or unit) is kg is converted, and a value with no unit is taken as grams. Rounded to a whole gram.
gestational_age_weeks	integer	mapped from FHIR	LOINC 11884-4 Observation.
apgar_one_minute	integer	mapped from FHIR	LOINC 9272-6 Observation.
apgar_five_minute	integer	mapped from FHIR	LOINC 9274-2 Observation.
apgar_ten_minute	integer	long-tail	Apgar score at 10 minutes, recorded when resuscitation continues past 5 minutes. Not read from a Bundle — there is no LOINC mapping for it. (Added 2026-08.)
gestational_age_days	integer	long-tail
resuscitation / assisted_ventilation	boolean	long-tail
congenital_anomaly	string	long-tail
nicu_admission	boolean	long-tail
neonatal_death / neonatal_death_timing / neonatal_death_cause	boolean / string	long-tail
infant_living_at_report	boolean	long-tail	Infant living at time of report.
newborn_hearing_screening	string	long-tail	Hearing-screening result.
hepatitis_b_vaccine / hepatitis_b_immune_globulin	boolean	long-tail

Transfer of care

Zero or more per course of care — the community-birth differentiator. Captured via the structured web form (0..n), the CSV importer (one per row, gated on transfer_type), and the FHIR push (see below). In the CSV template the columns are prefixed transfer_.

Field	Type	Provenance	Notes
transfer_type	string	long-tail	One of antepartum, intrapartum, postpartum_maternal, neonatal. Marks a transfer present.
reason_code	string	long-tail	Coded reason (SNOMED). CSV column transfer_reason_code.
reason_text	string	long-tail	Free-text reason. CSV column transfer_reason_text.
destination	string	long-tail	Where care transferred to. CSV column transfer_destination.
emergency	boolean	long-tail	Whether the transfer was an emergency. CSV column transfer_emergency.
occurred_at	datetime	long-tail	When the transfer occurred. CSV column transfer_occurred_at.

FHIR representation

A transfer of care has no dedicated BFDR profile, so the push lane reads it from a FHIR R4 Encounter in the course-of-care Bundle. The transfer type is the gate — an Encounter that names no recognized transfer type (e.g. the birth Encounter) records no transfer, mirroring the CSV/web “transfer_type marks a transfer present” rule. Map each transfer Encounter as:

Canonical field	FHIR source
transfer_type	Encounter.type[].coding[].code ∈ {antepartum, intrapartum, postpartum_maternal, neonatal} (recommended system https://birthtracks.twosportday.com/fhir/CodeSystem/transfer-type; matched on code, case-insensitive, regardless of system)
reason_code	Encounter.reasonCode[0].coding[0].code (SNOMED)
reason_text	Encounter.reasonCode[0].text, falling back to the coding display
destination	Encounter.hospitalization.destination.display
emergency	true iff Encounter.priority.coding[].code ∈ {EMER, STAT, ASAP} (HL7 ActPriority); otherwise false
occurred_at	Encounter.period.start

Provider attribution

On the partner lane (a push under a partner feed key), providers named in a course of care are stored as their own canonical entity, so attendant-level benchmarking works. Provider attribution is not patient PHI, so unlike the mother and child, a provider’s name and credentials are retained. On a practice’s own (native) key, Practitioner resources are accepted but not stored, and no attendant or certifier is recorded. See Two lanes.

Canonical field	FHIR source
external_provider_id	The first non-NPI Practitioner.identifier.value, falling back to Practitioner.id. The stable identity key — a Practitioner without one is skipped.
npi	The identifier whose system names US-NPI. A discovery signal only; deliberately never the key, because doulas and CPMs frequently have none.
role	Keyword-matched from the practitioner’s qualification text/display: midwife (also CNM/CPM/LM), physician (also obstetric/obstetrician, MD), doula, nurse (also RN), assistant, else other. Midwife is matched first, so CNM, MD is a midwife.
display_name	Practitioner.name[0].text, falling back to the assembled human name.
credentials	The practitioner’s qualification text/display.

The attending provider is the participant an Encounter marks with the HL7 v3 ParticipationType ATND; nothing else promotes a practitioner to attendant. The certifier is the practitioner referenced by Composition.attester[].party, falling back to Composition.author.

Partner lane

On the partner lane (an EHR vendor pushing for its practices) the mother and child are reduced to a coarse, de-identified spine before anything is persisted, while provider attribution is retained as above. Attribution is recorded on this lane only. See Partner onboarding.

Consent

One or more consent records per course of care, each a scope, whether consent was granted, its source, and when it was recorded. A FHIR push records one from the Bundle’s first Consent resource — see Consent.

Practice-defined custom fields

Beyond the canonical spine, a practice can define its own fields (EPIC 58). These live outside the FHIR lane — a Bundle never carries them, and they are never mapped from a push; they are set on the structured web form and read back by the practice that owns them. Two tables model them: definitions (the schema a practice declares) and values (what a record holds for a definition).

Custom field definition

Practice-scoped. A field is declared once per section and reused across records.

Field	Type	Notes
label	string	The field’s display label. Unique per (practice, section, label).
type	string	The input type (e.g. text, number, select).
section	string	Which record section the field attaches to.
options	json	Choices for a select-type field; null otherwise.
position	integer	Ordering within its section.
active	boolean	Whether the field is currently shown.
promoted_at / promoted_to	datetime / string	Set when a custom field is promoted into the canonical model (ADR 0006 reversal) — promoted_to names the canonical field it became.

Custom field value

Practice-scoped and polymorphic — a value attaches to whatever record type its definition’s section targets (record_type + record_id), so one table holds the values for every custom field across the practice.

Field	Type	Notes
custom_field_definition_id	integer	The definition this value answers.
record_type / record_id	string / integer	The record the value belongs to (polymorphic).
value	text	The stored value, encrypted at rest. Unique per (definition, record).

LOINC codes used on newborn Observations

LOINC	Meaning
8339-4	Birth weight (grams)
11884-4	Gestational age (weeks)
9272-6	Apgar score at 1 minute
9274-2	Apgar score at 5 minutes