curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "external_visit_id": "consult-1001",
    "external_patient_id": "acme-patient-90210",
    "questionnaire_type": "glp-1",
    "questionnaire": {
      "type": "glp-1",
      "version": "1.0",
      "title": "GLP-1 Medical Assessment",
      "answers": [
        { "id": "bmi", "question": "BMI", "answer": "32.1" },
        { "id": "contraindications", "question": "Any contraindications?", "answer": "No" },
        { "id": "goals", "question": "Treatment goals", "answer": "Weight management" }
      ]
    },
    "notes": "GLP-1 eligibility review"
  }'

curl -X PUT "https://n-kumar.bespoke-consults.designingit.co/v1/visits/consult-1001/questionnaire" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "questionnaire_type": "glp-1",
    "questionnaire": {
      "type": "glp-1",
      "version": "1.0",
      "title": "GLP-1 Medical Assessment",
      "answers": [
        { "id": "bmi", "question": "BMI", "answer": "31.4" }
      ]
    }
  }'

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits/consult-1001/images" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "face_url": "https://cdn.partner.example/patients/pt-1/face.jpg",
    "photo_id_url": "https://cdn.partner.example/patients/pt-1/id-front.jpg"
  }'

Bespoke Prescription API — Developer Guide

Version 1.2

This guide is everything you need to integrate with the Bespoke Prescription API: authentication, endpoints, request and response payloads, status lifecycle, errors, and recommended patterns.

External references

Partners should send stable external ids so Bespoke updates existing objects instead of creating disconnected snapshots. Typed aliases are accepted and returned alongside the legacy external_ref / brand_code names:

Recommended minimum: external_patient_id, external_visit_id, external_product_id. Look up a prescription with GET /prescriptions/{external_prescription_id}.

What the API does

You submit clinical consults (visits). When a Bespoke provider approves a consult, Bespoke creates the prescriptions for fulfilment. You then:

1. Track those prescriptions with GET /prescriptions
2. Receive status as the order is accepted, shipped, and delivered

You can also manage patients independently via /v1/patients (create/upsert, retrieve, update). Reuse the same external_ref on later consults so demographics are not duplicated.

One partner account can own many brands (sub-companies). Send brand_code on patients and prescriptions so Bespoke knows which brand every record belongs to. Omitted brand_code uses the partner's default brand. Hierarchy:

Partner → Brand → Patient → Visit → Prescription

You track progress by polling GET /prescriptions/{submission_id} and/or receiving outbound partner webhooks (configured per account).

Your system  →  POST /v1/patients              →  Bespoke patient record (optional first step)
Your system  →  POST /v1/visits                →  Bespoke consult (Open / stored `pending` + questionnaire)
Your system  ←  webhook consultation.created
Your system  →  PUT  /v1/visits/{id}           →  notes / clinic / practitioner (no status change)
Prescriber   →  Completed or Declined           →  Bespoke consult decision
Your system  ←  webhook consultation.approved | declined
                 ↳ on approve: fills + doctor details + pharmacy-compatible e-script fields
Your system  ←  GET  /v1/prescriptions/{id}    ←  status updates (uuid or external_prescription_id)

Partner webhooks (callbacks)

Outbound webhooks are disabled by default. A Bespoke admin enables them on your account; you then configure the callback URL in Partner dashboard → Integration → Webhooks.

Full webhook contract (events, signatures, decline codes, pharmacy return):
/docs/webhooks

Base URL

https://n-kumar.bespoke-consults.designingit.co/v1

Replace the host with the URL your account manager provides for sandbox or production.

All requests must use HTTPS. Plain HTTP is rejected.

Authentication

Every request requires two headers:

GET /v1/ping HTTP/1.1
Host: api.bespoke.example
X-Api-Key: bsk_live_7Qd3xR2mVn8pLc4KfW1sTbYz
X-Api-Secret: <your secret>
Accept: application/json

Credentials are issued in the Bespoke partner dashboard. The secret cannot be recovered later; if it is lost, rotate the credential and deploy the new pair.

Rotation issues a new pair and keeps the previous pair valid for 24 hours so you can cut over without downtime.

Never put credentials in a query string. Never call the API from a browser or mobile app — only from your backend.

Sandbox keys use the bsk_test_ prefix. Live keys use bsk_live_.

Request and response conventions

Idempotency

Write endpoints such as POST /visits and POST /patients upsert by your external ids, so retrying the same payload updates the existing record instead of creating a duplicate. Prescriptions are not created via the API.

