Developers · Partner API v1.0.0

ClinicBond Partner API reference

A server-to-server REST API with signed webhooks, for connecting a clinic's own systems (pharmacy software, ERPs, fulfillment, CRMs) to its ClinicBond patient app and dashboard. This page is built from the same definitions the API checks requests against.

Base URLhttps://api.clinicbond.com/api/v1

Overview

The API reads and updates a clinic's patients, orders, auto-refill subscriptions, product catalog and patient messages, and sends events to your server as they happen. Every request is made with an API key that belongs to one clinic, and sees only that clinic's records.

  • Requests and responses are JSON over HTTPS.
  • API access is included from the Growth plan. A clinic owner or admin creates keys in the dashboard under Settings, API.
  • The machine-readable spec is at clinicbond.com/developers/openapi.json, ready to import into Postman, Insomnia or Swagger.
Your first request
curl "https://api.clinicbond.com/api/v1/patients?limit=1" \
  -H "Authorization: Bearer $API_KEY"

Authentication

API key (Bearer). Send the key in the Authorization header of every request:

Header
Authorization: Bearer hlpk_live_…
  • Create keys in Admin → Settings → API. The key is shown once; we store only a hash.
  • Each key carries explicit scopes — grant only what the integration needs.
  • Revocation is immediate.
  • A key can be bound to one of the clinic's pharmacies (Settings → API, Bind to pharmacy). A bound key sees only orders that are paid and cleared to fill with a line that pharmacy fills, only those lines (no prices or amounts), and the patient's name, phone and shipping address; it takes only orders:read, orders:write and webhooks:manage, and its webhooks are filtered to its pharmacy. On an order another pharmacy also fills, it can add tracking (recorded as its parcel) but not change the status (409 shared_order).

Keep keys on your server. Never put a key in a browser, a mobile app or a public repository. If a key leaks, revoke it in Settings, API and create a new one.

Scopes

Each key carries the scopes picked when it was created. A request to an endpoint whose scope the key lacks answers 403 with the missing scope named.

Rate limits

Requests are counted per API key, in the window shown for the clinic's plan. Treat the number as the most you should send: past it, the API answers 429 with the error rate_limited (see Errors) until the window resets.

Responses carry the standard RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, so you can slow down before you reach the limit. A 429 also carries Retry-After, in seconds.

PlanLimit
Trial50 requests / 15 minutes
Starter200 requests / 15 minutes
Growth1000 requests / 15 minutes
Signature5000 requests / 15 minutes

Conventions

TopicRule
Pagination?page=1&limit=50 (max 100) → { data, pagination: { page, limit, total, pages } }
TimestampsISO-8601 UTC
IdempotencyPATCH endpoints are safe to retry; webhook POST upserts on (event, targetUrl)

Errors

Errors from the API's endpoints use one envelope: { success: false, error: "<machine_code>", message: "<human text>" } — codes: unauthorized, missing_scope, validation, invalid_id, not_found, duplicate, conflict, account_inactive, server_error, and for pharmacy-bound keys pharmacy_key, pharmacy_removed, shared_order, acknowledgment_required

Example error404 Not Found
{
  "success": false,
  "error": "not_found",
  "message": "Patient not found"
}

Branch on error, not on message, and allow for codes you have not seen: an endpoint's description can name others (for example needs_review on resuming a subscription). Some errors add a field. A 403 for a missing scope names it in requiredScope, and some 400 and 409 answers add a code that says more about the cause.

The rate limit answers in the same envelope, with the error rate_limited and retryAfter, the seconds until the key's window resets:

Rate limited429 Too Many Requests
{
  "success": false,
  "error": "rate_limited",
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 450
}

Status codes

CodeMeaning
400Bad request — the error names the field
401Missing, invalid, or revoked API key
403Key lacks the required scope (named in the response) or account inactive
404Not found within your clinic
409Duplicate or conflicting state
429Rate limit exceeded
500Our fault — retry with backoff

Events and webhooks

Subscribe an https endpoint to any event with POST /webhooks (scope webhooks:manage). HTTP POST, JSON, 10s timeout. Repeated failures deactivate the subscription.

Events

injection_missedstreak_brokenorder_status_changedachievement_unlockedreward_earnedprovider_review_flaggedorder_createdpatient_createdmessage_receivedorder_updatedtreatment_schedule_changeddose_logged_late

