Skip to main content
Welcome to the Switchbord API reference. Switchbord provides a stable Public REST API (v1) for workspace management, contact synchronization, and message dispatch, alongside specialized compatibility layers for legacy integrations.

​
Getting Started

The API is accessible at https://api.switchbord.ai/v1 (or your self-hosted domain). All requests must be authenticated using an API Key passed in the X-API-Key header. You can manage API keys in the Settings > Integrations > API Keys section of the Switchbord dashboard.

​
Core v1 Surface

The v1 API focuses on high-level operations for automated workflows:
  • GET /v1/contacts - List and filter workspace contacts.
  • POST /v1/messages - Send messages (text, media, or template) to a contact.
  • GET /v1/templates - Fetch approved WhatsApp templates.
  • POST /v1/broadcasts - Trigger a pre-defined broadcast to a segment.

​
Provider Webhook Ingress

Switchbord handles the complexity of Meta’s webhook challenges and signature verification:
  • POST /webhooks/whatsapp - Primary ingress for WhatsApp Business Platform events.
These routes handle challenge verification, signature validation, and replay-safe job enqueueing.

​
Compatibility Endpoints

To ease migration from legacy systems, we maintain compatibility aliases for Charles and other common platforms:
  • PUT /api/v1beta/contact/
  • POST /webhooks/v0/rest-trigger/...
See the Compatibility Surface guide for the exact mappings.

​
Extension and Internal API

For forensic and administrative operations, an internal API surface exists (prefixed with /internal). These endpoints are used by the Switchbord UI and are subject to change.
  • GET /internal/audit-logs
  • GET /internal/webhook-events

​
Posture and Reliability

  • Fully Typed: All endpoints are modeled with TypeScript and validated at the edge.
  • Queue-First: Webhook payloads are persisted to the database and normalized before being processed by background workers.
  • Rate Limiting: Default limits apply to v1 endpoints. Contact support for high-volume requirements.