Getting started

This walkthrough takes you from zero to a mapped record: get a key, submit one course of care, and poll for the result. This is the path an EHR or integrator uses to feed births into BirthTracks so a provider enters each one once, rather than re-keying it here.

Sandbox practices

There is no separate sandbox host. For the beta / design-partner program a practice can be provisioned as a sandbox: it is seeded with synthetic data, holds no real PHI, and shows a “Test practice — sample data” banner in the app. It is where an invited practice exercises the integration before its real cutover. Contact your BirthTracks representative to have a sandbox practice set up — there is no self-service path.

1. Get an API key

Registry API keys are minted per practice and shown once at mint time. Sign in and open Birth Registry → Integrations (/registry/integrations) to mint a key.

Two things gate minting from that page:

Your practice must be in the partner-EHR beta. Until then the tab shows “Integrations are in a limited-availability beta” instead of the API keys section. Contact your BirthTracks representative to request access; there is no self-service or command-line path to a key while the lane is in limited availability.
Only a practice Admin can mint or revoke a key. A Provider can open the tab and see the existing keys and the FHIR ingestion log, but is shown no mint or revoke controls. Read-only Viewer and write-only Scribe seats cannot open the Integrations tab at all (403).

You get a raw token prefixed rgk_. Store it like a password — only its hash is kept, so it can’t be recovered later. Send it on every request:

Authorization: Bearer rgk_your_token_here

2. Submit a course of care

The body is a FHIR R4 BFDR document Bundle: one mother Patient, one child Patient, and the newborn Observations. The example below uses placeholder values.

curl

curl -X POST https://birthtracks.twosportday.com/api/registry/fhir/Bundle \
  -H "Authorization: Bearer rgk_your_token_here" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Bundle",
    "type": "document",
    "identifier": { "value": "CHART-001" },
    "entry": [
      { "fullUrl": "urn:uuid:mother-1", "resource": {
        "resourceType": "Patient", "id": "mother-1",
        "meta": { "profile": ["http://hl7.org/fhir/us/bfdr/StructureDefinition/Patient-mother-vr|2.0.0"] },
        "name": [{ "family": "Doe", "given": ["Jane"] }],
        "birthDate": "1990-04-01",
        "address": [{ "postalCode": "98101" }]
      }},
      { "fullUrl": "urn:uuid:child-1", "resource": {
        "resourceType": "Patient", "id": "child-1",
        "meta": { "profile": ["http://hl7.org/fhir/us/bfdr/StructureDefinition/Patient-child-vr|2.0.0"] },
        "gender": "female",
        "birthDate": "2026-05-01"
      }},
      { "resource": {
        "resourceType": "Observation",
        "subject": { "reference": "Patient/child-1" },
        "code": { "coding": [{ "system": "http://loinc.org", "code": "8339-4" }] },
        "valueQuantity": { "value": 3400, "unit": "g", "code": "g" }
      }},
      { "resource": {
        "resourceType": "Observation",
        "subject": { "reference": "Patient/child-1" },
        "code": { "coding": [{ "system": "http://loinc.org", "code": "9274-2" }] },
        "valueQuantity": { "value": 9, "unit": "{score}" }
      }},
      { "fullUrl": "urn:uuid:birth-encounter-1", "resource": {
        "resourceType": "Encounter", "id": "birth-encounter-1",
        "location": [{ "location": { "reference": "Location/birth-location-1" } }]
      }},
      { "fullUrl": "urn:uuid:birth-location-1", "resource": {
        "resourceType": "Location", "id": "birth-location-1",
        "type": [{ "coding": [{ "system": "http://snomed.info/sct", "code": "22232009", "display": "Hospital" }] }]
      }}
    ]
  }'

You’ll get a 202 Accepted with a FHIR OperationOutcome and a Content-Location header pointing at the status URL for this ingestion.

The birth Encounter names a Location whose Location.type is the NCHS place-of-birth code — the place of birth is required on your own (native) key, and a record without a resolvable one is rejected with an OperationOutcome.

Python

import requests

BASE = "https://birthtracks.twosportday.com"
TOKEN = "rgk_your_token_here"

