API docs — Retrievant

Quickstart

Install the SDK or call the API directly. All examples use the sandbox environment, which returns synthetic patients and never touches real records.

# 1. Create a retrieval for a patient
curl https://sandbox.api.retrievant.example/v1/retrievals \
  -H "Authorization: Bearer sk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
    "patient": { "given_name": "Marie", "family_name": "Bouchard", "dob": "1984-02-09" },
    "scope": { "from": "2019-01-01", "record_types": ["encounters","labs","imaging","claims"] },
    "webhook_url": "https://yourapp.example/hooks/retrievant"
  }'

import Retrievant from "@retrievant/sdk";
const retrievant = new Retrievant(process.env.RETRIEVANT_KEY);

const retrieval = await retrievant.retrievals.create({
  patient: { givenName: "Marie", familyName: "Bouchard", dob: "1984-02-09" },
  scope: { from: "2019-01-01", recordTypes: ["encounters", "labs", "imaging", "claims"] },
  webhookUrl: "https://yourapp.example/hooks/retrievant",
});
console.log(retrieval.consentUrl); // send this to the patient

from retrievant import Retrievant
client = Retrievant(api_key=os.environ["RETRIEVANT_KEY"])

retrieval = client.retrievals.create(
    patient={"given_name": "Marie", "family_name": "Bouchard", "dob": "1984-02-09"},
    scope={"from": "2019-01-01", "record_types": ["encounters", "labs", "imaging", "claims"]},
    webhook_url="https://yourapp.example/hooks/retrievant",
)
print(retrieval.consent_url)  # send this to the patient

Authentication

Every request carries a bearer token. Sandbox keys start with sk_sandbox_, production keys with sk_live_. Keys are scoped to a workspace and can be restricted to specific record types.

Never call the API from a browser. Keys grant access to health data; keep them server-side and rotate them from the dashboard.

Retrievals

A retrieval is the unit of work: one patient, one scope, one assembled record.

POST/v1/retrievals

Field	Type	Description
patient	object	Given name, family name, date of birth. Optional: last known postcode, phone.
scope.from	date	Earliest record date to request.
scope.record_types	string[]	Any of encounters, labs, imaging, medications, allergies, claims, coverage, notes.
scope.providers	string[]	Optional. Limit to named providers; otherwise the planner discovers them.
webhook_url	url	Where to send status events.
priority	enum	`standard` or `urgent`. Urgent escalates to phone within 5 minutes.

GET/v1/retrievals/{id}

Returns status (awaiting_consent, in_progress, complete, partial), per-source progress, and the gap report once finished.

The response includes a consent_url. Send it to the patient by SMS, email, or embed it in your app. The page is hosted by Retrievant, brandable, and available in English, French, German, Spanish and Dutch. Nothing is retrieved until the patient signs.

Patients can later revoke from their own dashboard; you receive a retrieval.revoked event and must delete downstream copies within 30 days.

Webhooks

Events are signed with HMAC-SHA256 in the Retrievant-Signature header.

Event	When
retrieval.consented	Patient signed. Agents dispatched.
retrieval.source_complete	One provider returned. Includes source, method, field count.
retrieval.escalated	An agent handed off to a human specialist.
retrieval.complete	Assembled record ready. Includes download URL (expires in 24h).
retrieval.revoked	Patient withdrew consent.

Record format

Records are delivered as a FHIR R4 Bundle. Every resource carries a meta.source URI and a Retrievant provenance extension naming the provider, the retrieval method, and a confidence score for extracted (OCR'd) values. PDF and flat JSON exports are also available.

Try it live

Fire a sandbox retrieval from this page. It runs against synthetic data and streams the same events you'd receive in production.

// response will stream here

Rate limits

Sandbox: 60 requests/minute. Production: 600 requests/minute, 10,000 retrievals/day by default. Limits are raised on request; check status for live latency.

Build on Retrievant.