API Documentation

Integrate seamlessly with BookEase's booking engine. Our RESTful API allows you to manage bookings, services, customers, and automate your scheduling workflow.

Base URL: https://api.bookease.com/v1
All requests require a valid API key. Responses are returned in JSON format.

Quick Start

curl -X GET https://api.bookease.com/v1/services \
  -H 'Authorization: Bearer bk_live_abc123xyz' \
  -H 'Content-Type: application/json'

Authentication

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

AUTH Authorization: Bearer <your_api_key>

Key Type	Purpose	Prefix
`bk_test_...`	Development & testing	Test mode
`bk_live_...`	Production environment	Live mode

Never expose live API keys in client-side code or public repositories. Use environment variables.

Core Endpoints

The API is structured around REST principles. Each resource is accessed via a plural noun endpoint.

Bookings

POST /bookings

Create a new booking. Requires a valid service_id and customer_id.

Request Body

Parameter	Type	Description
`service_id` Required	string	UUID of the service to book
`customer_id` Required	string	UUID of the customer
`start_time` Required	ISO 8601	Booking start time
`notes` Optional	string	Additional instructions

Example Request

{"service_id": "srv_8f3k29", "customer_id": "cus_1m2n3o", "start_time": "2025-08-15T14:00:00Z", "notes": "Please arrive 5 mins early."}

Example Response

{"id": "bkg_x9y8z7", "status": "confirmed", "service_id": "srv_8f3k29", "customer_id": "cus_1m2n3o", "start_time": "2025-08-15T14:00:00Z", "created_at": "2025-06-01T10:30:00Z"}

Services

GET/services

Retrieve a list of available services. Supports filtering by category, provider, and availability.

Query Param	Type	Description
`category`	string	Filter by service category
`available`	boolean	Only return bookable services
`limit`	integer	Max items per page (default: 20)

Customers

GET/customers/:id

Fetch detailed customer information including booking history, preferences, and contact details.

Pagination & Filtering

List endpoints return paginated results. Use cursor-based pagination for consistent performance at scale.

{"data": [...], "pagination": {"next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true, "total_count": 1240}}

Pass the next_cursor value in subsequent requests to fetch the next page.

Error Handling

BookEase uses standard HTTP status codes. Error responses include a machine-readable error object.

Code	Meaning	Common Cause
`400`	Bad Request	Invalid JSON or missing required fields
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for this resource
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Time slot already booked
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal BookEase issue (contact support)

Error Response Format

{"error": {"code": "slot_unavailable", "message": "The requested time slot is already booked.", "request_id": "req_9a8b7c6d"}}

Rate Limits

API requests are limited to 1,000 requests per minute per API key. Headers included in every response:

X-RateLimit-Limit: Max requests allowed
X-RateLimit-Remaining: Requests left in current window
X-RateLimit-Reset: Unix timestamp when window resets

Exceeding limits returns 429 Too Many Requests. Implement exponential backoff.

Webhooks

Receive real-time notifications when booking events occur. Configure endpoints in your Dashboard.

Event	Description
`booking.created`	New booking confirmed
`booking.cancelled`	Booking cancelled by user or system
`booking.rescheduled`	Booking time updated
`payment.completed`	Payment successfully processed

All webhook payloads are signed with HmacSHA256. Verify the X-BookEase-Signature header before processing.

SDKs & Integrations

Official client libraries are available for popular languages. Community libraries are also supported.

Language	Package	Status
Python	`pip install bookease-sdk`	Official
Node.js	`npm install @bookease/api`	Official
PHP	`composer require bookease/php-sdk`	Official
Ruby	`gem install bookease-ruby`	Community

📦 Import our collection in Postman or test endpoints directly in the API Playground.

Changelog

v1.2.4 (2025-05-20) - Added booking.rescheduled webhook, improved cursor pagination
v1.2.0 (2025-03-10) - Introduced service availability filtering, new rate limit headers
v1.1.0 (2024-11-05) - Customer preferences endpoint, webhook signature verification docs
v1.0.0 (2024-06-01) - Initial public release