AI Appointment Assistant API

Version v1Base URL: https://api.aiappointmentassistant.com/v1

Welcome to the official API documentation for AI Appointment Assistant. Developers can integrate leads, appointments, conversations, user data, and custom automations using our secure REST API.

📦 Resources Overview

LeadsCreate, list, update, delete incoming leads
AppointmentsCreate and manage bookings
ConversationsFetch AI conversations, messages, status
UsersProgrammatically manage team accounts
WebhooksReceive real-time events

🔐 Authentication

All API requests require one of the following authentication methods:

1. API Key (Server-to-Server)

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

2. OAuth 2.0 (User integrations)

We support:

  • Authorization Code Flow
  • Client Credentials Flow

📘 Quick Start

Create your first lead in seconds:

curl -X POST https://api.aiappointmentassistant.com/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "prospect@example.com",
    "name": "John Doe",
    "phone": "+1-444-123-9876",
    "source": "website"
  }'

📍 Leads API

POST/leads

Create a new lead.

Request Body

FieldTypeRequiredDescription
emailstringyesLead email
namestringnoLead name
phonestringnoPhone number
sourcestringnoSource tag

Response Example

{
  "id": "lead_83hd92k1",
  "email": "prospect@example.com",
  "status": "new",
  "created_at": 1732819200
}
GET/leads

List all leads.

Parameters

  • limit - Max items (default 20)
  • page - Pagination
curl -X GET https://api.aiappointmentassistant.com/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/leads/:id

Retrieve a specific lead.

curl -X GET https://api.aiappointmentassistant.com/v1/leads/lead_83hd92k1 \
  -H "Authorization: Bearer YOUR_API_KEY"
PATCH/leads/:id

Update a lead.

curl -X PATCH https://api.aiappointmentassistant.com/v1/leads/lead_83hd92k1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "status": "contacted" }'
DELETE/leads/:id

Delete a lead.

curl -X DELETE https://api.aiappointmentassistant.com/v1/leads/lead_83hd92k1 \
  -H "Authorization: Bearer YOUR_API_KEY"

📅 Appointments API

POST/appointments

Create a new appointment.

Request Fields

  • lead_id - required
  • datetime - required (ISO 8601)
  • duration - default 30 mins
curl -X POST https://api.aiappointmentassistant.com/v1/appointments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "lead_id": "lead_83hd92k1",
    "datetime": "2025-01-10T14:00:00Z",
    "duration": 30
  }'

GET /appointments - Filter by date, status, lead, or team

PATCH /appointments/:id - Reschedule or update details

DELETE /appointments/:id - Cancel an appointment

💬 Conversations API

GET/conversations

List all conversations.

GET/conversations/:id

Retrieve detailed transcript.

curl -X GET https://api.aiappointmentassistant.com/v1/conversations/cnv_028kd \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/conversations/:id/messages

Send message into an AI conversation thread.

👤 Users API

GET/users

List users (admins only).

POST/users

Create user.

Fields

  • email
  • name
  • role: admin | manager | staff | viewer

📡 Webhooks

Use webhooks to receive real-time events.

Webhook Endpoint Example

POST https://yourdomain.com/webhooks/aiassistant

Supported Events

EventDescription
lead.createdNew lead generated
lead.updatedStatus changed
appointment.bookedAppointment confirmed
appointment.rescheduledUser rescheduled
conversation.completedAI finished the conversation
message.createdNew AI message

Webhook Request Example

{
  "event": "appointment.booked",
  "timestamp": 1732819200,
  "data": {
    "appointment_id": "apt_22jdh38",
    "lead_id": "lead_83hd92k1"
  }
}

⚠️ Errors

CodeMeaning
400Invalid request
401Invalid or missing API key
403Insufficient permissions
404Resource not found
429Rate limit exceeded
500Server error

📈 Rate Limits

  • 60 requests per minute per API key
  • Bursting supported

📄 Changelog

v1.1

Added webhooks + conversations API

v1.0

Initial public API

🚀 Want API Access?

API is available on Growth and Pro plans.

View Pricing