Rate limits

120 requests per minute per account (default). Over the limit:

• HTTP 429
• Code rate_limited
• Header Retry-After (seconds)

Back off and retry. Do not busy-loop.

Endpoints

GET /ping

Smoke-test credentials (useful in deploy pipelines).

curl "https://n-kumar.bespoke-consults.designingit.co/v1/ping" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

200 OK

{
  "status": "ok",
  "account": "Acme Health",
  "environment": "live",
  "server_time": "2026-08-12T11:14:03+00:00"
}

GET /medications

List medications the pharmacy network supports (and, when you have linked partner catalog products, only those linked items).

Query params: q (search name / strength / external id), brand_code / brand_id (limit to a brand's linked catalog).

curl "https://n-kumar.bespoke-consults.designingit.co/v1/medications?q=sema" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

200 OK

{
  "data": [
    {
      "medication_id": "3f2a1c8e-9b4d-4e6a-8f1c-2d7e9a0b5c4d",
      "external_product_id": "prx-sema-025",
      "name": "Semaglutide",
      "strength": "0.25mg",
      "ndc": null,
      "default_directions": "Inject 0.25 mg subcutaneously once weekly"
    }
  ]
}

Use external_product_id on consults when identifying a catalog product.

GET /products

Identical to GET /medications (path alias for partners that call the catalog “products”).

POST /patients

Create or update a standalone patient for your account. Identity is your external_ref (unique per account). Sending the same external_ref again updates demographics instead of creating a duplicate.

Returns 201 Created on first insert, 200 OK on update.

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/patients" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "external_ref": "acme-patient-90210",
  "first_name": "Dana",
  "last_name": "Whitfield",
  "date_of_birth": "1986-04-11",
  "gender": "female",
  "email": "dana@example.com",
  "phone": "3055551234",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4",
    "city": "Miami",
    "state": "FL",
    "postal_code": "33101"
  }
}'

201 / 200 response

{
  "patient_id": "3f2a1c8e-9b4d-4e6a-8f1c-2d7e9a0b5c4d",
  "external_ref": "acme-patient-90210",
  "brand_id": "7c1e9a2b-4d5f-4a8e-9c3b-1f0e2d4a6b8c",
  "brand_code": "brand-a",
  "first_name": "Dana",
  "last_name": "Whitfield",
  "date_of_birth": "1986-04-11",
  "gender": "f",
  "email": "dana@example.com",
  "phone": "305-555-1234",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4",
    "city": "Miami",
    "state": "FL",
    "postal_code": "33101"
  },
  "created_at": "2026-08-12T11:14:03+00:00",
  "updated_at": "2026-08-12T11:14:03+00:00"
}

Response patient_id is the Bespoke patient UUID. Use either patient_id or external_ref on later GET/PUT calls (add ?brand_code= when the same ref exists under multiple brands). Reuse the same external_ref + brand_code on later consults.

GET /patients/{external_ref_or_patient_id}

Retrieve one patient owned by your account. Path may be your external_ref or the Bespoke patient_id UUID.

curl "https://n-kumar.bespoke-consults.designingit.co/v1/patients/acme-patient-90210" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

200 OK — same body as POST /patients. 404 not_found if unknown or owned by another account.

PUT /patients/{external_ref_or_patient_id}

Replace demographics for an existing patient. Path identifies the patient (external_ref or patient_id). Body uses the same fields as POST /patients except external_ref is optional (identity cannot be changed via the body).

200 OK on success. 404 if the patient does not exist for your account.

GET /patients

List patients for your account. Optional brand_code / brand_id to scope to one brand.

POST /visits

Open a clinical consult before sending a prescription. It starts Open (stored pending). Completing the consult is a separate explicit action — submitting an Rx never marks the visit Completed.

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "consult-1001",
    "patient_ref": "acme-patient-90210",
    "notes": "GLP-1 eligibility review"
  }'

Medical questionnaire (clinical — Bespoke only): send on POST /visits or PUT /visits/{id}/questionnaire. Providers review answers in the admin Visits screen before completing the consult and issuing a prescription.

Never sent to the pharmacy network. The pharmacy receives only the resulting prescription/order fields. Do not put questionnaire content in directions, metadata on prescriptions, or any pharmacy payload.

Example questionnaire body:

