Changelog

Notable changes to the Registry API and these docs. The OpenAPI spec is the authoritative contract; this page is the human-readable history.

The API is unversioned today — changes are additive where possible, and any breaking change will be called out here.

2026-09-24 — Partner feed keys minted from the partner record

Partner feed keys now have a dedicated issuing path: BirthTracks staff mint them from your partner record, for a named practice and scope set, and every mint is audited. No change to the wire format or to how a key is sent. See Partner onboarding, step 3.

2026-09-24 — Suspended partners are refused at the door

A partner feed key is now refused with 403 Forbidden while its partner’s contract status is Pending or Suspended, on both ingest and ingestion lookup. Previously only the partner-EHR beta gate was checked, so a suspended partner’s feed kept authenticating. Moving the partner back to Active restores its keys; history is never deleted. Practice-owned keys are unaffected.

2026-09-24 — Native vs partner lane contract

Docs only; no API change. The API reference now has a side-by-side contract for the two ingestion lanes: a practice’s own key vs a partner feed key. It covers how each key is obtained, the beta gate, de-identification, place of birth, and provider attribution.
Provider attribution (attendant, certifier, other providers) is recorded on the partner lane only. Under a practice’s own key, Practitioner resources are accepted but ignored. The docs previously presented attribution as applying to both lanes.
Partner onboarding no longer sends partners to Birth Registry → Integrations for feed keys. Those are native keys. Partner feed keys are issued by BirthTracks.
The Suspended contract status is described as it is enforced: it does not by itself refuse a feed key, and access is withdrawn by revoking the partner’s keys.
Documented how the certifier is read (Composition.attester[].party, falling back to Composition.author).

2026-09-24 — Docs correctness pass

Docs only; no API change. Receipt examples now show the real reference value — the chart number, or record[N] — instead of a resource reference.
The 429 rate-limit response is documented as it is sent: not an OperationOutcome, with Retry-After and X-RateLimit-* headers.
The data dictionary now marks race, ethnicity and place of birth as mapped from FHIR, lists the spine columns it was missing, and documents birth-weight unit handling and patient-birthTime.
Retractions are documented as subject to the staleness guard.

2026-09-23 — Place of birth mapped from the FHIR door

The birth Encounter.location → Location.type is now mapped to the record’s place of birth via the NCHS birth-delivery-occurred value set. On your own (native) key a place of birth is required: a record with no resolvable birthplace is rejected with an OperationOutcome (required, Encounter.location.location.type), with partial-batch semantics unchanged (sibling records still land). EHR-partner feeds are exempt — spine only, place optional. The planned place of birth is read, when present, from the BFDR planned-birthplace Observation. See the place-of-birth codes.

2026-09-18 — Integrations tab, FHIR ingestion log, Admin-only key minting

API keys and developer resources moved to Birth Registry → Integrations (/registry/integrations).
The tab adds a read-only FHIR ingestions log: each recent push’s accepted and rejected counts and status. The per-record outcomes stay behind GET /api/registry/fhir/ingestions/{id}.
Only a practice Admin can mint or revoke a key. A Provider sees the key list with no write controls; Viewer and Scribe seats cannot open the tab.
A practice outside the partner-EHR beta sees a limited-availability notice in place of the tab’s contents.

2026-09-17 — “Scribe key” preset; Physician provider role

An ingest:write-only key is named a Scribe key — it records births and reads nothing — and the key-minting form offers a one-click Scribe key preset that selects exactly that scope.
Partner lane: a Practitioner whose qualification reads physician, obstetric/obstetrician or MD is now recorded with the Physician role (previously other), so it counts in attendant-type benchmarks. Midwife keywords still win, so CNM, MD stays a midwife.

2026-08-24 — Sandbox practices

A practice can be marked a sandbox (practices.is_sandbox) for the beta / design-partner program: it holds synthetic data only and shows a persistent “Test practice — sample data” banner in the app. No real PHI lands in a sandbox practice. There is no separate host — sandbox practices live alongside real ones; see the note in Getting started.

