API Introduction - Kordless

Kordless API Platform

The Kordless API platform enables you to integrate scheduling, customer management, and AI-powered tools into your applications. Build custom workflows, automate operations, and create unique booking experiences for your customers.

Currently Available: Booking APIComing Soon: CRM API, Chat API, Analytics API

Available APIs

Booking API

Create custom booking experiences, embed scheduling widgets, and manage appointments programmatically.Status: ✅ Available Now

Manage customers, contacts, and relationships through the API.Status: 🚧 Coming Soon

Chat API

Integrate our AI-powered virtual sales assistant into your applications.Status: 🚧 Roadmap

Analytics API

Access business metrics, reports, and insights programmatically.Status: 🚧 Roadmap

Booking API

The Booking API allows you to build custom booking experiences for your customers. Perfect for:

Custom booking widgets - Embed scheduling on your website
Mobile apps - Native iOS/Android booking experiences
Third-party integrations - Connect Kordless to other tools
White-label solutions - Embed scheduling in your products

How It Works

The Booking API uses your organization slug (from your public booking page URL) to identify your business:

https://api.kordless.ai/api/calendar/v1/public/org/{your-org-slug}

Booking API Capabilities

Services & Organization

Get organization branding and info
List bookable services
Retrieve service details and settings

Availability

Query available time slots
Support for hosts and teams
Timezone-aware slot calculations
Real-time availability checks

Bookings

Create new bookings
Lookup bookings by confirmation number
Cancel bookings
Reschedule bookings

Webhooks

Real-time booking notifications
Event-driven automation
Secure webhook verification

Getting Started

Generate API Key

Create an API key in the platform: Calendar → Settings → API Keys

Get Your Organization Slug

Find your organization slug in your public booking page URL:Find your slug in Calendar → Settings → Public Booking Page.

Make Your First Request

Fetch your organization info and services:

curl https://api.kordless.ai/api/calendar/v1/public/org/your-org-slug \
  -H "x-kordless-key: your_api_key"

Base URL

All API requests should be made to:

https://api.kordless.ai

For local development:

http://localhost:8000

Authentication

Booking API requests require one header:

x-kordless-key: your_api_key

Never expose your API key in client-side code or public repositories. Use a backend proxy to make API calls.

Read the Authentication Guide →

Typical Booking Flow

Code Examples

JavaScript
Python
cURL

const API_KEY = process.env.KORDLESS_API_KEY;
const ORG_SLUG = 'your-org-slug';

// 1. Get available services
const orgResponse = await fetch(
  `https://api.kordless.ai/api/calendar/v1/public/org/${ORG_SLUG}`,
  { headers: { 'x-kordless-key': API_KEY } }
);
const { organization, services } = await orgResponse.json();

// 2. Get availability for a service
const params = new URLSearchParams({
  org_slug: ORG_SLUG,
  service_slug: services[0].slug,
  from: '2025-12-03T00:00:00Z',
  to: '2025-12-03T23:59:59Z',
  partySize: '1'
});

const slotsResponse = await fetch(
  `https://api.kordless.ai/api/calendar/v1/public/availability?${params}`,
  { headers: { 'x-kordless-key': API_KEY } }
);
const { slots } = await slotsResponse.json();

// 3. Create a booking
const bookingResponse = await fetch(
  'https://api.kordless.ai/api/calendar/v1/public/bookings',
  {
    method: 'POST',
    headers: {
      'x-kordless-key': API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': `booking-${Date.now()}`
    },
    body: JSON.stringify({
      org_slug: ORG_SLUG,
      service_slug: services[0].slug,
      starts_at: slots[0].startsAt,
      ends_at: slots[0].endsAt,
      timezone: 'America/New_York',
      contact: {
        name: 'Jane Doe',
        email: '[email protected]',
        phone: '+1234567890'
      }
    })
  }
);

const { booking } = await bookingResponse.json();
console.log(`Booked! Confirmation: ${booking.confirmation_number}`);

import os
import requests

API_KEY = os.environ['KORDLESS_API_KEY']
ORG_SLUG = 'your-org-slug'
HEADERS = {'x-kordless-key': API_KEY}