{
  "type": "glp-1",
  "version": "1.0",
  "title": "GLP-1 Medical Assessment",
  "answers": [
    { "id": "bmi", "question": "BMI", "answer": "32.1" },
    { "id": "contraindications", "question": "Any contraindications?", "answer": "No" }
  ]
}

Consultations have three statuses. The JSON status field is the stored value:

Opening the consult in /prescriber may store in_progress; the status stays Open. needs_information, cancelled, and abandoned are not product statuses.

Partners may withdraw an Open consult only while it is still stored pending (cancelled on POST /visits/{id}/status). That is a partner API action, not a fourth consultation status.

PUT /visits/{id}

Update consult fields without changing status: notes, clinic_id / nested clinic, practitioner_id, metadata. Status changes use the endpoints below.

POST /visits/{id}/status

Partners may only withdraw an Open consult while it is still stored pending:

{ "status": "cancelled", "reason": "Patient withdrew" }

Partners cannot set Completed or Declined. A Bespoke provider reviews and completes or declines in the consult UI. After a provider has opened the consult (stored in_progress) or closed it, partners cannot withdraw it.

Terminal states cannot be reopened. Creating a prescription never changes visit status.

POST /visits/{id}/complete

Not available to partners. Completing (approving) a consult is a Bespoke provider action.

POST /visits/{id}/cancel

Shortcut for { "status": "cancelled" }. Works only while the consult is Open and still stored pending. Optional body: { "reason": "…" }.

PUT /visits/{id}/questionnaire

Attach or replace the medical assessment on an existing consult (same questionnaire / questionnaire_type fields as create). POST to the same path is accepted as an alias. Clinical data stays on the visit for provider review and is never relayed to the pharmacy.

POST /visits/{id}/images

Attach optional clinical photos as partner-hosted HTTPS URLs. Send one or both:

Aliases also accepted: face / photo_id, or nested under images (images.face, images.photo_id, …). The same fields may be sent on POST /visits or PUT /visits/{id}.

Photos are not required to complete a consult. Re-submitting replaces the previous URL for that slot. Photos are clinical review data only — never sent to the pharmacy network.

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits/consult-1001/images" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "face_url": "https://cdn.partner.example/patients/pt-1/face.jpg",
    "photo_id_url": "https://cdn.partner.example/patients/pt-1/id-front.jpg"
  }'

Visit responses include:

{
  "images_complete": true,
  "images": {
    "face": {
      "slot": "face",
      "url": "https://cdn.partner.example/patients/pt-1/face.jpg",
      "uploaded_at": "2026-08-28T12:00:00+00:00"
    },
    "photo_id": {
      "slot": "photo_id",
      "url": "https://cdn.partner.example/patients/pt-1/id-front.jpg",
      "uploaded_at": "2026-08-28T12:00:00+00:00"
    }
  }
}

GET /visits/{id}/images/{slot}

Resolve one photo (face or photo_id) using the same API credentials. Responds with a redirect to the partner-hosted source_url.

GET /visits/{id}/messages · POST /visits/{id}/messages

Medical messaging thread for one consult (patient ↔ provider). Requires medical messaging enabled on your partner account (admin toggle; off by default).

POST body:

Provider replies in the Bespoke Message center; when webhooks are enabled you receive medical_message.created. Full contract: /docs/messaging.

GET /visits / GET /visits/{id}

List (filter ?status= / ?patient_ref= / brand) or retrieve one consult. ?status= uses the stored value (pending, in_progress, completed, declined). Product statuses are Open (pending / in_progress), Completed, and Declined. The visit response includes questionnaire_type, questionnaire, and questionnaire_submitted_at when present.

POST /clinics

Create or update a clinic under your brand. Upserts by external_ref when provided.

Response includes clinic_id, external_ref, brand fields, name, phone, address.

GET /clinics / GET /clinics/{id}

List or retrieve clinics for your account. Lookup by clinic_id UUID or external_ref.

POST /practitioners

Create or update a provider / practitioner. Upserts by npi under the brand. Must be linked to a clinic via clinic_id when known. Include state licenses where required.

Response includes practitioner_id (internal public uuid), external_ref, clinic, NPI, name, phone, address, and licenses.

Associate the provider with a consult via practitioner_id on POST /visits. Completing a consult requires a provider. When a prescription is issued for that visit, the same practitioner is returned on the submission (and may be inherited from the visit if you omit prescriber / practitioner_id on the Rx).

GET /practitioners / GET /practitioners/{id}