Delivery body

Envelope
{ trigger, timestamp, locationId, clinic, data }

message_received deliberately excludes the message body (PHI) — fetch it via GET /api/v1/messages. order_updated: the clinic changed the lines of an order that was already cleared to fill. A subscription filtered to a pharmacy gets that pharmacy's new lines while the order stays cleared, or only { orderId, orderNumber, held: true } when the order went back to prescriber review, or { orderId, orderNumber, linesRemoved: true } when it no longer has lines for that pharmacy. Hold the fill until the order is cleared again. Order events: items on a dose priced by formula carry formulaId and formulaName only; a subscription filtered to a pharmacy (pharmacyId) gets that pharmacy's lines as the partner API gives a pharmacy-bound key, built from the order once it is cleared to fill: the dose, and the formula keys with the formula a prescriber confirmed.

Verifying signatures

A subscription created with a secret signs every delivery. The X-Portal-Signature header carries sha256=HEX(HMAC_SHA256(secret, rawRequestBody)). Check it against the raw request body before you trust a delivery:

Node.js
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-portal-signature'] || ''));

Patients

Scopes: patients:read patients:write

GET /api/v1/patients patients:read

List patients (role user only), newest first.

Query parameters

ParameterNotes
pagedefault 1
limitdefault 50, max 100
searchmatches first/last name or email
externalRefexact match on your system’s id
updatedSinceISO-8601 — records changed since

Returns Paginated patient objects

Example request
curl "https://api.clinicbond.com/api/v1/patients?limit=20&updatedSince=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "id": "665000000000000000000001",
      "externalRef": "YOUR-ID-1001",
      "firstName": "Test",
      "lastName": "Patient",
      "email": "test.patient@example.com",
      "phone": "+15555550100",
      "dateOfBirth": "1990-01-01T00:00:00.000Z",
      "isActivePatient": true,
      "addresses": [
        {
          "label": "Home",
          "street": "100 Example Street",
          "apartment": "Suite 1",
          "city": "Exampleville",
          "state": "CA",
          "zipCode": "90000",
          "country": "USA",
          "isDefault": true
        }
      ],
      "createdAt": "2026-01-15T17:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}
GET /api/v1/patients/:id patients:read

One patient by our id — or by YOUR id using the form ext:<externalRef>.

Returns Patient object

Example request
curl "https://api.clinicbond.com/api/v1/patients/ext:YOUR-ID-1001" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000001",
    "externalRef": "YOUR-ID-1001",
    "firstName": "Test",
    "lastName": "Patient",
    "email": "test.patient@example.com",
    "phone": "+15555550100",
    "dateOfBirth": "1990-01-01T00:00:00.000Z",
    "isActivePatient": true,
    "addresses": [
      {
        "label": "Home",
        "street": "100 Example Street",
        "apartment": "Suite 1",
        "city": "Exampleville",
        "state": "CA",
        "zipCode": "90000",
        "country": "USA",
        "isDefault": true
      }
    ],
    "createdAt": "2026-01-15T17:30:00.000Z"
  }
}
POST /api/v1/patients patients:write

Create a patient. Arrives unclaimed (no password) — they claim the account from the clinic’s invite flow. 409 on duplicate email or externalRef within your clinic.

Request body (JSON)

FieldNotes
firstNamerequired
lastNamerequired
emailrequired
phoneoptional
dateOfBirthoptional ISO date
externalRefoptional — your system’s id, unique per clinic
isActivePatientoptional boolean
address{ street, city, state, zipCode, apartment?, label? }

Returns 201 with the patient object

Example request
curl -X POST "https://api.clinicbond.com/api/v1/patients" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test",
    "lastName": "Patient",
    "email": "test.patient@example.com",
    "phone": "+15555550100",
    "externalRef": "YOUR-ID-1001",
    "address": {
      "street": "100 Example Street",
      "city": "Exampleville",
      "state": "CA",
      "zipCode": "90000"
    }
  }'