2026-08-24 — Canonical spine: eight new columns

Records — and the fields the FHIR mapper can land — gained eight columns on the canonical course-of-care spine: birth_position, induction_indication, doula_present, delayed_cord_clamping, stat_cesarean, induction and augmentation agents, prenatal_care_site, and a ten-minute Apgar (apgar_ten_minute). See the data dictionary for the full spine.

2026-08-21 — Practice-defined custom fields

Practices can define their own fields — definitions and per-record values — outside the FHIR lane. These are practice-local: they are not part of the FHIR / USCDI mapping and do not appear in a submitted or pulled Bundle.

2026-08-19 — Scribe role and key minting

A write-only Scribe seat can capture births but read nothing, and cannot mint or manage registry API keys. (Since 2026-09-18 only a practice Admin mints or revokes keys — see above.)

2026-08-17 — Operator health endpoint returns 503 on stale results

BirthTracks’ internal, token-gated /health/json endpoint (for BirthTracks operators, not partners) now returns 503 when its stored health-check results are too old to trust, so a stopped scheduler is not read as healthy. It says nothing about any partner feed; for feed health, see Troubleshooting.

2026-08-14 — Source stamping and blank child dates

Provenance source stamping now coalesces to a single source per value, and a blank child birth date is handled at the mapper rather than failing the record.

2026-08-13 — Duplicate detection keys on child birth date

Duplicate-detection keys now include the child’s birthDate, so two births filed under the same chart identifiers but different birth dates are no longer treated as the same record.

2026-08-13 — Encrypted outcomes, failed-receipt shape, stricter date parsing

The ingestion outcome is encrypted at rest.
A terminal status of failed returns a small error object as its receipt body — distinct from the per-record accepted / rejected pair a completed ingestion carries. See Failed ingestions.
An unparseable birthDate or meta.lastUpdated is dropped at the mapper instead of rejecting the whole record.

2026-07-31 — Provider identity attribution

Documented how a pushed Practitioner resource resolves to a provider identity: a non-NPI provider id can be the identity key, a career log records the provider’s history, and merging two identities repoints attribution to the survivor. See Provider attribution.

2026-07-28 — partner integration docs

New Partner onboarding guide — the end-to-end path for an EHR vendor or integrator: contract and BAA, contract status and beta access, practice and feed-key provisioning, first ingest, and the expected sync cadence (daily floor, event-driven push, bulk backfill at onboarding).
New Troubleshooting page — every request-level and per-record OperationOutcome you can receive, what causes it and what to do, plus the feed-health expectations for a live feed.
Documented what the partner lane deliberately does not do — no filing lane by default, and nothing identified is stored (masking runs before persistence, as an allow-list).
Documented Practitioner and Encounter in the API reference and the data dictionary — including non-NPI provider ids as the identity key and the ATND attendant rule.

2026-07-28

Amendments. Re-sending a Bundle under a chart number already on file now amends that record — version advances, previous values are kept as history — instead of being rejected as a duplicate. Accepted entries for a correction carry "amended": true and the new version.
Retractions. A Composition with status: entered-in-error, or an entry with "request": { "method": "DELETE" }, voids the record it names; a later re-send revives it as a further amendment version.
Two guards apply to amendments only: a push older than the stored version is rejected as a conflict (“Stale update ignored”), and a correction that would duplicate a different record is rejected rather than merged.

See Amendments and retractions.

2026-06-08

The current API surface:

POST /api/registry/fhir/Bundle — submit a FHIR R4 BFDR Bundle (one course of care, or many in batch mode) for asynchronous ingestion.
GET /api/registry/fhir/ingestions/{id} — poll an ingestion for its per-record accepted / rejected outcomes.
Per-practice API keys (rgk_) carrying ingest:write / ingest:read scopes.
Accept-and-flag duplicate detection (suspected_duplicate) and per-practice chart-number uniqueness.
A consent decision captured per course of care from an optional FHIR Consent.
A 120 request/minute rate limit per API key, shared across both endpoints.