List or retrieve practitioners. Lookup by practitioner_id UUID or external_ref.

Prescriptions

Partners cannot create prescriptions via the API. When a Bespoke provider approves a consult, Bespoke creates the fills for that visit (count is set on your account). Use GET to list and poll those submissions.

GET /prescriptions/{submission_id_or_external_prescription_id}

Retrieve one submission by Bespoke submission_id (UUID) or your external_prescription_id (stored as external_ref). Optional ?brand_code= / ?brand_id= when looking up by external id under a multi-brand account.

Fetch one submission by Bespoke submission_id (UUID) or your external_prescription_id.

curl "https://n-kumar.bespoke-consults.designingit.co/v1/prescriptions/b4f0c1d2-9a76-4a1e-8f3b-2c5d7e9a0b11" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

200 OK (shipped example)

{
  "submission_id": "b4f0c1d2-9a76-4a1e-8f3b-2c5d7e9a0b11",
  "status": "shipped",
  "patient_ref": "acme-patient-90210",
  "medication": "Semaglutide",
  "strength": "0.25mg",
  "quantity": 4,
  "refills": 0,
  "tracking": {
    "carrier": "UPS",
    "number": "1Z999AA10123456784"
  },
  "timeline": [
    { "status": "queued", "at": "2026-08-12T11:14:03+00:00" },
    { "status": "accepted", "at": "2026-08-12T11:14:19+00:00" },
    { "status": "shipped", "at": "2026-08-13T16:02:44+00:00" }
  ],
  "created_at": "2026-08-12T11:14:03+00:00",
  "updated_at": "2026-08-13T16:02:44+00:00",
  "metadata": {
    "your_order_id": "ACME-88213"
  }
}

200 OK (failed example)

{
  "submission_id": "b4f0c1d2-9a76-4a1e-8f3b-2c5d7e9a0b11",
  "status": "failed",
  "patient_ref": "acme-patient-90210",
  "medication": "Semaglutide",
  "strength": "0.25mg",
  "quantity": 4,
  "refills": 0,
  "error": {
    "code": "pharmacy_rejected",
    "message": "Prescriber NPI is invalid. Fields: {\"prescribedBy.npi\":\"must be a valid NPI\"}"
  },
  "timeline": [
    { "status": "queued", "at": "2026-08-12T11:14:03+00:00" },
    { "status": "failed", "at": "2026-08-12T11:14:25+00:00" }
  ],
  "created_at": "2026-08-12T11:14:03+00:00",
  "updated_at": "2026-08-12T11:14:25+00:00",
  "metadata": {
    "your_order_id": "ACME-88213"
  }
}

error.message is actionable detail from the pharmacy network (vendor product names removed). Use it to understand why fulfilment failed.

404 — unknown id, or a submission that belongs to another account / outside retention.

Pause and activate fills (pharmacy routing required)

These endpoints work only when pharmacy routing is activated on your account so prescriptions go through the Bespoke pharmacy channel (admin: Route to pharmacy network).

If routing is off, or your account is set to return prescriptions to you (partner_return), pause and activate are not available. Those calls return 403 pharmacy_channel_required. Ask your account manager to turn on pharmacy routing if you need this.

The consult must already be completed. Shipped and delivered fills cannot be held.

POST /visits/{id}/prescriptions/pause

Hold remaining fills on a completed consult (pharmacy routing must be on).

Queued fills are held in Bespoke and are not relayed. Accepted (not yet shipped) fills are cancelled at the pharmacy and marked paused. Shipped and delivered fills are skipped.

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits/VISIT_ID/prescriptions/pause" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"reason": "Patient asked to hold remaining fills"}'

Optional prescription_id (UUID or your external_prescription_id) limits the call to one fill. reason is optional.

200

{
  "visit_id": "…",
  "action": "paused",
  "updated": 2,
  "unchanged": 0,
  "skipped": 1,
  "prescriptions": [
    { "submission_id": "…", "status": "paused" }
  ]
}

403 pharmacy_channel_required — pharmacy routing is not activated for the Bespoke pharmacy channel (account is partner_return, or fills are not sent through us).

422 — consult is not completed, or every fill has already shipped / been delivered.

POST /visits/{id}/prescriptions/activate

Release paused fills. They return to queued and are sent to the pharmacy again. Fills that were accepted (and therefore cancelled at the pharmacy when paused) are submitted as a new pharmacy order.