# 1. Get available services
org_response = requests.get(
    f'https://api.kordless.ai/api/calendar/v1/public/org/{ORG_SLUG}',
    headers=HEADERS
)
data = org_response.json()
services = data['services']

# 2. Get availability
slots_response = requests.get(
    'https://api.kordless.ai/api/calendar/v1/public/availability',
    headers=HEADERS,
    params={
        'org_slug': ORG_SLUG,
        'service_slug': services[0]['slug'],
        'from': '2025-12-03T00:00:00Z',
        'to': '2025-12-03T23:59:59Z',
        'partySize': 1
    }
)
slots = slots_response.json()['slots']

# 3. Create a booking
booking_response = requests.post(
    'https://api.kordless.ai/api/calendar/v1/public/bookings',
    headers={**HEADERS, 'Content-Type': 'application/json'},
    json={
        'org_slug': ORG_SLUG,
        'service_slug': services[0]['slug'],
        'starts_at': slots[0]['startsAt'],
        'ends_at': slots[0]['endsAt'],
        'timezone': 'America/New_York',
        'contact': {
            'name': 'Jane Doe',
            'email': '[email protected]'
        }
    }
)

booking = booking_response.json()['booking']
print(f"Booked! Confirmation: {booking['confirmation_number']}")

# 1. Get organization & services
curl https://api.kordless.ai/api/calendar/v1/public/org/your-org-slug \
  -H "x-kordless-key: your_api_key"

# 2. Get availability
curl "https://api.kordless.ai/api/calendar/v1/public/availability?org_slug=your-org-slug&service_slug=haircut&from=2025-12-03T00:00:00Z&to=2025-12-03T23:59:59Z&partySize=1" \
  -H "x-kordless-key: your_api_key"

# 3. Create booking
curl -X POST https://api.kordless.ai/api/calendar/v1/public/bookings \
  -H "x-kordless-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "org_slug": "your-org-slug",
    "service_slug": "haircut",
    "starts_at": "2025-12-03T14:00:00Z",
    "ends_at": "2025-12-03T15:00:00Z",
    "timezone": "America/New_York",
    "contact": {
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  }'

Rate Limits

Default Limits:

General requests: 60 requests per minute per API key
Booking creation: 10 requests per minute per API key

Higher limits available for production use cases.

Rate limit headers in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

Customer Self-Service

For customer self-service actions (lookup, cancel, reschedule), the API uses confirmation number + contact verification instead of an API key:

# Customer looks up their booking
curl "https://api.kordless.ai/api/calendar/v1/public/bookings/confirmation/[email protected]"

# Customer cancels their booking
curl -X POST "https://api.kordless.ai/api/calendar/v1/public/bookings/confirmation/ABC123/[email protected]"

This allows customers to manage their own bookings securely.

Booking API Endpoints

Get Organization

Get organization info and list of services

Get Service

Get service details and calendar settings

Get Availability

Query available time slots

Create Booking

Create a new booking

Lookup Booking

Look up booking by confirmation number

Cancel Booking

Cancel a booking

Reschedule Booking

Reschedule to a new time

Webhooks

Real-time booking notifications

What’s Next?

Authentication

Learn about API key authentication.

Create a Booking

Make your first booking API call.

Error Handling

Understand API errors and how to handle them.

Webhooks

Set up real-time event notifications.

Getting Started

Services

Availability

Bookings

Webhooks

​Kordless API Platform

​Available APIs

Booking API

Chat API

Analytics API

​Booking API

​How It Works

​Booking API Capabilities

​Getting Started

​Base URL

​Authentication

​Typical Booking Flow

​Code Examples

​Rate Limits

​Customer Self-Service

​Booking API Endpoints

Get Organization

Get Service

Get Availability

Create Booking

Lookup Booking

Cancel Booking

Reschedule Booking

Webhooks

​What’s Next?

Authentication

Create a Booking

Error Handling

Webhooks

Kordless API Platform

Available APIs

Booking API

How It Works

Booking API Capabilities

Getting Started

Base URL

Authentication

Typical Booking Flow

Code Examples

Rate Limits

Customer Self-Service

Booking API Endpoints

What’s Next?