Example response201 Created
{
  "success": true,
  "data": {
    "id": "665000000000000000000001",
    "externalRef": "YOUR-ID-1001",
    "firstName": "Test",
    "lastName": "Patient",
    "email": "test.patient@example.com",
    "phone": "+15555550100",
    "dateOfBirth": "1990-01-01T00:00:00.000Z",
    "isActivePatient": true,
    "addresses": [
      {
        "label": "Home",
        "street": "100 Example Street",
        "apartment": "Suite 1",
        "city": "Exampleville",
        "state": "CA",
        "zipCode": "90000",
        "country": "USA",
        "isDefault": true
      }
    ],
    "createdAt": "2026-01-15T17:30:00.000Z"
  }
}
PATCH /api/v1/patients/:id patients:write

Partial update of the create fields. Setting address replaces the default address and keeps the rest.

Returns Updated patient object

Example request
curl -X PATCH "https://api.clinicbond.com/api/v1/patients/665000000000000000000001" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15555550199"
  }'
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000001",
    "externalRef": "YOUR-ID-1001",
    "firstName": "Test",
    "lastName": "Patient",
    "email": "test.patient@example.com",
    "phone": "+15555550100",
    "dateOfBirth": "1990-01-01T00:00:00.000Z",
    "isActivePatient": true,
    "addresses": [
      {
        "label": "Home",
        "street": "100 Example Street",
        "apartment": "Suite 1",
        "city": "Exampleville",
        "state": "CA",
        "zipCode": "90000",
        "country": "USA",
        "isDefault": true
      }
    ],
    "createdAt": "2026-01-15T17:30:00.000Z"
  }
}

The patient object

FieldType and notes
idstring
externalRefstring|null
firstNamestring
lastNamestring
emailstring
phonestring|null
dateOfBirthISO date|null
isActivePatientboolean
addressesarray of { label, street, apartment, city, state, zipCode, country, isDefault }
createdAtISO datetime
Example patient
{
  "id": "665000000000000000000001",
  "externalRef": "YOUR-ID-1001",
  "firstName": "Test",
  "lastName": "Patient",
  "email": "test.patient@example.com",
  "phone": "+15555550100",
  "dateOfBirth": "1990-01-01T00:00:00.000Z",
  "isActivePatient": true,
  "addresses": [
    {
      "label": "Home",
      "street": "100 Example Street",
      "apartment": "Suite 1",
      "city": "Exampleville",
      "state": "CA",
      "zipCode": "90000",
      "country": "USA",
      "isDefault": true
    }
  ],
  "createdAt": "2026-01-15T17:30:00.000Z"
}

Orders

Scopes: orders:read orders:write

GET /api/v1/orders orders:read

List orders, newest first.

Query parameters

ParameterNotes
pageNo notes
limitNo notes
statusfilter by status
patientIdfilter by patient
sinceISO-8601 — created since

Returns Paginated order objects

Example request
curl "https://api.clinicbond.com/api/v1/orders?status=processing&since=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "id": "665000000000000000000101",
      "orderNumber": "2601-EXAMPL",
      "patientId": "665000000000000000000001",
      "status": "shipped",
      "paymentStatus": "paid",
      "totalAmount": 199,
      "finalAmount": 199,
      "source": "checkout",
      "items": [
        {
          "productId": "665000000000000000000201",
          "name": "Example Product",
          "quantity": 1,
          "price": 199,
          "variantId": "665000000000000000000202",
          "variant": {
            "name": "Monthly",
            "dosage": null
          }
        }
      ],
      "shippingAddress": {
        "street": "100 Example Street",
        "apartment": "Suite 1",
        "city": "Exampleville",
        "state": "CA",
        "zipCode": "90000",
        "country": "USA"
      },
      "tracking": {
        "carrier": "USPS",
        "trackingNumber": "9400000000000000000000",
        "trackingUrl": null,
        "estimatedDelivery": null
      },
      "shippedAt": "2026-01-17T15:00:00.000Z",
      "deliveredAt": null,
      "createdAt": "2026-01-16T09:12:00.000Z",
      "updatedAt": "2026-01-17T15:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}
GET /api/v1/orders/:id orders:read

One order.

Returns Order object

