Design Your Integration

The first decision is how much of the experience you own. Three methods, in increasing order of effort and control.

At a glance

Choosing

Start with UI + API unless you have a specific reason not to. It is the method most partners land on, and the one these docs are most complete for.

Pick UI Only if you want the shortest path to something working and can accept that your clinicians create their own Blueprint accounts. It is a good proof of concept, and a reasonable permanent choice for a small deployment.

Pick API Only if you already have working audio capture you intend to keep, or if regulatory or UX constraints mean you cannot embed third-party UI. Be clear-eyed about the cost: browser audio capture across devices, microphone permissions, device selection, level metering, connection loss and resume, and long-upload reliability are all things Blueprint's UI already handles.

UI Only

You add a script tag. Blueprint's UI appears inside your page and handles everything from account creation to note review.

Clinicians authenticate to Blueprint themselves — each needs a Blueprint account, though the embedded UI makes signup quick, and a clinician already signed in to Blueprint elsewhere is recognized automatically.

The clinician moves the finished note into your application. You can improve on that with a small amount of frontend code — selecting the current client automatically, or capturing the note when it is generated.

One caveat that shapes this method. The original "Copy Note" hand-off — where the clinician clicks a button and your page receives the note text directly — only works on the older full widget. On the current default widget, use onNoteGenerated and fetch the note by API instead, which needs a backend. If a pure zero-backend integration is a hard requirement, read UI Only Integrations carefully before committing.

→ UI Only Integrations

UI + API

You add the same script tag, but your backend owns the data model. It creates clinician and client records in Blueprint mirroring your own users and patients, and mints a short-lived token so the embedded UI can act on a clinician's behalf. Clinicians never sign up for anything.

Blueprint still captures the audio. Documentation comes back to you as a webhook, and your backend fetches and stores it — so notes land in your database rather than being pasted in.

→ UI + API Integrations

API Only

You build the entire experience, including audio capture. Your backend creates the clinician and client records, then makes the recording available at a URL Blueprint fetches. Documentation comes back by webhook.

→ API Only Integrations

Things that are true of all three

• You always need clinician and client records in Blueprint. Even in API Only, documentation has to attach to a clinician and a client. Link them to your own records with externalId — see Concepts.
• In UI Only and UI + API, session audio never touches your servers. The embedded UI uploads directly to Blueprint. This is usually the point: it keeps recordings out of your infrastructure and out of scope for your own handling.
• Documentation is always generated asynchronously. Nothing returns a finished note synchronously. Design for the webhook.
• You can mix. Nothing stops you from embedding the UI for recording while also calling the API for assessments, programs, or note preferences. UI + API is exactly that combination.

Before you build

• Environments & Base URLs — base URLs, and the CSP entries you need if embedding
• Authentication — credentials and token lifetimes
• Quickstart — the whole flow in curl