Skip to content
Developers

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.

GET /api/v1/me
# 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"
}
REST API 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.

  1. Get your key

    A partner admin creates it under Settings → API in the partner portal. Send it on every call as X-API-Key.

  2. Create the patient

    POST /api/v1/patients/create with name, contact details and address. Pass your own external_id to match records later.

  3. Open the encounter

    POST /api/v1/encounters/create with the intake answers and offerings. A clinician licensed in the patient's state picks it up.

POST /api/v1/encounters/create
# 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
Resources

What the API covers.

Every path below sits under /api/v1. The reference lists each route with its fields and responses.

Full reference
  • 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
  • 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
  • Offerings

    The programs you sell, managed from code as well as the portal.

    • GET/offerings/search
    • POST/offerings/create
    • PATCH/offerings/{id}
  • Intake forms

    Find the published intake for an offering and read its questions.

    • POST/intake-forms/search
    • GET/intake-forms/{id}/questions
  • Lookups

    Reference data for building orders: ICD-10 codes, medications, pharmacies, allergens.

    • GET/lookups/icd-codes
    • GET/lookups/pharmacies
    • GET/allergens/search
  • Billing

    Your balance, charges and payments, for reconciliation.

    • GET/billing/balance
    • GET/billing/charges
    • GET/billing/payments
  • Webhook deliveries

    Your endpoints and every delivery attempt made to them.

    • GET/webhooks
    • GET/webhooks/{id}/deliveries
  • Account

    Check which partner a key belongs to, before you go live.

    • GET/me
Webhooks

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.created
  • encounter.updated
  • encounter.completed
  • encounter.cancelled

Prescriptions

  • encounter.rx_sent
  • encounter.rx_accepted
  • encounter.rx_failed
  • encounter.rx_cancel_requested
  • encounter.rx_cancelled
  • encounter.rx_cancel_denied

Treatments

  • encounter.treatment.created
  • encounter.treatment.updated
  • encounter.treatment.deleted

Messages

  • encounter.message.created

Patients

  • patient.created
  • patient.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-Signature
v1= followed by the hex HMAC-SHA256
NODE verify-webhook.js
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.