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.
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:
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.
| Scope | Endpoints |
|---|---|
patients:read | GET /patients GET /patients/:id |
patients:write | POST /patients PATCH /patients/:id |
orders:read | GET /orders GET /orders/:id |
orders:write | PATCH /orders/:id |
subscriptions:read | GET /subscriptions GET /subscriptions/:id |
subscriptions:write | POST /subscriptions/:id/pause POST /subscriptions/:id/resume POST /subscriptions/:id/cancel |
products:read | GET /products |
messages:read | GET /messages |
messages:write | POST /messages |
webhooks:manage | GET /webhooks POST /webhooks DELETE /webhooks/:id |
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.
| Plan | Limit |
|---|---|
Trial | 50 requests / 15 minutes |
Starter | 200 requests / 15 minutes |
Growth | 1000 requests / 15 minutes |
Signature | 5000 requests / 15 minutes |
Conventions
| Topic | Rule |
|---|---|
Pagination | ?page=1&limit=50 (max 100) → { data, pagination: { page, limit, total, pages } } |
Timestamps | ISO-8601 UTC |
Idempotency | PATCH 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
{
"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:
{
"success": false,
"error": "rate_limited",
"message": "Rate limit exceeded. Please try again later.",
"retryAfter": 450
}
Status codes
| Code | Meaning |
|---|---|
400 | Bad request — the error names the field |
401 | Missing, invalid, or revoked API key |
403 | Key lacks the required scope (named in the response) or account inactive |
404 | Not found within your clinic |
409 | Duplicate or conflicting state |
429 | Rate limit exceeded |
500 | Our 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_lateDelivery body
{ 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:
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
/api/v1/patients
patients:read
List patients (role user only), newest first.
Query parameters
| Parameter | Notes |
|---|---|
page | default 1 |
limit | default 50, max 100 |
search | matches first/last name or email |
externalRef | exact match on your system’s id |
updatedSince | ISO-8601 — records changed since |
Returns Paginated patient objects
curl "https://api.clinicbond.com/api/v1/patients?limit=20&updatedSince=2026-01-01T00:00:00Z" \
-H "Authorization: Bearer $API_KEY"
{
"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
}
}
/api/v1/patients/:id
patients:read
One patient by our id — or by YOUR id using the form ext:<externalRef>.
Returns Patient object
curl "https://api.clinicbond.com/api/v1/patients/ext:YOUR-ID-1001" \
-H "Authorization: Bearer $API_KEY"
{
"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"
}
}
/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)
| Field | Notes |
|---|---|
firstName | required |
lastName | required |
email | required |
phone | optional |
dateOfBirth | optional ISO date |
externalRef | optional — your system’s id, unique per clinic |
isActivePatient | optional boolean |
address | { street, city, state, zipCode, apartment?, label? } |
Returns 201 with the patient object
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"
}
}'
{
"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"
}
}
/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
curl -X PATCH "https://api.clinicbond.com/api/v1/patients/665000000000000000000001" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15555550199"
}'
{
"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
| Field | Type and notes |
|---|---|
id | string |
externalRef | string|null |
firstName | string |
lastName | string |
email | string |
phone | string|null |
dateOfBirth | ISO date|null |
isActivePatient | boolean |
addresses | array of { label, street, apartment, city, state, zipCode, country, isDefault } |
createdAt | ISO datetime |
{
"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
/api/v1/orders
orders:read
List orders, newest first.
Query parameters
| Parameter | Notes |
|---|---|
page | No notes |
limit | No notes |
status | filter by status |
patientId | filter by patient |
since | ISO-8601 — created since |
Returns Paginated order objects
curl "https://api.clinicbond.com/api/v1/orders?status=processing&since=2026-01-01T00:00:00Z" \
-H "Authorization: Bearer $API_KEY"
{
"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
}
}
/api/v1/orders/:id
orders:read
One order.
Returns Order object
curl "https://api.clinicbond.com/api/v1/orders/665000000000000000000101" \
-H "Authorization: Bearer $API_KEY"
{
"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"
}
}
/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)
| Field | Notes |
|---|---|
status | optional — one of the allowed statuses |
tracking | optional { trackingNumber, carrier? } |
Returns Updated order object. Fires the order_status_changed webhook.
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"
}
}'
{
"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
| Field | Type and notes |
|---|---|
id | string |
orderNumber | string |
patientId | string |
status | string |
paymentStatus | string |
totalAmount | number |
finalAmount | number |
source | checkout|subscription|admin|reorder |
items | array 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. |
shippingAddress | object|null |
tracking | { carrier, trackingNumber, trackingUrl, estimatedDelivery }|null |
shippedAt | ISO datetime|null |
deliveredAt | ISO datetime|null |
createdAt | ISO datetime |
updatedAt | ISO datetime |
{
"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
/api/v1/subscriptions
subscriptions:read
List auto-refill enrollments.
Query parameters
| Parameter | Notes |
|---|---|
page | No notes |
limit | No notes |
status | active|paused|canceled|payment_failed|needs_approval |
patientId | No notes |
Returns Paginated subscription objects
curl "https://api.clinicbond.com/api/v1/subscriptions?status=active&patientId=665000000000000000000001" \
-H "Authorization: Bearer $API_KEY"
{
"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
}
}
/api/v1/subscriptions/:id
subscriptions:read
One subscription.
Returns Subscription object
curl "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301" \
-H "Authorization: Bearer $API_KEY"
{
"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"
}
}
/api/v1/subscriptions/:id/pause
subscriptions:write
Pause auto-refill. 409 if canceled.
Returns Updated subscription
curl -X POST "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301/pause" \
-H "Authorization: Bearer $API_KEY"
{
"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"
}
}
/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
curl -X POST "https://api.clinicbond.com/api/v1/subscriptions/665000000000000000000301/resume" \
-H "Authorization: Bearer $API_KEY"
{
"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"
}
}
/api/v1/subscriptions/:id/cancel
subscriptions:write
Cancel permanently.
Request body (JSON)
| Field | Notes |
|---|---|
reason | optional string |
Returns Updated subscription
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"
}'
{
"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
| Field | Type and notes |
|---|---|
id | string |
patientId | string |
productId | string |
productName | string |
variant | { name, price }|null |
status | string |
intervalDays | number |
nextChargeAt | ISO datetime |
lastChargedAt | ISO datetime|null |
cyclesCompleted | number |
createdAt | ISO datetime |
{
"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
/api/v1/products
products:read
The clinic’s catalog with variant strengths and pricing — use it to map your own item ids.
Query parameters
| Parameter | Notes |
|---|---|
page | No notes |
limit | No notes |
active | true (default) | false |
Returns Paginated product objects
curl "https://api.clinicbond.com/api/v1/products?active=true" \
-H "Authorization: Bearer $API_KEY"
{
"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
| Field | Type and notes |
|---|---|
id | string |
name | string |
isActive | boolean |
requiresPrescription | boolean |
medicationType | string|null |
variants | array of { id, name, price, dosage: { amount, unit }|null, supplyLength, supplyLengthUnit } |
{
"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
/api/v1/messages
messages:read
One patient’s thread, oldest first.
Query parameters
| Parameter | Notes |
|---|---|
patientId | required |
page | No notes |
limit | No notes |
Returns Paginated message objects
curl "https://api.clinicbond.com/api/v1/messages?patientId=665000000000000000000001" \
-H "Authorization: Bearer $API_KEY"
{
"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
}
}
/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)
| Field | Notes |
|---|---|
patientId | required |
body | required, max 4000 chars |
Returns 201 { id, createdAt }
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."
}'
{
"success": true,
"data": {
"id": "665000000000000000000402",
"createdAt": "2026-01-18T10:06:00.000Z"
}
}
The message object
| Field | Type and notes |
|---|---|
id | string |
direction | inbound (from patient) | outbound (to patient) |
body | string |
senderName | string|null |
senderType | patient|agent|system|bot |
createdAt | ISO datetime |
{
"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
/api/v1/webhooks/events
(any valid key)
The event catalog and signing contract.
Returns { data: [{ event }], signing }
curl "https://api.clinicbond.com/api/v1/webhooks/events" \
-H "Authorization: Bearer $API_KEY"
{
"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"
}
}
/api/v1/webhooks
webhooks:manage
Your API-created subscriptions.
Returns Array of webhook objects
curl "https://api.clinicbond.com/api/v1/webhooks" \
-H "Authorization: Bearer $API_KEY"
{
"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
}
]
}
/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)
| Field | Notes |
|---|---|
event | required — from the catalog |
targetUrl | required https URL |
secret | recommended — up to 128 chars |
pharmacyId | optional: 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
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"
}'
{
"success": true,
"data": {
"id": "665000000000000000000501",
"event": "order_status_changed",
"targetUrl": "https://hooks.example.com/clinic-events",
"active": true,
"hasSecret": true,
"lastDeliveryAt": null,
"lastErrorAt": null
}
}
/api/v1/webhooks/:id
webhooks:manage
Remove a subscription.
Returns { success: true }
curl -X DELETE "https://api.clinicbond.com/api/v1/webhooks/665000000000000000000501" \
-H "Authorization: Bearer $API_KEY"
{
"success": true
}
The webhook object
| Field | Type and notes |
|---|---|
id | string |
event | string |
targetUrl | string |
active | boolean |
hasSecret | boolean |
lastDeliveryAt | ISO datetime|null |
lastErrorAt | ISO datetime|null |
pharmacyId | string (only on a subscription filtered to one pharmacy) |
{
"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.
Tell us what your integration needs at support@hlpatientportal.com.