API Reference

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.

Base URL: https://taanbook.com/api/v1Rate limit: 200 req / minFormat: JSON

Authentication

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

API keys grant full read/write access to your tenant data. Keep them secret — never expose them in client-side code or public repositories.

Response format

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

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

Appointments

Create and query appointments for your business.

GET/api/v1/appointments

List appointments in a date range.

Query parameters

`from`required	ISO 8601 date	Start of the range (inclusive).
`to`required	ISO 8601 date	End of the range (inclusive).
`resourceId`	string	Filter by staff/resource ID.
`clientId`	string	Filter by client ID.

Example

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"
    }
  ]
}

POST/api/v1/appointments

Create a new appointment.

Request body

`serviceId`required	string	ID of the service to book.
`startsAt`required	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).

Example

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"
  }
}

GET/api/v1/appointments/{id}

Retrieve a single appointment by ID.

GET /api/v1/appointments/clx9z8y7x6w5v4u3t2s1r
Authorization: Bearer taanbook_sk_live_xxx

Clients

Manage your client/contact list. All client data is scoped to your business.

GET/api/v1/clients

Search and paginate clients.

Query parameters

`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"
    }
  ]
}

POST/api/v1/clients

Create a new client record.

Request body

`name`required	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.

GET/api/v1/clients/{id}

Retrieve a single client by ID.

Services

Read the services (treatments, appointments types) your business offers.

GET/api/v1/services

List 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"
    }
  ]
}

Availability

Query open time slots for a service before creating an appointment.

GET/api/v1/availability

Return available booking slots for a service in a date range.

Query parameters

`serviceId`required	string	ID of the service to check.
`from`required	ISO 8601 datetime	Start of window (UTC).
`to`required	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" }
  ]
}

Pagination

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

Rate limiting

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.

Getting an API key

API keys are managed from the TaanBook dashboard:

Log in to your TaanBook account.
Go to Dashboard → Settings and scroll to the API Keys section.
Click Create key, give it a name, and copy the key immediately — it is shown only once.
To revoke a key, click the delete icon next to it. Revoked keys stop working instantly.

Getting your schedule ready...

TaanBookAPI Reference

API Reference

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.

Base URL: https://taanbook.com/api/v1Rate limit: 200 req / minFormat: JSON

Authentication

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

API keys grant full read/write access to your tenant data. Keep them secret — never expose them in client-side code or public repositories.

Response format

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

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

Appointments

Create and query appointments for your business.

GET/api/v1/appointments

List appointments in a date range.

Query parameters

`from`required	ISO 8601 date	Start of the range (inclusive).
`to`required	ISO 8601 date	End of the range (inclusive).
`resourceId`	string	Filter by staff/resource ID.
`clientId`	string	Filter by client ID.

Example

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"
    }
  ]
}

POST/api/v1/appointments

Create a new appointment.

Request body

`serviceId`required	string	ID of the service to book.
`startsAt`required	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).

Example

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"
  }
}

GET/api/v1/appointments/{id}

Retrieve a single appointment by ID.

GET /api/v1/appointments/clx9z8y7x6w5v4u3t2s1r
Authorization: Bearer taanbook_sk_live_xxx

Clients

Manage your client/contact list. All client data is scoped to your business.

GET/api/v1/clients

Search and paginate clients.

Query parameters

`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"
    }
  ]
}

POST/api/v1/clients

Create a new client record.

Request body

`name`required	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.

GET/api/v1/clients/{id}

Retrieve a single client by ID.

Services

Read the services (treatments, appointments types) your business offers.

GET/api/v1/services

List 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"
    }
  ]
}

Availability

Query open time slots for a service before creating an appointment.

GET/api/v1/availability

Return available booking slots for a service in a date range.

Query parameters

`serviceId`required	string	ID of the service to check.
`from`required	ISO 8601 datetime	Start of window (UTC).
`to`required	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" }
  ]
}

Pagination

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

Rate limiting

Getting an API key

API keys are managed from the TaanBook dashboard:

Log in to your TaanBook account.
Go to Dashboard → Settings and scroll to the API Keys section.
Click Create key, give it a name, and copy the key immediately — it is shown only once.
To revoke a key, click the delete icon next to it. Revoked keys stop working instantly.

API Reference — TaanBook — TaanBook