bundle = {
    "resourceType": "Bundle",
    "type": "document",
    "identifier": {"value": "CHART-001"},
    "entry": [
        {"fullUrl": "urn:uuid:mother-1", "resource": {
            "resourceType": "Patient", "id": "mother-1",
            "meta": {"profile": ["http://hl7.org/fhir/us/bfdr/StructureDefinition/Patient-mother-vr|2.0.0"]},
            "name": [{"family": "Doe", "given": ["Jane"]}],
            "birthDate": "1990-04-01",
            "address": [{"postalCode": "98101"}],
        }},
        {"fullUrl": "urn:uuid:child-1", "resource": {
            "resourceType": "Patient", "id": "child-1",
            "meta": {"profile": ["http://hl7.org/fhir/us/bfdr/StructureDefinition/Patient-child-vr|2.0.0"]},
            "gender": "female",
            "birthDate": "2026-05-01",
        }},
        {"resource": {
            "resourceType": "Observation",
            "subject": {"reference": "Patient/child-1"},
            "code": {"coding": [{"system": "http://loinc.org", "code": "8339-4"}]},
            "valueQuantity": {"value": 3400, "unit": "g", "code": "g"},
        }},
        {"resource": {
            "resourceType": "Observation",
            "subject": {"reference": "Patient/child-1"},
            "code": {"coding": [{"system": "http://loinc.org", "code": "9274-2"}]},
            "valueQuantity": {"value": 9, "unit": "{score}"},
        }},
        {"fullUrl": "urn:uuid:birth-encounter-1", "resource": {
            "resourceType": "Encounter", "id": "birth-encounter-1",
            "location": [{"location": {"reference": "Location/birth-location-1"}}],
        }},
        {"fullUrl": "urn:uuid:birth-location-1", "resource": {
            "resourceType": "Location", "id": "birth-location-1",
            "type": [{"coding": [{"system": "http://snomed.info/sct", "code": "22232009", "display": "Hospital"}]}],
        }},
    ],
}

resp = requests.post(
    f"{BASE}/api/registry/fhir/Bundle",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/fhir+json",
    },
    json=bundle,
)
resp.raise_for_status()
status_url = resp.headers["Content-Location"]
print("Accepted:", status_url)

JavaScript

const BASE = "https://birthtracks.twosportday.com";
const TOKEN = "rgk_your_token_here";

const bundle = {
  resourceType: "Bundle",
  type: "document",
  identifier: { value: "CHART-001" },
  entry: [
    { fullUrl: "urn:uuid:mother-1", resource: {
      resourceType: "Patient", id: "mother-1",
      meta: { profile: ["http://hl7.org/fhir/us/bfdr/StructureDefinition/Patient-mother-vr|2.0.0"] },
      name: [{ family: "Doe", given: ["Jane"] }],
      birthDate: "1990-04-01",
      address: [{ postalCode: "98101" }],
    }},
    { fullUrl: "urn:uuid:child-1", resource: {
      resourceType: "Patient", id: "child-1",
      meta: { profile: ["http://hl7.org/fhir/us/bfdr/StructureDefinition/Patient-child-vr|2.0.0"] },
      gender: "female",
      birthDate: "2026-05-01",
    }},
    { resource: {
      resourceType: "Observation",
      subject: { reference: "Patient/child-1" },
      code: { coding: [{ system: "http://loinc.org", code: "8339-4" }] },
      valueQuantity: { value: 3400, unit: "g", code: "g" },
    }},
    { resource: {
      resourceType: "Observation",
      subject: { reference: "Patient/child-1" },
      code: { coding: [{ system: "http://loinc.org", code: "9274-2" }] },
      valueQuantity: { value: 9, unit: "{score}" },
    }},
    { fullUrl: "urn:uuid:birth-encounter-1", resource: {
      resourceType: "Encounter", id: "birth-encounter-1",
      location: [{ location: { reference: "Location/birth-location-1" } }],
    }},
    { fullUrl: "urn:uuid:birth-location-1", resource: {
      resourceType: "Location", id: "birth-location-1",
      type: [{ coding: [{ system: "http://snomed.info/sct", code: "22232009", display: "Hospital" }] }],
    }},
  ],
};

const resp = await fetch(`${BASE}/api/registry/fhir/Bundle`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/fhir+json",
  },
  body: JSON.stringify(bundle),
});
if (!resp.ok) throw new Error(`Ingest failed: ${resp.status}`);
console.log("Accepted:", resp.headers.get("Content-Location"));

3. Poll for the result

The Content-Location header is the status URL. Poll it until status is completed or failed:

curl https://birthtracks.twosportday.com/api/registry/fhir/ingestions/<id> \
  -H "Authorization: Bearer rgk_your_token_here"

A completed ingestion looks like:

{
  "id": "0c5e...",
  "status": "completed",
  "accepted": 1,
  "rejected": 0,
  "outcome": {
    "accepted": [
      { "reference": "CHART-001", "submission_uuid": "9b2f..." }
    ],
    "rejected": []
  },
  "completedAt": "2026-05-01T12:00:00+00:00"
}

Each entry’s reference is the record’s chart number (Bundle.identifier.value — CHART-001 above), or record[N] when the course of care carries none. outcome is always the accepted/rejected pair. If a record is rejected, rejected is non-zero and the failing record appears in outcome.rejected[], each entry carrying its own FHIR OperationOutcome with profile-specific diagnostics — for example, a course of care missing its child Patient. A terminal status of failed is different: it means the push could not be processed at all, and outcome is a small error object instead — see Failed ingestions.

Next steps

The full data dictionary — what each FHIR field maps to in the canonical model.
Birth Registry → Integrations also lists recent FHIR ingestions — each push’s accepted and rejected counts and status — so you can see pushes landing without polling. The per-record outcomes stay behind the status endpoint.
The API reference and the machine-readable OpenAPI spec.