Skip to content
BirthTracks Help CenterBirthTracks Help Center

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

Section titled “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

Section titled “1. Get an API key”

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

Two things gate minting from that page:

  • Your practice must be in the partner-EHR beta. The key-management UI ships dark until then — if you don’t see the API keys section, your practice isn’t enabled yet. 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.
  • You need a record-managing role (practice admin or provider). Read-only Viewer and write-only Scribe seats can see existing keys but cannot issue one.

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

Section titled “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

Section titled “curl”
Terminal window
curl -X POST https://birthtracks.neighborhoodtechnologies.co/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}" }
      }}
    ]
  }'

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

Python

Section titled “Python”
import requests


BASE = "https://birthtracks.neighborhoodtechnologies.co"
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}"},
        }},
    ],
}


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

Section titled “JavaScript”
const BASE = "https://birthtracks.neighborhoodtechnologies.co";
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}" },
    }},
  ],
};


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

Section titled “3. Poll for the result”

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

Terminal window
curl https://birthtracks.neighborhoodtechnologies.co/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": "Patient/mother-1", "submission_uuid": "9b2f..." }
    ],
    "rejected": []
  },
  "completedAt": "2026-05-01T12:00:00+00:00"
}

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

Section titled “Next steps”