Same optional prescription_id as pause.

curl -X POST "https://n-kumar.bespoke-consults.designingit.co/v1/visits/VISIT_ID/prescriptions/activate" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

POST /prescriptions/{id}/pause and POST /prescriptions/{id}/activate do the same thing for a single fill and return that submission.

GET /prescriptions

List your submissions, newest first. Scoped to your account and retention window (default 90 days).

curl "https://n-kumar.bespoke-consults.designingit.co/v1/prescriptions?status=failed&per_page=25" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "Accept: application/json"

{
  "data": [
    {
      "submission_id": "b4f0c1d2-9a76-4a1e-8f3b-2c5d7e9a0b11",
      "status": "failed",
      "patient_ref": "acme-patient-90210",
      "medication": "Semaglutide",
      "strength": "0.25mg",
      "quantity": 4,
      "refills": 0,
      "error": {
        "code": "pharmacy_rejected",
        "message": "…"
      },
      "timeline": […],
      "created_at": "2026-08-12T11:14:03+00:00",
      "updated_at": "2026-08-12T11:14:25+00:00",
      "metadata": {}
    }
  ],
  "meta": {
    "per_page": 25,
    "next_cursor": "eyJpZCI6NDgyMX0"
  }
}

Pass cursor=<next_cursor> for the next page. When next_cursor is null, you are done.

Status lifecycle

queued → relaying → accepted → shipped → delivered
                 ↘ failed
                          shipped → voided
                 (admin) → cancelled

Polling guidance

• Poll no more than once per minute per submission.
• Most submissions reach accepted within seconds when the queue is healthy.
• shipped typically follows within a business day once fulfilment starts.
• After failed, do not keep polling the same id for recovery.

Errors

HTTP error shape

All API errors use one envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "The submission could not be processed because some fields are invalid.",
    "request_id": "5c2a1f80-6f0e-4d3a-9d1b-77a0c2e6b4f9",
    "fields": {
      "patient.date_of_birth": ["Must be a valid date in the format YYYY-MM-DD."],
      "prescription.quantity": ["Must be greater than zero."]
    }
  }
}

fields appears only on 422 validation_failed.

HTTP status codes

Submission-level failure codes

These appear on a failed submission under error.code:

Read error.message for fulfilment failures.

Recommended integration flow

1. Call GET /ping from your deploy pipeline with sandbox credentials.
2. Optionally GET /products (or /medications) to pick catalog ids.
3. Optionally POST /patients once per person (upsert by your external_ref).
4. POST /visits with questionnaire (photo URLs optional); later PUT /visits/{id}.
5. A Bespoke provider reviews and approves the consult. Bespoke then creates the prescriptions.
6. Poll GET /prescriptions (filter by patient_ref) or GET /prescriptions/{id} until terminal status.
7. If failed, show error.message to your operators.

Minimal happy-path sequence

GET  /v1/ping
GET  /v1/products               → catalog (optional)
POST /v1/patients               → 201 (optional; upsert by external_ref)
POST /v1/visits                 → 201 Open / stored pending (+ questionnaire; photo URLs optional)
                                  provider approves consult
GET  /v1/prescriptions          → fills created on approve
GET  /v1/prescriptions/{id}     → status=relaying | accepted | …
GET  /v1/prescriptions/{id}     → status=shipped (+ tracking)
GET  /v1/prescriptions/{id}     → status=delivered

Partner dashboard

In addition to the API, your team can sign in to the partner dashboard to:

• View Patients, Visits / consults, Assessments (questionnaires), and Prescriptions
• Browse Products, Brands, Clinics, and Practitioners
• Inspect failure messages and submission status history
• Rotate API credentials

Dashboard access is separate from API keys (email/password for your users). Ask your account manager to invite operators.

Sandbox vs live

Use sandbox credentials until your payloads consistently reach accepted. Then switch to live keys and the production base URL your account manager provides.

Integration checklist

• Credentials stored in a secret manager (never in source control)
• All calls made server-to-server over HTTPS
• Consults submitted with questionnaire (photo URLs optional)
• X-Request-Id captured in your logs
• Retries with backoff on 429, 500, and 503
• Polling capped (≤ 1/minute per submission)
• Tested end-to-end against sandbox before go-live

Support

Contact your account manager, or email support@bespoke.example.

Always include:

• submission_id and/or request_id (X-Request-Id)
• Approximate time of the request (UTC)
• Whether you are on sandbox or live