Example request
curl "https://api.clinicbond.com/api/v1/orders/665000000000000000000101" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000101",
    "orderNumber": "2601-EXAMPL",
    "patientId": "665000000000000000000001",
    "status": "shipped",
    "paymentStatus": "paid",
    "totalAmount": 199,
    "finalAmount": 199,
    "source": "checkout",
    "items": [
      {
        "productId": "665000000000000000000201",
        "name": "Example Product",
        "quantity": 1,
        "price": 199,
        "variantId": "665000000000000000000202",
        "variant": {
          "name": "Monthly",
          "dosage": null
        }
      }
    ],
    "shippingAddress": {
      "street": "100 Example Street",
      "apartment": "Suite 1",
      "city": "Exampleville",
      "state": "CA",
      "zipCode": "90000",
      "country": "USA"
    },
    "tracking": {
      "carrier": "USPS",
      "trackingNumber": "9400000000000000000000",
      "trackingUrl": null,
      "estimatedDelivery": null
    },
    "shippedAt": "2026-01-17T15:00:00.000Z",
    "deliveredAt": null,
    "createdAt": "2026-01-16T09:12:00.000Z",
    "updatedAt": "2026-01-17T15:00:00.000Z"
  }
}
PATCH /api/v1/orders/:id orders:write

Advance fulfillment and/or attach tracking. Allowed statuses: processing, approved, shipped, in_transit, out_for_delivery, delivered. Setting a tracking number with no status auto-advances a pre-shipment order to shipped, and registers carrier tracking so the order keeps updating itself. Refunds and cancellations are deliberately NOT available by API. An order with a formula line no prescriber has confirmed cannot be set to approved (400 use_prescriber_review): a prescriber approves it on review.

Request body (JSON)

FieldNotes
statusoptional — one of the allowed statuses
trackingoptional { trackingNumber, carrier? }

Returns Updated order object. Fires the order_status_changed webhook.

Example request
curl -X PATCH "https://api.clinicbond.com/api/v1/orders/665000000000000000000101" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "tracking": {
      "trackingNumber": "9400000000000000000000",
      "carrier": "USPS"
    }
  }'
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000101",
    "orderNumber": "2601-EXAMPL",
    "patientId": "665000000000000000000001",
    "status": "shipped",
    "paymentStatus": "paid",
    "totalAmount": 199,
    "finalAmount": 199,
    "source": "checkout",
    "items": [
      {
        "productId": "665000000000000000000201",
        "name": "Example Product",
        "quantity": 1,
        "price": 199,
        "variantId": "665000000000000000000202",
        "variant": {
          "name": "Monthly",
          "dosage": null
        }
      }
    ],
    "shippingAddress": {
      "street": "100 Example Street",
      "apartment": "Suite 1",
      "city": "Exampleville",
      "state": "CA",
      "zipCode": "90000",
      "country": "USA"
    },
    "tracking": {
      "carrier": "USPS",
      "trackingNumber": "9400000000000000000000",
      "trackingUrl": null,
      "estimatedDelivery": null
    },
    "shippedAt": "2026-01-17T15:00:00.000Z",
    "deliveredAt": null,
    "createdAt": "2026-01-16T09:12:00.000Z",
    "updatedAt": "2026-01-17T15:00:00.000Z"
  }
}

The order object

FieldType and notes
idstring
orderNumberstring
patientIdstring
statusstring
paymentStatusstring
totalAmountnumber
finalAmountnumber
sourcecheckout|subscription|admin|reorder
itemsarray of { productId, name, quantity, price, variantId, variant, pharmacyId?, pharmacyName?, formulaId?, formulaName?, formulaIngredients?, formulaLabel?, productCode?, concentrationMgPerMl?, fillMl?, formulaConfirmedAt? } (pharmacyId and pharmacyName on lines a pharmacy fills, when the clinic uses pharmacy choice). On a dose the clinic prices by formula (how the dose is compounded, named by its added ingredient), a line also carries formulaId, formulaName (the patient-facing name), formulaIngredients (added ingredients by chemical name), formulaLabel (the pharmacy's own label text), productCode (the pharmacy's own code), concentrationMgPerMl and fillMl (null when not on file), and formulaConfirmedAt: when a prescriber confirmed the formula (null until then; fill only a confirmed formula). A pharmacy-bound key sees an order only once every formula line on it is confirmed.
shippingAddressobject|null
tracking{ carrier, trackingNumber, trackingUrl, estimatedDelivery }|null
shippedAtISO datetime|null
deliveredAtISO datetime|null
createdAtISO datetime
updatedAtISO datetime
Example order
{
  "id": "665000000000000000000101",
  "orderNumber": "2601-EXAMPL",
  "patientId": "665000000000000000000001",
  "status": "shipped",
  "paymentStatus": "paid",
  "totalAmount": 199,
  "finalAmount": 199,
  "source": "checkout",
  "items": [
    {
      "productId": "665000000000000000000201",
      "name": "Example Product",
      "quantity": 1,
      "price": 199,
      "variantId": "665000000000000000000202",
      "variant": {
        "name": "Monthly",
        "dosage": null
      }
    }
  ],
  "shippingAddress": {
    "street": "100 Example Street",
    "apartment": "Suite 1",
    "city": "Exampleville",
    "state": "CA",
    "zipCode": "90000",
    "country": "USA"
  },
  "tracking": {
    "carrier": "USPS",
    "trackingNumber": "9400000000000000000000",
    "trackingUrl": null,
    "estimatedDelivery": null
  },
  "shippedAt": "2026-01-17T15:00:00.000Z",
  "deliveredAt": null,
  "createdAt": "2026-01-16T09:12:00.000Z",
  "updatedAt": "2026-01-17T15:00:00.000Z"
}

