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 core demographics and newborn measures listed below as mapped from FHIR. 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.
intended_place / actual_place	string	Planned vs. actual place of birth.
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.

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	long-tail
ethnicity	string	long-tail
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

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. All of it is long-tail: the FHIR push lands only the core demographics and newborn measures (above), so these fields 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.)

Birth encounter (labour & delivery)

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

Field	Type	Notes
labor_onset	string	Spontaneous, induced, etc.
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	From the child Patient.birthDate/time.
birth_weight_g	integer	mapped from FHIR	LOINC 8339-4 Observation (grams).
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. (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

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

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.

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), doula, nurse (also RN), assistant, else other.
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.

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. See Partner onboarding.

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