Partner onboarding

This page is the self-serve path for a partner: an EHR vendor or integrator that pushes births into the registry on behalf of the practices it serves. It covers everything from first contact to a steady daily feed.

If you are a single practice pushing your own births under your own key, you want Getting started instead — the wire format is identical, but the onboarding steps and the storage rules below are specific to the partner lane.

What the integration does

Your EHR stays the system of record. You push each course of care as a FHIR R4 BFDR Bundle and BirthTracks turns it into registry statistics and outcome benchmarking for the practice — so a provider enters a birth once, in your product, and the registry side falls out.

What it deliberately does not do

Two limits are worth stating plainly, because both are load-bearing for the compliance conversation.

No filing lane by default. Vendors file vital records through their own EHR, so the partner lane does not build a filing spine: the identifiers a filing artifact would need are never written for partner-submitted records. Filing through BirthTracks is not part of this integration and is not something a partner feed can turn on for itself — it would be a separate, explicitly granted capability, never a retroactive upgrade of records you have already sent.

Nothing identified is stored. Your Bundles arrive identified — that transfer is PHI in transit, and BirthTracks acts as your subcontractor business associate — but identified data does not land. A masking step runs at the door, before anything is persisted, and it is an allow-list: only the fields named below can ever be written on the partner lane, so a field the mapper learns to read later cannot silently start being stored.

Entity	What may be stored from a partner Bundle
Course of care	Lifecycle status, input source, your chart number (`external_record_id`, stored encrypted with a blind index), the declared BFDR IG version, enrolment timestamp.
Mother	Maternal age, 3-digit residence ZIP prefix, race, ethnicity. No name, no date of birth, no address, no payer account.
Child	Birth order, sex, birth date/time, birth weight, gestational age, Apgar at 1 and 5 minutes.

Two values are coarsened further at the door rather than only on the way out: a maternal age above 89 is dropped (the HIPAA Safe Harbor aggregation ceiling), and a restricted 3-digit ZIP prefix is suppressed. The result is that the registry never holds a partner-submitted value that the public projection would have had to mask anyway.

Provider attribution is retained, because a provider is not a patient: the Practitioner resources you send are stored so attendant-level benchmarking works. See Provider attribution below.

Step 1 — Contract and BAA

Onboarding starts as a business conversation, not an API call. Before a feed can be provisioned we need:

a partner agreement covering the practices you will push for, and
an executed BAA — you are the covered entity’s business associate and BirthTracks is your subcontractor business associate for the data you send.

Contact your BirthTracks representative to start this. Your partner record is created in the Pending state while the contract and BAA are in flight.

Step 2 — Activation and beta access

Two independent switches gate a live feed, and both must be on:

Gate	Meaning
Contract status	`Pending` → `Active` once the agreement and BAA are in place. Only an `Active` partner is provisioned a live feed; `Suspended` withdraws access without deleting your history, and only active feeds are monitored for feed health.
Beta access	The partner-EHR lane ships behind a beta gate, and this is the one enforced on every request. Until your organisation is let into the beta, a partner feed key authenticates but is refused with `403` — “This partner feed is not enabled for the partner-EHR beta.” Being `Active` is not enough on its own.

Both are set by BirthTracks; there is no self-service path while the lane is in limited availability. Your representative confirms when both are on.

Step 3 — Practices and feed keys

Once you are active and in the beta:

Practices are provisioned — one BirthTracks practice per practice you push for. Records are scoped to the practice the submitting key belongs to, so a practice only ever sees its own births.
A feed API key is minted per practice, in Registry → Settings (/registry/settings). A key is displayed once at mint time, prefixed rgk_; only a hash is stored, so it can never be recovered — treat it like a password and store it in your secret manager. Keys do not expire; they stay valid until revoked.
Confirm the key’s scopes. A feed needs ingest:write to submit and ingest:read to poll for results. See Authentication.

Send the key as a bearer token on every request:

Authorization: Bearer rgk_your_token_here

One key per practice keeps revocation granular: rotating or revoking one practice’s feed never interrupts the others.

Step 4 — First ingest

Work through Getting started with your first practice’s key. The short version:

POST a Bundle to /api/registry/fhir/Bundle with Content-Type: application/fhir+json.
Take the status URL from the Content-Location header on the 202 Accepted.
Poll that URL until status is completed or failed, and read the per-record accepted / rejected detail.

A course of care is accepted when it carries exactly one mother Patient and at least one child Patient, resolved from each resource’s BFDR meta.profile. Add the newborn Observations, and the Practitioner and Encounter resources below, to get the full registry value out of the feed.

Before you go live, confirm your integration handles all four of these, since each has a distinct correct response:

a rejected record inside an otherwise good batch (land the rest, queue the one for repair),
a conflict on a stale update (your push was older than what we hold — don’t retry it unchanged),
a suspected_duplicate flag on an accepted record (informational; the record landed),
a retraction of a record you previously sent.

The Troubleshooting page lists every outcome you can receive and what to do about each.

Provider attribution

Include a Practitioner for each provider involved in the course of care. Two details matter for a partner feed:

Your own id is the key, not the NPI. The provider’s stable identity is read from the first non-NPI identifier.value you send, falling back to the resource id. The NPI, when present, is kept as a discovery signal only — it is deliberately never the key, because doulas and CPMs frequently have none. A Practitioner with no stable id at all is skipped rather than stored under a synthesized key that your next push would not match, so send a stable id and keep it stable across pushes.
Role is coarse and keyword-matched from the practitioner’s qualification text or display — midwife (including CNM, CPM, LM), doula, nurse (or RN), assistant, and otherwise “other”. Anything unrecognised lands as “other”, which is excluded from attendant-type benchmarks, so an unmatched credential can never over-count attendants.

The attending provider is the one an Encounter marks with the HL7 v3 ParticipationType ATND. Nothing else promotes a practitioner to attendant — a doula listed as a participant is recorded as present, not as attending.

Encounter resources also carry transfers of care; see the data dictionary for how a transfer Encounter maps.

Step 5 — Sync cadence

Cadence is yours to choose, within one floor and two recommendations:

Daily is the contract floor. Every practice’s feed should deliver at least once a day. Stats and benchmarks are only as current as the last successful push.
Event-driven push is encouraged. Sending a course of care when it is completed or amended in your EHR keeps the registry close to real time and spreads load, rather than concentrating it in a nightly window.
Backfill in bulk at onboarding. Send the practice’s history once when the feed is provisioned, using batch Bundles (a Bundle whose entries are themselves Bundles, one course of care each). Do this before switching on the ongoing feed so the practice’s benchmarks are meaningful from day one.

Always send your source system’s own last-modified stamp (meta.lastUpdated or the Bundle timestamp). It is what lets out-of-order delivery and retries be rejected as stale rather than rolling a record backwards.

A feed that goes quiet past the silence window is flagged to BirthTracks automatically — including a feed that was provisioned but never delivered at all. See feed health for what we watch and what you should watch.

Ongoing operation

Concern	Where it is covered
Corrections and withdrawals	Amendments and retractions — re-send under the same chart number to correct; `entered-in-error` or a `DELETE` entry to retract.
Safe retries	`Idempotency-Key` — a retry of the same POST replays the original receipt instead of re-ingesting.
Same birth arriving twice	Duplicate handling — accepted and flagged for review, never silently merged or dropped.
Consent	Consent — recorded per course of care, not enforced at intake.
Rejections and feed health	Troubleshooting.
Field-level mapping	Data dictionary.