Keep your stack.Plug in clinicians.
A REST API to create patients and encounters from your checkout, and signed webhooks for everything that happens after. Keys and endpoints are managed by your team in the partner portal.
# check that your key works curl https://blueprintmd.com/api/v1/me \ -H "X-API-Key: $BMD_API_KEY" { "success": true, "partner": { "name": "Northwind Health", "status": "active", … }, "api_version": "v1" }
Three calls to a first encounter.
JSON over HTTPS, authenticated with one header. The full reference, with request and response schemas for every route, is generated from the code and always current.
-
Get your key
A partner admin creates it under Settings → API in the partner portal. Send it on every call as
X-API-Key. -
Create the patient
POST /api/v1/patients/createwith name, contact details and address. Pass your ownexternal_idto match records later. -
Open the encounter
POST /api/v1/encounters/createwith the intake answers and offerings. A clinician licensed in the patient's state picks it up.
# create an encounter from your checkout curl https://blueprintmd.com/api/v1/encounters/create \ -H "X-API-Key: $BMD_API_KEY" \ -H "Idempotency-Key: ord_8f2c1a" \ --json '{"patient_id": "a3bb189e-…", "intake_form_id": "b4cc290f-…", "offering_ids": ["…"], "responses": […]}'
Retries are safe
Send an Idempotency-Key on patient, encounter and offering create calls. If a timeout makes you retry, you get the first response back instead of a duplicate.
- Same key, same body
- The stored response, with
Idempotent-Replayed: true - Same key, different body
422: a key can't be reused for another request- First request still running
409: retry shortly- Server error
- Not stored, so your retry really runs again
- How long keys last
- 24 hours
What the API covers.
Every path below sits under /api/v1. The reference lists each route with its fields and responses.
-
Patients
Create, read, update and search patients, with your own external ID.
- POST
/patients/ create - GET
/patients/ {id} - POST
/patients/ search - GET
/patients/ {id}/ encounters
- POST
-
Encounters
Open an encounter, follow its status, add photos and message the care team.
- POST
/encounters/ create - GET
/encounters/ {id}/ status-history - POST
/encounters/ {id}/ photos - POST
/encounters/ {id}/ messages
- POST
-
Offerings
The programs you sell, managed from code as well as the portal.
- GET
/offerings/ search - POST
/offerings/ create - PATCH
/offerings/ {id}
- GET
-
Intake forms
Find the published intake for an offering and read its questions.
- POST
/intake-forms/ search - GET
/intake-forms/ {id}/ questions
- POST
-
Lookups
Reference data for building orders: ICD-10 codes, medications, pharmacies, allergens.
- GET
/lookups/ icd-codes - GET
/lookups/ pharmacies - GET
/allergens/ search
- GET
-
Billing
Your balance, charges and payments, for reconciliation.
- GET
/billing/ balance - GET
/billing/ charges - GET
/billing/ payments
- GET
-
Webhook deliveries
Your endpoints and every delivery attempt made to them.
- GET
/webhooks - GET
/webhooks/ {id}/ deliveries
- GET
-
Account
Check which partner a key belongs to, before you go live.
- GET
/me
- GET
Every change, signed and sent.
Add an endpoint under Settings → Webhooks and pick the events you want, or leave them all unticked to receive every event, including ones added later.
Event catalogue
Encounters
encounter.createdencounter.updatedencounter.completedencounter.cancelled
Prescriptions
encounter.rx_sentencounter.rx_acceptedencounter.rx_failedencounter.rx_cancel_requestedencounter.rx_cancelledencounter.rx_cancel_denied
Treatments
encounter.treatment.createdencounter.treatment.updatedencounter.treatment.deleted
Messages
encounter.message.created
Patients
patient.createdpatient.updated
Each delivery is a JSON body with event, timestamp and data. Prescription events include the prescriber and the status of each offering.
Verify the signature
Every delivery carries two headers. Recompute the HMAC-SHA256 of {timestamp}.{raw body} with your webhook secret (Settings → API) and compare.
X-BlueprintMD-Timestamp- Unix time, in seconds, when the delivery was signed
X-BlueprintMD-Signaturev1=followed by the hex HMAC-SHA256
import crypto from 'node:crypto'; // keep the raw body: the signature covers its exact bytes const raw = express.raw({ type: 'application/json' }); app.post('/webhooks/blueprintmd', raw, (req, res) => { const ts = req.get('X-BlueprintMD-Timestamp'); const sig = req.get('X-BlueprintMD-Signature') ?? ''; const expected = 'v1=' + crypto .createHmac('sha256', process.env.BMD_WEBHOOK_SECRET) .update(`${ts}.${req.body}`) .digest('hex'); const valid = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); // also reject stale deliveries (we suggest a 5-minute window) const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300; if (!valid || !fresh) return res.sendStatus(401); const { event, data } = JSON.parse(req.body); // e.g. event === 'encounter.rx_sent' res.sendStatus(200); });
Ready to wire it up?
Partners get API keys and a webhook secret from the partner portal. Talk to us to set up your brand, and your developers can start as soon as your account is live.