Free AI Booking API Documentation - No Credit Card Required

UseBotAI FREE Booking API

The UseBotAI Booking API allows you to integrate our powerful appointment booking and customer management capabilities into your existing applications. Start FREE with manual booking features - no credit card required!

Free API Access

Get started with 150 manual bookings per month, 5 services, and full API access - completely free, no credit card required!

Base URL

https://usebotai.com/api/v1

Content Type

application/json

Getting Started

To get started, you'll need an API key from your UseBotAI client dashboard. All API requests must be authenticated using this key for accessing booking system features.

Authentication

UseBotAI API uses Bearer token authentication. Include your API key in the Authorization header of every request. API access and rate limits depend on your subscription plan.

Plan-Based API Access

Free Plan

• API access included
• 150 booking API calls/month
• 5 services max
• Standard rate limits (60 req/min)
• No credit card required

Paid Plans

• Unlimited API calls
• Higher service limits
• Priority support
• Enhanced rate limits (300 req/min)
• AI voice features access

API Key Format

ub_your_company_name_1234567890abcdef

Authentication Header

Authorization: Bearer ub_your_company_name_1234567890abcdef

Example Request

curl -H "Authorization: Bearer ub_your_company_name_1234567890abcdef" \
     -H "Content-Type: application/json" \
     https://usebotai.com/api/v1/bookings

Security Note

Keep your API key secure and never expose it in client-side code. If compromised, regenerate it immediately from your dashboard.

Error Handling

UseBotAI API uses conventional HTTP response codes to indicate the success or failure of requests.

Success Codes

200 - OK
201 - Created
204 - No Content

Error Codes

400 - Bad Request
401 - Unauthorized
403 - Plan Limit Exceeded
404 - Not Found
429 - Rate/Monthly Limit Exceeded
500 - Server Error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is invalid",
    "details": {
      "email": ["Email is required"],
      "phone": ["Phone number format is invalid"]
    }
  }
}

Rate Limits & Quotas

API rate limits and monthly quotas vary by subscription plan. Exceeding limits will result in HTTP 429 responses.

Plan	Rate Limit	Monthly Bookings	Services Limit
Free	60 req/min	150 bookings	5 services
Starter	150 req/min	Unlimited	20 services
Professional	300 req/min	Unlimited	100 services
Enterprise	600 req/min	Unlimited	400 services

Rate Limit Headers

All API responses include headers with current limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640995200
X-MonthlyLimit-Remaining: 142
X-MonthlyLimit-Reset: 1643673600

Rate Limit Exceeded Response

HTTP 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later",
    "details": {
      "limit": 60,
      "reset_time": 1640995200,
      "retry_after": 60
    }
  }
}

Pagination

List endpoints support pagination using limit and offset parameters.

Parameters

limit - Number of items to return (max 100, default 20)
offset - Number of items to skip (default 0)

Example Request

GET /api/v1/bookings?limit=50&offset=100

Response Format

