Overview

The Coachbot Public API lets you submit leads into Coachbot from your own backend without using the built-in /forms/<slug> UI. Same dispatch pipeline as the form — voice workspaces get a sync Vapi call, WhatsApp workspaces fire the Inngest agent turn.

When to use it#

• You already have a beautifully-designed lead form on your own website and don't want to migrate to Coachbot's form.
• You're capturing leads from somewhere that isn't a form (chat widget, calendly submission, ad lander).
• You want to enrich the lead with extra fields (Company Name, UTM source, etc.) that Coachbot's first-class columns don't have.

If you just want a hosted form, use /forms/<slug> instead — it's free, branded, validated, and has the same dispatch pipeline behind it.

Security model#

• Every API call is authenticated with a workspace-scoped Bearer key: Authorization: Bearer ck_live_<32 hex>.
• Keys are generated in Settings → API Keys. They display once on creation and are hashed (SHA-256) for storage. Coachbot will never show the plaintext again.
• Use one key per environment (production, staging) and revoke any that leak.
• Never embed a key in client-side JavaScript. Your backend should proxy the form submission to Coachbot. Client-side calls would expose the key to anyone who views source.

60-second quickstart#

1. Generate a key: Settings → API keys → New API key → name it → Generate → copy the plaintext ck_live_… value.
2. Submit a test lead from your terminal:

curl -X POST https://<your-host>/api/public/leads \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "phone": "+447xxxxxxxxx",
    "email": "jane@business.com",
    "goal": "Interested in your enterprise plan",
    "consent": true,
    "metadata": {
      "companyName": "Acme Corp",
      "source": "homepage form"
    }
  }'

3. You should get a 201 back with the lead ID. For voice workspaces, your phone rings within seconds. For WhatsApp workspaces, the lead's phone gets the agent's first message.

Full reference: Authentication, Submit a lead, Read a lead, Errors.