Concepts

Object hierarchy

Partner  (you)
└── Organization        a customer of yours — a practice or group
    └── Clinic          a location within that organization
        └── Clinician   the end user of your application
            └── Client  the person being treated
                └── Session          one recorded encounter
                    ├── Transcript
                    ├── Summary
                    ├── Progress Note
                    └── MDM elements  (prescribers)

Clinician and client data is separated by organization boundaries. A request for a resource that
belongs to another partner or another organization returns 404 — the same response you get for an
ID that does not exist at all, so the API never confirms whether an ID belongs to someone else. See
Errors.

Who's who

Partner — an organization using the Blueprint platform and combining it with their own
applications to create an integrated experience. That is you. Represented by partner in the API.

Partner application ("your application") — the application being integrated with Blueprint,
usually an electronic health record (EHR) system used by a clinician.

Organization — an organization of clinicians, such as a group practice. Typically a customer of
yours who wants to use your application with Blueprint. Represented by organization.

Clinic — a location or facility within an organization, for example a practice with multiple
offices. At least one clinic must exist within an organization. For practices that do not want to
subdivide by location, create a single clinic mirroring the organization. Represented by clinic.

Clinician — the end user of your application, typically a mental health professional such as a
therapist or psychiatrist. Represented by clinician.

Client ("patient") — the person being treated, and the subject of the clinical artifacts
Blueprint generates. Represented by client.

Blueprint uses "client" in most of the API, but not all of it: a few places use "patient" instead.
Notably the assessment_completed webhook payload has a patientId field where every other event
uses clientId, and the widget's patientReference setting controls display terminology. They
refer to the same person. When this documentation says "API client" it means a piece of software,
not a person.

Clinician roles

Every clinician holds the clinician role. You can also grant elevated roles, such as administering
a clinic or the whole organization, by passing roles when you create a clinician
(POST /clinics/{clinicId}/clinicians) or update one (PATCH /clinicians/{clinicianId}).
GET /clinicians/{clinicianId} returns the roles a clinician holds.

Do not hardcode the list. Call GET /organizations/{organizationId}/clinician-roles for the roles
you can assign in an organization, each with a stable key, a display name, and a description
of what it allows:

{
  "data": [
    { "key": "clinician", "name": "Clinician", "description": "...", "isDefault": true },
    { "key": "org_admin", "name": "Organization Admin", "description": "...", "isDefault": false }
  ],
  "rolesManagedByIdentityProvider": false
}

Pass those keys exactly as returned. A key that is not in the list returns 400.

• On create, omit roles or send [] for a clinician with no elevated roles. You never need to
  send clinician; it is always held.
• On update, roles replaces the clinician's assignable roles, so send the complete set you want
  them to have. [] removes every elevated role. Omit roles to leave them unchanged.
• Roles granted in Blueprint outside this list are never changed by the API, whatever you send.

Some organizations manage roles through their identity provider using directory sync. For these,
rolesManagedByIdentityProvider is true and only clinician is listed. Creating a clinician with
any other role, or sending roles on update at all, returns 409, because the next directory sync
would undo the change. Create clinicians without roles and let the identity provider assign them.

Clinical artifacts

Everything below is generated asynchronously after a session ends. Wait for the corresponding webhook
rather than polling — see Listening to Webhooks.

Session — one recorded encounter between a clinician and a client. Sessions carry the setting
(in-person or telehealth), the note type to generate, and optionally your own
sessionExternalId. Represented by session.

Transcript — the diarized text of the session, as timed items with a speaker number.

Summary — a short narrative summary of the session. A session can have summaries aimed at
different audiences.

Progress Note — the clinical note. Returned as an ordered array of sections, each with a
machine-readable key, a human-readable title, and content:

{
  "note": [
    { "key": "subjective", "title": "Subjective", "content": "Client reported..." },
    { "key": "plan",       "title": "Plan",       "content": "Client will continue..." }
  ]
}

This shape lets you render a note type you have never seen before without knowing its sections in
advance. The accompanying template tells you the note type and the sections it is expected to
contain.

A clinician can finalize a note, which sends the progress_note_finalized webhook but does not
lock it. Separately, a clinician can sign and lock a note in Blueprint. Attempts to patch,
magic-edit, or regenerate a locked note return 403.

Every note also carries createdAt and updatedAt. Regenerating or magic-editing a note creates a
new note, so createdAt orders a session's notes from oldest to newest.

MDM elements — medical decision making elements (problems addressed, risk of complications,
crisis intervention), used by prescribers for billing support. Available via
GET /sessions/{sessionId}/mdm.

Note type — the format of the progress note: soap, dap, birp, girp, emdr,
case_management, intake, supervision, couple_soap, pirp, sirp, pie, and the prescriber
formats prescriber_initial_evaluation, prescriber_followup, and
prescriber_followup_interventions.

Do not hardcode this list. Call
GET /organizations/{organizationId}/progress-note-types to get the types available to a given
organization, including which session type and clinician group each applies to.

Session type — individual, couple, or group.

Treatment approach — the modality used, for example cbt, dbt, emdr, act,
gottman_method, ifs. Influences how the note is written.

Measurement-based care

Assessment — a standardized clinical measure (PHQ-9, GAD-7 and similar). List what a clinic has
available with GET /clinics/{clinicId}/assessments.

There are three ways to use them, and the distinction matters:

Assessment score — the result of a completed assessment: a total score plus per-question answers.
Arrives via the assessment_completed webhook and is fetched from
GET /assessment-scores/{assessmentScoreId}.

Program — a grouping used to organize clients within an organization, for example a care pathway
or cohort. Clients can be assigned to and removed from programs.

Identifiers

Internal ID — a UUID generated by Blueprint, universally unique, used as the path segment in API
routes. Example: 00000000-0000-0000-0000-000000000000.

External ID — a string you generate and attach to a Blueprint entity: a row ID, a user ID, a
medical record number. Optional, but expected to be unique within a clinical organization.

External IDs are the recommended way to link the two systems, because they let you avoid storing
Blueprint's UUIDs alongside your own records. They are searchable:

GET /v2/clinicians/{clinicianId}/clients?externalId=mrn-77120
GET /v2/clinics/{clinicId}/clinicians?externalId=user-5501

If you do store Blueprint UUIDs, every level of the hierarchy can be read back directly by its ID:

GET /v2/organizations/{organizationId}
GET /v2/clinics/{clinicId}
GET /v2/clinicians/{clinicianId}
GET /v2/clients/{clientId}
GET /v2/sessions/{sessionId}

Organizations and clinics are new additions here. Resolving one used to mean paging the list endpoint
until the ID appeared — 10 records at a time, with no filters — so answering "what is this
organization called?" could cost many round trips. Both now return the same shape their list endpoint
returns.

organization, clinic, clinician, and client all accept externalId on create. Sessions use a
separate sessionExternalId, which is echoed back in webhook payloads so you can attribute a
generated note to the appointment it came from without a lookup.

Set them on everything you create. Because the API does not support idempotency keys, externalId is
also the only reliable way to tell whether a create that timed out actually succeeded — see
Pagination & Limits.