{
  "data": [...],
  "pagination": {
    "total": 250,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

Bookings API

Manage appointments and bookings for your business. API access and limitations depend on your subscription plan.

Plan-Based API Limitations

Free Plan

• 150 bookings/month
• 5 services max
• Manual booking only
• No AI features

Starter Plan

• Unlimited bookings
• 20 services max
• Voice assistant
• Default AI model

Professional Plan

• Unlimited bookings
• 100 services max
• All AI models
• 5 voice clones

Enterprise Plan

• Unlimited bookings
• 400 services max
• All AI models
• 20 voice clones

List Bookings

GET /api/v1/bookings

Retrieve a list of all bookings for your business.

Query Parameters

status - Filter by status (confirmed, pending, cancelled, completed)
date_from - Filter bookings from date (YYYY-MM-DD)
date_to - Filter bookings to date (YYYY-MM-DD)
customer_id - Filter by customer ID
service_id - Filter by service ID

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://usebotai.com/api/v1/bookings?status=confirmed&limit=10"

Create Booking

POST /api/v1/bookings

Create a new booking. Subject to plan limitations and monthly quotas.

Plan Restrictions Apply

Free plan users are limited to 150 bookings per month. Paid plans have unlimited booking creation. Service limits also apply based on your subscription tier.

Request Body

{
  "customer_id": 123,
  "service_id": 456,
  "appointment_date": "2024-12-20",
  "appointment_time": "14:30:00",
  "notes": "Customer prefers window seat"
}

Success Response (201 Created)

{
  "id": 789,
  "booking_reference": "BOOK001234",
  "customer_id": 123,
  "service_id": 456,
  "appointment_date": "2024-12-20",
  "appointment_time": "14:30:00",
  "duration_minutes": 60,
  "status": "confirmed",
  "notes": "Customer prefers window seat",
  "created_at": "2024-12-15T10:30:00Z"
}

Error Responses

Monthly Booking Limit Exceeded (Free Plan)

HTTP 429 Too Many Requests
{
  "error": {
    "code": "MONTHLY_LIMIT_EXCEEDED",
    "message": "Monthly booking limit of 150 bookings exceeded for Free plan",
    "details": {
      "plan": "free",
      "limit": 150,
      "used": 150,
      "reset_date": "2024-01-01"
    },
    "upgrade_url": "https://usebotai.com/client/subscription-plans"
  }
}

Service Limit Exceeded

HTTP 403 Forbidden
{
  "error": {
    "code": "SERVICE_LIMIT_EXCEEDED", 
    "message": "Cannot create booking for service. Service limit exceeded for your plan",
    "details": {
      "service_count": 5,
      "service_limit": 5,
      "plan": "free"
    },
    "upgrade_url": "/client/subscription-plans"
  }
}

Service Not Found or Inactive

HTTP 404 Not Found
{
  "error": {
    "code": "SERVICE_NOT_FOUND",
    "message": "Service not found or not available for your plan",
    "details": {
      "service_id": 456
    }
  }
}

Get Booking

GET /api/v1/bookings/{id}

Retrieve a specific booking by ID.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://usebotai.com/api/v1/bookings/789"

Update Booking

PUT /api/v1/bookings/{id}

Update an existing booking.

{
  "appointment_date": "2024-12-21",
  "appointment_time": "15:00:00",
  "status": "confirmed",
  "notes": "Rescheduled to next day"
}

Cancel Booking

DELETE /api/v1/bookings/{id}

Cancel a booking (sets status to cancelled).

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
     "https://usebotai.com/api/v1/bookings/789"

Customers API

Manage your customer database and contact information.

List Customers

GET /api/v1/customers

Query Parameters

search - Search by name, email, or phone
email - Filter by email address
phone - Filter by phone number

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://usebotai.com/api/v1/customers?search=john"

Create Customer

POST /api/v1/customers

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_number": "+1-555-0123",
  "preferred_language": "en",
  "notes": "VIP customer"
}

Services API

Manage your business services and pricing. Service creation limits apply based on your plan.

Service Limits by Plan

Free: 5 services Starter: 20 services Professional: 100 services Enterprise: 400 services

List Services

GET /api/v1/services

{
  "data": [
    {
      "id": 1,
      "service_name": "Personal Training Session",
      "description": "One-on-one fitness training",
      "duration_minutes": 60,
      "price": 75.00,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Create Service

POST /api/v1/services

Create a new service. Subject to service limits based on your plan.

Request Body

{
  "service_name": "Personal Training Session",
  "description": "One-on-one fitness training",
  "duration_minutes": 60,
  "price": 75.00,
  "category": "fitness",
  "is_active": true
}

Success Response (201 Created)

{
  "id": 1,
  "service_name": "Personal Training Session",
  "description": "One-on-one fitness training",
  "duration_minutes": 60,
  "price": 75.00,
  "category": "fitness",
  "is_active": true,
  "created_at": "2024-12-15T10:30:00Z"
}

Error Response - Service Limit Exceeded

HTTP 403 Forbidden
{
  "error": {
    "code": "SERVICE_LIMIT_EXCEEDED",
    "message": "Service limit exceeded for your plan. Upgrade to create more services",
    "details": {
      "current_count": 5,
      "service_limit": 5,
      "plan": "free"
    },
    "upgrade_url": "/client/subscription-plans"
  }
}

Analytics API

Access booking and usage analytics for your business.

Booking Statistics

GET /api/v1/analytics/bookings

{
  "period": "last_30_days",
  "total_bookings": 150,
  "confirmed_bookings": 135,
  "cancelled_bookings": 10,
  "no_show_bookings": 5,
  "revenue": 11250.00,
  "daily_breakdown": [
    {
      "date": "2024-12-01",
      "bookings": 8,
      "revenue": 600.00
    }
  ]
}

JavaScript SDK

Use our JavaScript SDK for easy integration in web applications.

Installation

npm install @usebotai/sdk

Usage

import UseBotAI from '@usebotai/sdk';

const client = new UseBotAI({
  apiKey: 'ub_your_api_key_here',
  baseUrl: 'https://usebotai.com/api/v1'
});

// List bookings
const bookings = await client.bookings.list({
  status: 'confirmed',
  limit: 10
});

// Create a booking
const newBooking = await client.bookings.create({
  customer_id: 123,
  service_id: 456,
  appointment_date: '2024-12-20',
  appointment_time: '14:30:00'
});

// Get customers
const customers = await client.customers.list({
  search: 'john',
  limit: 20
});

// Get services
const services = await client.services.list();

Python SDK

Use our Python SDK for server-side integrations.

Installation

pip install usebotai-sdk

Usage

from usebotai import UseBotAI

client = UseBotAI(
    api_key='ub_your_api_key_here',
    base_url='https://usebotai.com/api/v1'
)

# List bookings
bookings = client.bookings.list(
    status='confirmed',
    limit=10
)

# Create a booking
new_booking = client.bookings.create(
    customer_id=123,
    service_id=456,
    appointment_date='2024-12-20',
    appointment_time='14:30:00'
)

# Get customers
customers = client.customers.list(
    search='john',
    limit=20
)

# Get services
services = client.services.list()

PHP SDK

Use our PHP SDK for server-side integrations.

Installation

composer require usebotai/sdk

Usage



Warning:  require_once(vendor/autoload.php): Failed to open stream: No such file or directory in /home/u817454884/domains/usebotai.com/public_html/api_docs.php on line 985



Fatal error:  Uncaught Error: Failed opening required 'vendor/autoload.php' (include_path='.:/opt/alt/php82/usr/share/pear:/opt/alt/php82/usr/share/php:/usr/share/pear:/usr/share/php') in /home/u817454884/domains/usebotai.com/public_html/api_docs.php:985
Stack trace:
#0 {main}
  thrown in /home/u817454884/domains/usebotai.com/public_html/api_docs.php on line 985