Skip to main content
PUT
Set your brand's display identity

Authorizations

Authorization
string
header
required

Per-client API key (M2M). Presented as Authorization: Bearer <key>.

Headers

X-Brand-Id
string
required

Your brand id (brd_...). It must be one of the brands your API key's account owns; with a publishable key it must be the one brand the key was issued for. A missing or malformed value is refused with 400, and an unknown or foreign brand with 404.

Pattern: ^brd_[A-Za-z0-9][A-Za-z0-9_-]*$
Idempotency-Key
string

Send a unique value on every write. Do not assume that a repeated request with the same key is de-duplicated unless the operation says so.

Path Parameters

brand_id
string
required

the brand whose display identity to set (must match X-Brand-Id).

Pattern: ^brd_[A-Za-z0-9][A-Za-z0-9_-]*$

Body

application/json

The client self-serve write payload. It carries display, legal_documents, consent_holder, or any of them together: the client sets or updates its own brand display-identity block, its own terms of service and privacy policy links, and who holds its consent documents, with its own API key. A legal_documents write is applied only if the configuration has not changed since it was read; otherwise it is refused with 409 version-mismatch and nothing is written. There is deliberately no theme, redirect-allowlist, or charge-topology field — those stay platform-controlled; a client cannot set them here (any such key is barred by additionalProperties:false and, at runtime, is never read). Each block is merged onto the existing configuration and validated UNCHANGED by the brand-config validator. A display block cannot carry wording: a copy key is refused with 422, and the validator's issues are returned as given.

Choose who holds your brand's consent documents and identity: purple (Purple's consent documents apply, and your own legal links are not needed) or client (your own legal document links apply). Any other value is refused with 422 and the issue brand.consent_holder. Until it is chosen, your brand is not ready for patients.

Available options:
purple,
client
display
object

the per-brand display-identity block to set or update (merged onto the existing config).

Your brand's own terms of service and privacy policy links, set or updated. A slot you send replaces that slot's stored link; a slot you omit keeps its stored link. Each link must be an absolute https URL to the document as your patients should read it; anything else (a relative path, an http: URL, an empty string) is refused with 422 and the issue brand.legal_documents.url, and any other slot is refused with 422 and the issue brand.legal_documents.slot. These links are shown to patients before they consent. You do not need them when you chose consent_holder: purple: Purple's documents apply then.

Response

the stored configuration (the same projection you read back)

data
object
required

A brand's platform configuration as the platform holds it — clinically inert BY CONSTRUCTION (the validator enforces a top-level allowlist + a recursive clinical-shaped-key denylist). The your readback and the platform staff view return this EXACT shape. Presentation and commercial reach only; never a clinical field. additionalProperties:false mirrors the validator's top-level allowlist.