API Documentation

Comprehensive guide to integrating with BookEase. Build powerful scheduling, manage bookings, and automate workflows.

Overview

The BookEase API is a RESTful interface that allows you to programmatically manage bookings, access customer data, and integrate scheduling into your applications.

ℹ️

Base URL: All API requests should be made to https://api.bookease.io/v1. The API returns JSON responses and accepts JSON request bodies.

Rate Limiting

API requests are limited to 100 requests per minute for standard accounts and 500 requests per minute for enterprise plans. Exceeding limits returns a 429 Too Many Requests status.

Versioning

We follow semantic versioning. The current stable version is v1.0.0. Breaking changes will be introduced in v2 with a 6-month deprecation window.

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Header Authorization: Bearer YOUR_API_KEY

Obtain your API key from the BookEase Dashboard under Settings → API Keys.

⚠️

Never expose your API key in client-side code or public repositories. Use environment variables or a backend proxy.

Bookings

The Bookings resource represents a scheduled appointment or reservation. You can list, create, update, and cancel bookings.

GET /bookings

Retrieve a paginated list of bookings. Supports filtering by status, date range, and service ID.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `confirmed`, `pending`, `cancelled`
`date_from`	string	No	ISO 8601 date (YYYY-MM-DD)
`date_to`	string	No	ISO 8601 date (YYYY-MM-DD)
`limit`	integer	No	Number of results (default: 20, max: 100)
`cursor`	string	No	Pagination cursor from previous response

Example Request

GET /v1/bookings?status=confirmed&limit=10

Example Response

{
  "data": [
    {
      "id": "bk_8x92k1m3",
      "status": "confirmed",
      "service": "Haircut",
      "provider": "Sarah M.",
      "customer": "john@example.com",
      "scheduled_at": "2025-08-15T14:00:00Z",
      "created_at": "2025-07-10T09:22:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImJrXzh4OTJrMW0zIn0=",
    "has_more": true
  }
}

POST /bookings

Create a new booking. Requires a valid service ID and customer details.

Request Body

Field	Type	Required	Description
`service_id`	string	Yes	ID of the service to book
`provider_id`	string	No	Specific provider (optional)
`customer_email`	string	Yes	Customer email address
`customer_name`	string	Yes	Customer full name
`scheduled_at`	string	Yes	ISO 8601 datetime
`notes`	string	No	Additional booking notes

Example Request

POST /v1/bookings
Content-Type: application/json

{
  "service_id": "svc_haircut_premium",
  "customer_email": "jane@company.com",
  "customer_name": "Jane Doe",
  "scheduled_at": "2025-09-01T10:30:00Z",
  "notes": "Prefers quiet room"
}

PUT /bookings/:id

Update an existing booking. Only scheduled_at and notes are mutable.

PUT /v1/bookings/bk_8x92k1m3

{
  "scheduled_at": "2025-08-16T15:00:00Z",
  "notes": "Rescheduled due to conflict"
}

DELETE /bookings/:id

Cancel a booking. Returns 204 No Content on success.

Note: Bookings scheduled less than 24 hours in advance cannot be cancelled via API unless the account has premium permissions.

Webhooks

Subscribe to real-time events by registering a webhook URL in your dashboard. BookEase sends POST requests with a JSON payload.

Supported Events

Event	Description
`booking.created`	New booking successfully created
`booking.updated`	Booking details modified
`booking.cancelled`	Booking cancelled by user or provider
`booking.reminder`	24-hour reminder triggered

{
  "event": "booking.created",
  "timestamp": "2025-08-10T12:00:00Z",
  "data": {
    "id": "bk_9a21b4c7",
    "status": "confirmed",
    "service": "Massage Therapy",
    "customer_email": "alex@startup.io",
    "scheduled_at": "2025-08-12T11:00:00Z"
  }
}

🔐

All webhook requests include a X-BookEase-Signature header. Verify payloads using your webhook secret to prevent spoofing.

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details.

200 Success

201 Created

204 No Content

400 Bad Request

401 Unauthorized

404 Not Found

429 Rate Limited

500 Server Error

Error Response Format

{
  "error": {
    "code": "invalid_payload",
    "message": "Missing required field: customer_email",
    "details": {
      "field": "customer_email",
      "reason": "required"
    }
  }
}