Subscriptions

Scopes: subscriptions:read subscriptions:write

GET /api/v1/subscriptions subscriptions:read

List auto-refill enrollments.

Query parameters

ParameterNotes
pageNo notes
limitNo notes
statusactive|paused|canceled|payment_failed|needs_approval
patientIdNo notes

Returns Paginated subscription objects

Example request
curl "https://api.clinicbond.com/api/v1/subscriptions?status=active&patientId=665000000000000000000001" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "id": "665000000000000000000301",
      "patientId": "665000000000000000000001",
      "productId": "665000000000000000000201",
      "productName": "Example Product",
      "variant": {
        "name": "Monthly",
        "price": 199
      },
      "status": "active",
      "intervalDays": 30,
      "nextChargeAt": "2026-02-15T17:30:00.000Z",
      "lastChargedAt": "2026-01-16T09:12:00.000Z",
      "cyclesCompleted": 1,
      "createdAt": "2026-01-16T09:12:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}
GET /api/v1/subscriptions/:id subscriptions:read

One subscription.

Returns Subscription object

Example request
curl "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000301",
    "patientId": "665000000000000000000001",
    "productId": "665000000000000000000201",
    "productName": "Example Product",
    "variant": {
      "name": "Monthly",
      "price": 199
    },
    "status": "active",
    "intervalDays": 30,
    "nextChargeAt": "2026-02-15T17:30:00.000Z",
    "lastChargedAt": "2026-01-16T09:12:00.000Z",
    "cyclesCompleted": 1,
    "createdAt": "2026-01-16T09:12:00.000Z"
  }
}
POST /api/v1/subscriptions/:id/pause subscriptions:write

Pause auto-refill. 409 if canceled.

Returns Updated subscription

Example request
curl -X POST "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301/pause" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000301",
    "patientId": "665000000000000000000001",
    "productId": "665000000000000000000201",
    "productName": "Example Product",
    "variant": {
      "name": "Monthly",
      "price": 199
    },
    "status": "paused",
    "intervalDays": 30,
    "nextChargeAt": "2026-02-15T17:30:00.000Z",
    "lastChargedAt": "2026-01-16T09:12:00.000Z",
    "cyclesCompleted": 1,
    "createdAt": "2026-01-16T09:12:00.000Z"
  }
}
POST /api/v1/subscriptions/:id/resume subscriptions:write

Resume; a past-due next charge moves to tomorrow. A refill held for clinical review answers 409 needs_review: the clinic releases it from the dashboard.

Returns Updated subscription

Example request
curl -X POST "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301/resume" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000301",
    "patientId": "665000000000000000000001",
    "productId": "665000000000000000000201",
    "productName": "Example Product",
    "variant": {
      "name": "Monthly",
      "price": 199
    },
    "status": "active",
    "intervalDays": 30,
    "nextChargeAt": "2026-02-15T17:30:00.000Z",
    "lastChargedAt": "2026-01-16T09:12:00.000Z",
    "cyclesCompleted": 1,
    "createdAt": "2026-01-16T09:12:00.000Z"
  }
}
POST /api/v1/subscriptions/:id/cancel subscriptions:write

Cancel permanently.

Request body (JSON)

FieldNotes
reasonoptional string

