Build on ChatGenius
API Documentation & Developer Resources

Authentication

All API requests require authentication using a Bearer token in the Authorization header. API keys are available on the Enterprise plan.

Getting Your API Key

1. Log in to your ChatGenius dashboard
2. Navigate to Settings → API & Integrations
3. Click Generate API Key (Enterprise plan required)
4. Copy your API key and store it securely

Using the API Key

Include the token in every request header:

Authorization: Bearer YOUR_API_TOKEN

Example with cURL:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.chatgeniusx.com/api/bookings"

Base URL & Rate Limits

Base URL

https://api.chatgeniusx.com/api

All endpoints are relative to this base URL. For example, the bookings endpoint is:

https://api.chatgeniusx.com/api/bookings

Rate Limits

API requests are rate-limited to prevent abuse:

• 200 requests per minute per API key (default)
• 30 requests per minute for the /chat endpoint
• Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset window before retrying.

Response Format

All responses are JSON. Successful responses return the data directly. Errors return an object with an error field:

// Success
{ "ok": true, "data": { ... } }

// Error
{ "error": "Unauthorized" }

Bookings API

{
  "api_key": "your_external_api_key",
  "customer_name": "John Smith",
  "customer_email": "john@example.com",
  "customer_phone": "+1234567890",
  "date": "2026-05-15",
  "time": "10:00",
  "service": "General Consultation",
  "doctor_name": "Dr. Sarah Johnson",
  "notes": "First visit"
}

{
  "ok": true,
  "booking_id": 142,
  "message": "Booking created"
}

[
  {
    "id": 142,
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "date": "2026-05-15",
    "time": "10:00",
    "service": "General Consultation",
    "doctor_name": "Dr. Sarah Johnson",
    "status": "confirmed"
  }
]

Patients API

[
  {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+1987654321",
    "date_of_birth": "1990-06-15",
    "insurance_provider": "Delta Dental"
  }
]

{
  "phone": "+1555000123",
  "insurance_provider": "Aetna",
  "notes": "Allergic to penicillin"
}

Leads API

[
  {
    "id": 23,
    "name": "Mike Wilson",
    "phone": "+1555999888",
    "email": "mike@email.com",
    "stage": "qualified",
    "score": 7,
    "treatment_interest": "Teeth Whitening",
    "source": "chatbot"
  }
]

{ "stage": "qualified" }

{ "score": 12.5 }

Doctors API

[
  {
    "id": 5,
    "name": "Dr. Sarah Johnson",
    "specialty": "General Dentist",
    "bio": "15 years of experience...",
    "photo_url": "",
    "availability": "Mon-Fri"
  }
]

Chat API

{
  "message": "I'd like to book a teeth cleaning",
  "session_id": "unique-session-id",
  "admin_id": "your-public-admin-guid"
}

{
  "response": "I'd be happy to help you book a teeth cleaning! Which date works best for you?",
  "action": "booking_flow",
  "session_id": "unique-session-id"
}

Webhook Events

ChatGenius can send real-time webhook notifications to your server via Zapier integration. Configure webhooks in your dashboard under Integrations → Zapier.

Webhook Payload Example

Here's an example payload for the new_booking event:

{
  "event": "new_booking",
  "timestamp": "2026-04-27T14:30:00Z",
  "data": {
    "booking_id": 142,
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "customer_phone": "+1234567890",
    "date": "2026-05-15",
    "time": "10:00",
    "service": "General Consultation",
    "doctor_name": "Dr. Sarah Johnson",
    "status": "confirmed"
  }
}

Webhook Security

To ensure webhook payloads are legitimate and haven't been tampered with:

• HTTPS Only — Webhook URLs must use HTTPS. HTTP endpoints are rejected.
• Signature Verification — Each webhook includes an X-ChatGenius-Signature header containing an HMAC-SHA256 signature of the payload body.
• Timestamp Validation — Verify the timestamp field is within 5 minutes of current time to prevent replay attacks.

Verifying the Signature

import hmac, hashlib

def verify_signature(payload_body, signature, secret):
    """Verify the X-ChatGenius-Signature header."""
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Code Examples

Create a Booking

curl -X POST https://api.chatgeniusx.com/api/external/booking \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_EXTERNAL_API_KEY",
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "customer_phone": "+1234567890",
    "date": "2026-05-15",
    "time": "10:00",
    "service": "General Consultation"
  }'

import requests

response = requests.post(
    "https://api.chatgeniusx.com/api/external/booking",
    json={
        "api_key": "YOUR_EXTERNAL_API_KEY",
        "customer_name": "John Smith",
        "customer_email": "john@example.com",
        "customer_phone": "+1234567890",
        "date": "2026-05-15",
        "time": "10:00",
        "service": "General Consultation",
    }
)
print(response.json())

const resp = await fetch("https://api.chatgeniusx.com/api/external/booking", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_EXTERNAL_API_KEY",
    customer_name: "John Smith",
    customer_email: "john@example.com",
    customer_phone: "+1234567890",
    date: "2026-05-15",
    time: "10:00",
    service: "General Consultation",
  })
});
const data = await resp.json();
console.log(data);

Get Patients

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.chatgeniusx.com/api/patients"

import requests

response = requests.get(
    "https://api.chatgeniusx.com/api/patients",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
patients = response.json()
for p in patients:
    print(p["name"], p["email"])

const resp = await fetch("https://api.chatgeniusx.com/api/patients", {
  headers: { "Authorization": "Bearer YOUR_API_TOKEN" }
});
const patients = await resp.json();
patients.forEach(p => console.log(p.name, p.email));

Send a Chat Message

curl -X POST https://api.chatgeniusx.com/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I need to book a dental cleaning",
    "session_id": "my-session-123",
    "admin_id": "YOUR_PUBLIC_ADMIN_ID"
  }'

import requests

response = requests.post(
    "https://api.chatgeniusx.com/chat",
    json={
        "message": "I need to book a dental cleaning",
        "session_id": "my-session-123",
        "admin_id": "YOUR_PUBLIC_ADMIN_ID",
    }
)
print(response.json()["response"])

const resp = await fetch("https://api.chatgeniusx.com/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    message: "I need to book a dental cleaning",
    session_id: "my-session-123",
    admin_id: "YOUR_PUBLIC_ADMIN_ID",
  })
});
const data = await resp.json();
console.log(data.response);

SDKs & Libraries Coming Soon

Official SDKs for popular languages are in development. In the meantime, use the REST API directly with any HTTP client.

Interactive API Explorer

Select an endpoint to see the cURL command. Copy and run it in your terminal to test the API.