Developer Guide — QualifyBase API

The QualifyBase API gives clinics and partners programmatic access to leads, availability, appointment booking, and webhook events. It uses the same booking engine that powers the dashboard and AI agent, so external systems do not drift from the operational source of truth.

Quick Facts

Base URL	`/api/v1`, relative to your QualifyBase host
Authentication	Bearer token using a clinic-scoped `qbk_live_*` API key
Rate limit	120 requests per minute, per API key

Security Model

API keys are created inside the dashboard by an authenticated clinic user.
The full key is shown only once. QualifyBase stores a hash, not the raw key.
Each key is scoped to one clinic and cannot access another clinic's data.
Send keys only in the Authorization: Bearer header.
Do not put API keys in query strings, frontend code, analytics tools, or public repositories.

Quickstart

Create an API key in the dashboard under Setup → API keys.
Store the full qbk_live_... key in your server environment as QB_KEY.
Set your app URL as QB_HOST, then call the REST API from your backend.

# Check availability
curl -s "$QB_HOST/api/v1/availability?from=2026-04-26&preference=morning&limit=5" \
  -H "Authorization: Bearer $QB_KEY"

# Book an appointment
curl -s -X POST "$QB_HOST/api/v1/appointments" \
  -H "Authorization: Bearer $QB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "c3e8a1d4-...",
    "scheduled_at": "2026-04-26T09:00:00Z",
    "ends_at": "2026-04-26T09:30:00Z",
    "title": "Consultation"
  }'

What You Can Build

Lead sync: push web form leads into QualifyBase or pull qualified leads into your CRM.
Availability checks: show real clinic availability in an external app.
Appointment booking: create, reschedule, and cancel appointments from a custom workflow.
Webhook automation: receive appointment events in your CRM, Zapier, Make, or internal systems.

Core Endpoints

Method	Path	Purpose
`GET`	`/api/v1/leads`	List leads for the authenticated clinic.
`POST`	`/api/v1/leads`	Create or update a lead from an external source.
`GET`	`/api/v1/availability`	Find open appointment slots.
`POST`	`/api/v1/appointments`	Book an appointment for a lead.
`PATCH`	`/api/v1/appointments/:id`	Reschedule or update an appointment.

Webhooks

Webhooks notify your system when appointment events happen. Payloads should be verified on your server before you update external systems.

appointment.created
appointment.updated
appointment.cancelled

OpenAPI Spec

The machine-readable API contract is available at /api/v1/openapi.json. Import it into Postman, Insomnia, or an OpenAPI client generator.

What Is Not Public

Call recordings, full conversation transcripts, lead scoring internals, follow-up scheduling internals, agent configuration internals, billing, and cross-clinic data are not exposed as stable public API contracts.