API Reference

Build custom integrations with the SeroBook REST API. Access bookings, customers, and services programmatically to extend your scheduling workflows.

Starter plan and above

The SeroBook API is available on Starter plans and above. Free plan users can upgrade from Settings → Billing to access the API.

API Overview

The SeroBook API is a RESTful API that uses JSON for request and response bodies. All API requests are made over HTTPS to the base URL:

https://api.serobook.com/v1

The API follows standard HTTP conventions. Use GET to retrieve resources, POST to create, PUT to update, and DELETE to remove. All timestamps are returned in ISO 8601 format and are in UTC.

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header with the Bearer prefix.

Authorization: Bearer sk_live_your_api_key_here

Generating an API Key

  1. Navigate to Settings → Integrations → API Keys
  2. Click Generate New Key
  3. Give the key a descriptive name (e.g., "Website Integration" or "CRM Sync")
  4. Copy the key immediately — it will only be shown once
  5. Store it securely in your application's environment variables
Keep your API key secret

Never expose your API key in client-side code, public repositories, or browser requests. Always make API calls from your server. If a key is compromised, revoke it immediately from Settings → Integrations → API Keys and generate a new one.

Available Endpoints

The SeroBook API provides access to the following resources:

Bookings

Manage bookings programmatically. Create, retrieve, update, and cancel bookings through the API.

GET    /v1/bookings          # List all bookings (paginated)
GET    /v1/bookings/:id      # Get a specific booking
POST   /v1/bookings          # Create a new booking
PUT    /v1/bookings/:id      # Update a booking
DELETE /v1/bookings/:id      # Cancel a booking

# Query parameters for listing:
?status=confirmed|cancelled|completed|pending
?from=2024-01-01&to=2024-01-31
?customer_id=cus_abc123
?page=1&limit=25

Customers

Access and manage your customer database. Search, create, and update customer profiles.

GET    /v1/customers         # List all customers (paginated)
GET    /v1/customers/:id     # Get a specific customer
POST   /v1/customers         # Create a new customer
PUT    /v1/customers/:id     # Update a customer
DELETE /v1/customers/:id     # Delete a customer

# Query parameters for listing:
?search=john@example.com
?created_after=2024-01-01
?page=1&limit=25

Services

Retrieve your list of services and their configuration, including pricing and duration.

GET    /v1/services          # List all services
GET    /v1/services/:id      # Get a specific service
POST   /v1/services          # Create a new service
PUT    /v1/services/:id      # Update a service
DELETE /v1/services/:id      # Delete a service

Request & Response Format

All request bodies must be sent as JSON with the Content-Type: application/json header. Responses are also returned as JSON.

Successful Response

Successful responses return a 200 (or 201 for creation) status code along with the requested data:

{
  "success": true,
  "data": {
    "id": "bk_abc123",
    "customer": {
      "id": "cus_def456",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "service": {
      "id": "svc_ghi789",
      "name": "Consultation",
      "duration": 60
    },
    "date": "2024-03-15",
    "time": "10:00",
    "status": "confirmed",
    "price": 75.00,
    "notes": "First-time customer",
    "created_at": "2024-03-10T14:30:00Z",
    "updated_at": "2024-03-10T14:30:00Z"
  }
}

Paginated Responses

List endpoints return paginated results with metadata about the total count and pagination:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "total_pages": 6
  }
}

Example Requests

Here are complete examples for the most common API operations.

Create a Booking (cURL)

curl -X POST https://api.serobook.com/v1/bookings \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "jane@example.com",
    "customer_name": "Jane Smith",
    "service_id": "svc_ghi789",
    "date": "2024-03-15",
    "time": "10:00",
    "notes": "Referred by John"
  }'

Create a Booking (JavaScript / Fetch)

const response = await fetch("https://api.serobook.com/v1/bookings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_email: "jane@example.com",
    customer_name: "Jane Smith",
    service_id: "svc_ghi789",
    date: "2024-03-15",
    time: "10:00",
    notes: "Referred by John",
  }),
});

const data = await response.json();
console.log(data);
// { success: true, data: { id: "bk_abc123", ... } }

List Bookings with Filters (cURL)

curl "https://api.serobook.com/v1/bookings?status=confirmed&from=2024-03-01&to=2024-03-31&limit=50" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Update a Customer (JavaScript / Fetch)

const response = await fetch("https://api.serobook.com/v1/customers/cus_def456", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    phone: "+1-555-0199",
    tags: ["vip", "returning"],
  }),
});

const data = await response.json();
console.log(data);
// { success: true, data: { id: "cus_def456", name: "Jane Doe", ... } }
Use environment variables

Store your API key in an environment variable (e.g., SEROBOOK_API_KEY) rather than hardcoding it. This makes your code more secure and easier to manage across environments.

Rate Limits

To ensure fair usage and platform stability, the SeroBook API enforces rate limits based on your plan:

  • Starter: 60 requests per minute
  • Pro: 200 requests per minute
  • Business: 500 requests per minute

Rate limit information is included in every response header:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1710500400

When you exceed the rate limit, the API returns a 429 Too Many Requests status. The X-RateLimit-Reset header contains the Unix timestamp when the limit resets. Implement exponential backoff in your application to handle rate limits gracefully.

Batch operations

If you need to perform bulk operations (e.g., importing hundreds of customers), use pagination and add a small delay between requests. Contact support if you need a temporary rate limit increase for a large migration.

Error Codes

The SeroBook API uses standard HTTP status codes to indicate the outcome of requests. Error responses include a JSON body with details:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The 'date' field is required.",
    "details": [
      {
        "field": "date",
        "message": "This field is required"
      }
    ]
  }
}

HTTP Status Codes

  • 200 OK — Request succeeded
  • 201 Created — Resource created successfully
  • 400 Bad Request — Invalid request body or parameters
  • 401 Unauthorized — Missing or invalid API key
  • 403 Forbidden — API key lacks permission for this action
  • 404 Not Found — Resource does not exist
  • 409 Conflict — Scheduling conflict (e.g., overlapping booking)
  • 422 Unprocessable Entity — Validation error in the request data
  • 429 Too Many Requests — Rate limit exceeded
  • 500 Internal Server Error — Something went wrong on our end

Error Codes Reference

  • authentication_error — Invalid or missing API key
  • validation_error — One or more fields failed validation
  • not_found — The requested resource was not found
  • conflict — A scheduling or data conflict occurred
  • rate_limit_exceeded — Too many requests in the time window
  • plan_limit_exceeded — Your plan does not include this feature
  • server_error — An internal error occurred; try again later

SDKs & Libraries

While the SeroBook API can be used with any HTTP client, we provide official libraries for popular languages to simplify integration:

  • JavaScript / TypeScript — npm install @serobook/sdk
  • Python — pip install serobook
  • PHP — composer require serobook/serobook-php

JavaScript SDK Example

import SeroBook from "@serobook/sdk";

const client = new SeroBook("sk_live_your_api_key_here");

// Create a booking
const booking = await client.bookings.create({
  customer_email: "jane@example.com",
  customer_name: "Jane Smith",
  service_id: "svc_ghi789",
  date: "2024-03-15",
  time: "10:00",
});

// List upcoming bookings
const bookings = await client.bookings.list({
  status: "confirmed",
  from: "2024-03-01",
  to: "2024-03-31",
});

// Update a customer
await client.customers.update("cus_def456", {
  phone: "+1-555-0199",
  tags: ["vip"],
});
TypeScript support

The JavaScript SDK includes full TypeScript type definitions. You'll get autocomplete and type checking for all API methods, request parameters, and response objects in your editor.

Next Steps

Ready to start building with the SeroBook API?