{
  "openapi": "3.0.0",
  "info": {
    "title": "ClinicBond Partner API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.clinicbond.com/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from Settings → API"
      }
    }
  },
  "paths": {
    "/patients": {
      "get": {
        "tags": [
          "Patients"
        ],
        "summary": "List patients (role user only), newest first.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "default 1"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "default 50, max 100"
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "matches first/last name or email"
          },
          {
            "name": "externalRef",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "exact match on your system’s id"
          },
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO-8601 — records changed since"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated patient objects"
          }
        }
      },
      "post": {
        "tags": [
          "Patients"
        ],
        "summary": "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.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "description": "required"
                  },
                  "lastName": {
                    "description": "required"
                  },
                  "email": {
                    "description": "required"
                  },
                  "phone": {
                    "description": "optional"
                  },
                  "dateOfBirth": {
                    "description": "optional ISO date"
                  },
                  "externalRef": {
                    "description": "optional — your system’s id, unique per clinic"
                  },
                  "isActivePatient": {
                    "description": "optional boolean"
                  },
                  "address": {
                    "description": "{ street, city, state, zipCode, apartment?, label? }"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201 with the patient object"
          }
        }
      }
    },
    "/patients/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Patients"
        ],
        "summary": "One patient by our id — or by YOUR id using the form ext:<externalRef>.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Patient object"
          }
        }
      },
      "patch": {
        "tags": [
          "Patients"
        ],
        "summary": "Partial update of the create fields. Setting address replaces the default address and keeps the rest.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated patient object"
          }
        }
      }
    },
    "/orders": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "List orders, newest first.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "filter by status"
          },
          {
            "name": "patientId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "filter by patient"
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO-8601 — created since"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated order objects"
          }
        }
      }
    },
    "/orders/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "One order.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Order object"
          }
        }
      },
      "patch": {
        "tags": [
          "Orders"
        ],
        "summary": "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.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "description": "optional — one of the allowed statuses"
                  },
                  "tracking": {
                    "description": "optional { trackingNumber, carrier? }"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated order object. Fires the order_status_changed webhook."
          }
        }
      }
    },
    "/subscriptions": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "List auto-refill enrollments.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "active|paused|canceled|payment_failed|needs_approval"
          },
          {
            "name": "patientId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated subscription objects"
          }
        }
      }
    },
    "/subscriptions/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "One subscription.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription object"
          }
        }
      }
    },
    "/subscriptions/{id}/pause": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Pause auto-refill. 409 if canceled.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated subscription"
          }
        }
      }
    },
    "/subscriptions/{id}/resume": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "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.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated subscription"
          }
        }
      }
    },
    "/subscriptions/{id}/cancel": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Cancel permanently.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "description": "optional string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated subscription"
          }
        }
      }
    },
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "The clinic’s catalog with variant strengths and pricing — use it to map your own item ids.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "true (default) | false"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated product objects"
          }
        }
      }
    },
    "/messages": {
      "get": {
        "tags": [
          "Messages"
        ],
        "summary": "One patient’s thread, oldest first.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "patientId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "required"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": ""
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated message objects"
          }
        }
      },
      "post": {
        "tags": [
          "Messages"
        ],
        "summary": "Send a message that appears instantly in the patient’s app chat. Sender shows as the API key’s name.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "patientId": {
                    "description": "required"
                  },
                  "body": {
                    "description": "required, max 4000 chars"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201 { id, createdAt }"
          }
        }
      }
    },
    "/webhooks/events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "The event catalog and signing contract.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "{ data: [{ event }], signing }"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Your API-created subscriptions.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Array of webhook objects"
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "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).",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "description": "required — from the catalog"
                  },
                  "targetUrl": {
                    "description": "required https URL"
                  },
                  "secret": {
                    "description": "recommended — up to 128 chars"
                  },
                  "pharmacyId": {
                    "description": "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."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201 webhook object"
          }
        }
      }
    },
    "/webhooks/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Remove a subscription.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "{ success: true }"
          }
        }
      }
    }
  }
}