Returns Updated subscription

Example request
curl -X POST "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301/cancel" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Test cancellation"
  }'
Example response200 OK
{
  "success": true,
  "data": {
    "id": "665000000000000000000301",
    "patientId": "665000000000000000000001",
    "productId": "665000000000000000000201",
    "productName": "Example Product",
    "variant": {
      "name": "Monthly",
      "price": 199
    },
    "status": "canceled",
    "intervalDays": 30,
    "nextChargeAt": "2026-02-15T17:30:00.000Z",
    "lastChargedAt": "2026-01-16T09:12:00.000Z",
    "cyclesCompleted": 1,
    "createdAt": "2026-01-16T09:12:00.000Z"
  }
}

The subscription object

FieldType and notes
idstring
patientIdstring
productIdstring
productNamestring
variant{ name, price }|null
statusstring
intervalDaysnumber
nextChargeAtISO datetime
lastChargedAtISO datetime|null
cyclesCompletednumber
createdAtISO datetime
Example subscription
{
  "id": "665000000000000000000301",
  "patientId": "665000000000000000000001",
  "productId": "665000000000000000000201",
  "productName": "Example Product",
  "variant": {
    "name": "Monthly",
    "price": 199
  },
  "status": "active",
  "intervalDays": 30,
  "nextChargeAt": "2026-02-15T17:30:00.000Z",
  "lastChargedAt": "2026-01-16T09:12:00.000Z",
  "cyclesCompleted": 1,
  "createdAt": "2026-01-16T09:12:00.000Z"
}

Products

Scopes: products:read

GET /api/v1/products products:read

The clinic’s catalog with variant strengths and pricing — use it to map your own item ids.

Query parameters

ParameterNotes
pageNo notes
limitNo notes
activetrue (default) | false

Returns Paginated product objects

Example request
curl "https://api.clinicbond.com/api/v1/products?active=true" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "id": "665000000000000000000201",
      "name": "Example Product",
      "isActive": true,
      "requiresPrescription": true,
      "medicationType": null,
      "variants": [
        {
          "id": "665000000000000000000202",
          "name": "Monthly",
          "price": 199,
          "dosage": null,
          "supplyLength": 4,
          "supplyLengthUnit": "weeks"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}

The product object

FieldType and notes
idstring
namestring
isActiveboolean
requiresPrescriptionboolean
medicationTypestring|null
variantsarray of { id, name, price, dosage: { amount, unit }|null, supplyLength, supplyLengthUnit }
Example product
{
  "id": "665000000000000000000201",
  "name": "Example Product",
  "isActive": true,
  "requiresPrescription": true,
  "medicationType": null,
  "variants": [
    {
      "id": "665000000000000000000202",
      "name": "Monthly",
      "price": 199,
      "dosage": null,
      "supplyLength": 4,
      "supplyLengthUnit": "weeks"
    }
  ]
}

Messages

Scopes: messages:read messages:write

GET /api/v1/messages messages:read

One patient’s thread, oldest first.

Query parameters

ParameterNotes
patientIdrequired
pageNo notes
limitNo notes

Returns Paginated message objects

Example request
curl "https://api.clinicbond.com/api/v1/messages?patientId=665000000000000000000001" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "id": "665000000000000000000401",
      "direction": "inbound",
      "body": "Hi, this is a test message.",
      "senderName": "Test Patient",
      "senderType": "patient",
      "createdAt": "2026-01-18T10:05:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}
POST /api/v1/messages messages:write

Send a message that appears instantly in the patient’s app chat. Sender shows as the API key’s name.

Request body (JSON)

FieldNotes
patientIdrequired
bodyrequired, max 4000 chars

Returns 201 { id, createdAt }

Example request
curl -X POST "https://api.clinicbond.com/api/v1/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "665000000000000000000001",
    "body": "Your order has shipped. Tracking is in the app."
  }'
Example response201 Created
{
  "success": true,
  "data": {
    "id": "665000000000000000000402",
    "createdAt": "2026-01-18T10:06:00.000Z"
  }
}

The message object

FieldType and notes
idstring
directioninbound (from patient) | outbound (to patient)
bodystring
senderNamestring|null
senderTypepatient|agent|system|bot
createdAtISO datetime
Example message
{
  "id": "665000000000000000000401",
  "direction": "inbound",
  "body": "Hi, this is a test message.",
  "senderName": "Test Patient",
  "senderType": "patient",
  "createdAt": "2026-01-18T10:05:00.000Z"
}

