Getting your schedule ready...
Getting your schedule ready...
The TaanBook REST API lets you read and write appointments, clients, and services programmatically. All endpoints are under /api/v1 and require an API key.
Every request must include a valid API key in the Authorization header using the Bearer scheme. You can create and revoke API keys from Dashboard → Settings → API Keys.
Authorization: Bearer taanbook_sk_live_xxxxxxxxxxxxxxxxxxxx
Every successful response is wrapped in a { data } envelope. HTTP status codes follow REST conventions: 200 for reads, 201 for created resources, 204 for deletions with no body.
// 200 OK — list
{
"data": [ { "id": "...", ... }, ... ]
}
// 201 Created — single resource
{
"data": { "id": "...", ... }
}Errors always return a { error } object with a machine-readable code and a human-readable message.
{
"error": {
"code": "validation_error",
"message": "Invalid request",
"details": { ... } // present on validation errors
}
}| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | The key does not have access to this resource |
| 404 | not_found | Resource does not exist or belongs to another tenant |
| 422 | validation_error | Request body or query params failed validation |
| 429 | rate_limited | Too many requests — wait and retry |
| 500 | internal_error | Unexpected server error |
Create and query appointments for your business.
/api/v1/appointmentsList appointments in a date range.
fromrequired | ISO 8601 date | Start of the range (inclusive). |
torequired | ISO 8601 date | End of the range (inclusive). |
resourceId | string | Filter by staff/resource ID. |
clientId | string | Filter by client ID. |
GET /api/v1/appointments?from=2026-07-01&to=2026-07-31
Authorization: Bearer taanbook_sk_live_xxx
// Response
{
"data": [
{
"id": "clx1a2b3c4d5e6f7g8h9i",
"serviceId": "clx...",
"clientId": "clx...",
"resourceId": "clx...",
"branchId": "clx...",
"startsAt": "2026-07-15T10:00:00.000Z",
"endsAt": "2026-07-15T10:30:00.000Z",
"notes": null,
"source": "internal",
"cancelledAt": null,
"createdAt": "2026-06-20T08:00:00.000Z"
}
]
}/api/v1/appointmentsCreate a new appointment.
serviceIdrequired | string | ID of the service to book. |
startsAtrequired | ISO 8601 datetime | Start time of the appointment (UTC). |
clientId | string | ID of an existing client. Either clientId or client must be provided. |
client | object | Inline new client: { name, email?, phone? }. Creates the client record automatically. |
resourceId | string | Assign to a specific staff member or resource. |
branchId | string | Assign to a specific branch/location. |
notes | string | Internal notes (max 5 000 chars). |
POST /api/v1/appointments
Authorization: Bearer taanbook_sk_live_xxx
Content-Type: application/json
{
"serviceId": "clx1a2b3c4d5e6f7g8h9i",
"startsAt": "2026-07-15T10:00:00.000Z",
"client": { "name": "Sara López", "email": "sara@example.com" }
}
// Response 201 Created
{
"data": {
"id": "clx9z8y7x6w5v4u3t2s1r",
"serviceId": "clx1a2b3c4d5e6f7g8h9i",
"clientId": "clxnewclientid",
"startsAt": "2026-07-15T10:00:00.000Z",
"endsAt": "2026-07-15T10:30:00.000Z",
"source": "internal"
}
}/api/v1/appointments/{id}Retrieve a single appointment by ID.
GET /api/v1/appointments/clx9z8y7x6w5v4u3t2s1r Authorization: Bearer taanbook_sk_live_xxx
Manage your client/contact list. All client data is scoped to your business.
/api/v1/clientsSearch and paginate clients.
q | string | Full-text search on name, email, or phone. |
take | number | Page size (1–100, default 25). |
skip | number | Records to skip for pagination (default 0). |
GET /api/v1/clients?q=sara&take=10
Authorization: Bearer taanbook_sk_live_xxx
// Response
{
"data": [
{
"id": "clxnewclientid",
"name": "Sara López",
"email": "sara@example.com",
"phone": null,
"notes": null,
"tags": [],
"createdAt": "2026-06-20T08:00:00.000Z"
}
]
}/api/v1/clientsCreate a new client record.
namerequired | string | Full name (max 160 chars). |
email | string | Email address. |
phone | string | Phone number (min 3 chars). |
notes | string | Internal notes (max 5 000 chars). |
preferences | string | Client preferences (max 5 000 chars). |
tags | array | Array of { label, color? } tag objects. |
/api/v1/clients/{id}Retrieve a single client by ID.
Read the services (treatments, appointments types) your business offers.
/api/v1/servicesList all active services.
GET /api/v1/services
Authorization: Bearer taanbook_sk_live_xxx
// Response
{
"data": [
{
"id": "clxserviceid",
"name": "Corte de cabello",
"description": "Corte clásico con lavado",
"durationMinutes": 30,
"priceCents": 2500,
"currency": "EUR",
"color": "#5b6baa"
}
]
}Query open time slots for a service before creating an appointment.
/api/v1/availabilityReturn available booking slots for a service in a date range.
serviceIdrequired | string | ID of the service to check. |
fromrequired | ISO 8601 datetime | Start of window (UTC). |
torequired | ISO 8601 datetime | End of window (UTC). |
resourceId | string | Restrict to a specific staff member / resource. |
branchId | string | Restrict to a specific branch. |
GET /api/v1/availability
?serviceId=clxserviceid
&from=2026-07-15T00:00:00Z
&to=2026-07-15T23:59:59Z
Authorization: Bearer taanbook_sk_live_xxx
// Response
{
"data": [
{ "startsAt": "2026-07-15T09:00:00.000Z", "endsAt": "2026-07-15T09:30:00.000Z" },
{ "startsAt": "2026-07-15T10:00:00.000Z", "endsAt": "2026-07-15T10:30:00.000Z" },
{ "startsAt": "2026-07-15T11:00:00.000Z", "endsAt": "2026-07-15T11:30:00.000Z" }
]
}List endpoints that support pagination accept take (page size) and skip (offset) query parameters. The response data array length being less than take indicates the last page.
// Page 1 (first 25) GET /api/v1/clients?take=25&skip=0 // Page 2 (next 25) GET /api/v1/clients?take=25&skip=25
All /api/v1 endpoints share a limit of 200 requests per minute per API key. When the limit is exceeded the server returns 429 Too Many Requests. Implement exponential back-off and retry logic in your integration.
API keys are managed from the TaanBook dashboard: