Skip to content
BirthTracks Help CenterBirthTracks 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.

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.

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://laravel-sandbox.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}" }
      }}
    ]
  }'

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://laravel-sandbox.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}"},
        }},
    ],
}


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://laravel-sandbox.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}" },
    }},
  ],
};


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://laravel-sandbox.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": null,
  "completedAt": "2026-05-01T12:00:00+00:00"
}

If a record is rejected, rejected is non-zero and outcome holds a FHIR OperationOutcome with profile-specific diagnostics — for example, a course of care missing its child Patient.

Next steps

Section titled “Next steps”