Webhooks

Scopes: webhooks:manage

GET /api/v1/webhooks/events (any valid key)

The event catalog and signing contract.

Returns { data: [{ event }], signing }

Example request
curl "https://api.clinicbond.com/api/v1/webhooks/events" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "event": "injection_missed"
    },
    {
      "event": "streak_broken"
    },
    {
      "event": "order_status_changed"
    },
    {
      "event": "achievement_unlocked"
    },
    {
      "event": "reward_earned"
    },
    {
      "event": "provider_review_flagged"
    },
    {
      "event": "order_created"
    },
    {
      "event": "patient_created"
    },
    {
      "event": "message_received"
    },
    {
      "event": "order_updated"
    },
    {
      "event": "treatment_schedule_changed"
    },
    {
      "event": "dose_logged_late"
    }
  ],
  "signing": {
    "header": "X-Portal-Signature",
    "algorithm": "HMAC-SHA256 over the raw request body, hex encoded, prefixed \"sha256=\"",
    "note": "Set a secret when subscribing; deliveries without a secret are unsigned"
  }
}
GET /api/v1/webhooks webhooks:manage

Your API-created subscriptions.

Returns Array of webhook objects

Example request
curl "https://api.clinicbond.com/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true,
  "data": [
    {
      "id": "665000000000000000000501",
      "event": "order_status_changed",
      "targetUrl": "https://hooks.example.com/clinic-events",
      "active": true,
      "hasSecret": true,
      "lastDeliveryAt": "2026-01-17T15:00:01.000Z",
      "lastErrorAt": null
    }
  ]
}
POST /api/v1/webhooks webhooks:manage

Subscribe an https endpoint to an event. Provide a secret and every delivery is HMAC-signed. Re-posting the same event+url updates it (idempotent).

Request body (JSON)

FieldNotes
eventrequired — from the catalog
targetUrlrequired https URL
secretrecommended — up to 128 chars
pharmacyIdoptional: order events only for orders with a line this pharmacy fills, carrying only those lines, once the order is cleared to fill; needs a clinic admin's confirmation in Settings → API (409 acknowledgment_required). Implied for a pharmacy-bound key. Never converts the clinic's other subscription to the same event and URL (409 conflict); re-posting a filtered subscription without it keeps the filter (delete the subscription to remove it). Revoking the key that set it up, or the clinic deleting the pharmacy, removes it.

Returns 201 webhook object

Example request
curl -X POST "https://api.clinicbond.com/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order_status_changed",
    "targetUrl": "https://hooks.example.com/clinic-events",
    "secret": "replace-with-a-long-random-string"
  }'
Example response201 Created
{
  "success": true,
  "data": {
    "id": "665000000000000000000501",
    "event": "order_status_changed",
    "targetUrl": "https://hooks.example.com/clinic-events",
    "active": true,
    "hasSecret": true,
    "lastDeliveryAt": null,
    "lastErrorAt": null
  }
}
DELETE /api/v1/webhooks/:id webhooks:manage

Remove a subscription.

Returns { success: true }

Example request
curl -X DELETE "https://api.clinicbond.com/api/v1/webhooks/665000000000000000000501" \
  -H "Authorization: Bearer $API_KEY"
Example response200 OK
{
  "success": true
}

The webhook object

FieldType and notes
idstring
eventstring
targetUrlstring
activeboolean
hasSecretboolean
lastDeliveryAtISO datetime|null
lastErrorAtISO datetime|null
pharmacyIdstring (only on a subscription filtered to one pharmacy)
Example webhook
{
  "id": "665000000000000000000501",
  "event": "order_status_changed",
  "targetUrl": "https://hooks.example.com/clinic-events",
  "active": true,
  "hasSecret": true,
  "lastDeliveryAt": "2026-01-17T15:00:01.000Z",
  "lastErrorAt": null
}

OpenAPI spec

The same reference as an OpenAPI 3 document, generated from the same source as this page. Import it into Postman, Insomnia or Swagger to try the endpoints with your key.

Need a scope or an event that is not here?

Tell us what your integration needs at support@hlpatientportal.com.

Book a demo