Bookafy MCP by usefulapi

The account this API key belongs to: the admin user's email. Use it to confirm which Bookafy account is connected. GET /api/v3/me.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the appointments of ONE staff member (identified by their email: take it from bookafy_list_staff), newest first, optionally within a UTC date range. Each item has the service, customer, start/end time (UTC), title, price, duration and status. Page with page/per_page (default 25). Cancel/reschedule tokens are never returned. GET /api/v3/appointments.

{
  "type": "object",
  "properties": {
    "staff_email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Email of the staff user whose appointments to list (from bookafy_list_staff)."
    },
    "from": {
      "description": "Only appointments starting at or after this moment: yyyy-mm-dd (midnight UTC) or ISO 8601 date-time with timezone.",
      "type": "string"
    },
    "to": {
      "description": "Only appointments ending before this moment: yyyy-mm-dd (midnight UTC) or ISO 8601 date-time with timezone.",
      "type": "string"
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "per_page": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "required": [
    "staff_email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: book an appointment for a customer with a staff member and service (ids from bookafy_list_staff and bookafy_list_services). The customer is created from the given name/email/phone. Bookafy may email the booking confirmation to the customer and add the event to connected calendars, so only call it when the user clearly asked to book. Times are converted to UTC. POST /api/v3/appointments.

{
  "type": "object",
  "properties": {
    "staff_user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Staff user id (from bookafy_list_staff)."
    },
    "service_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Service id assigned to that staff user (from bookafy_list_services)."
    },
    "start": {
      "type": "string",
      "description": "Start, ISO 8601 date-time with timezone, e.g. 2026-11-02T09:30:00-05:00."
    },
    "end": {
      "type": "string",
      "description": "End, ISO 8601 date-time with timezone (after start, at most 24 h later)."
    },
    "customer_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Customer's full name."
    },
    "customer_email": {
      "description": "Customer's email (the confirmation goes there).",
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "customer_phone": {
      "description": "Customer's phone number.",
      "type": "string",
      "minLength": 3,
      "maxLength": 40
    },
    "custom_fields": {
      "description": "Custom booking-form answers as {field_name: value}, with underscores for spaces, e.g. {\"What_is_your_DOB\": \"1990\"}.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]{1,60}$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "title": {
      "description": "Title shown for the appointment (default: Bookafy's own).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "description": "Notes shown with the appointment.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "price": {
      "description": "Price of the appointment (default: the service's price).",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "required": [
    "staff_user_id",
    "service_id",
    "start",
    "end",
    "customer_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: reschedule or edit an existing appointment. Send the required staff, service, new times and customer name — read current values with bookafy_list_appointments first. Omitted optional fields are not sent. The customer may be notified of the change. Times are converted to UTC. PUT /api/v3/appointments/{id}.

{
  "type": "object",
  "properties": {
    "appointment_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Appointment id (from bookafy_list_appointments)."
    },
    "staff_user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Staff user the appointment is with."
    },
    "service_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Service id."
    },
    "start": {
      "type": "string",
      "description": "New start, ISO 8601 date-time with timezone."
    },
    "end": {
      "type": "string",
      "description": "New end, ISO 8601 date-time with timezone (after start, at most 24 h later)."
    },
    "customer_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Customer's full name."
    },
    "customer_email": {
      "description": "Customer's email.",
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "customer_phone": {
      "description": "Customer's phone number.",
      "type": "string",
      "minLength": 3,
      "maxLength": 40
    },
    "custom_fields": {
      "description": "Custom booking-form answers as {field_name: value}, with underscores for spaces, e.g. {\"What_is_your_DOB\": \"1990\"}.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]{1,60}$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "title": {
      "description": "Appointment title.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "description": "Notes shown with the appointment.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "price": {
      "description": "Price of the appointment.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "required": [
    "appointment_id",
    "staff_user_id",
    "service_id",
    "start",
    "end",
    "customer_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, IRREVERSIBLE: delete (cancel) an appointment. Bookafy may notify the customer and remove the event from connected calendars, and the appointment cannot be restored through the API. Only call it when the user explicitly asked to cancel this appointment. DELETE /api/v3/appointments/{id}.

{
  "type": "object",
  "properties": {
    "appointment_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Appointment id (from bookafy_list_appointments)."
    },
    "staff_user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Staff user the appointment is with (its user_id)."
    }
  },
  "required": [
    "appointment_id",
    "staff_user_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the account's customers (id, name, email, phone and custom booking-form answers). Bookafy returns the whole list at once; use `search` (matches name, email or phone) and `limit`/`offset` to page through it. GET /api/v3/customers.

{
  "type": "object",
  "properties": {
    "search": {
      "description": "Only customers whose name, email or phone contains this text (case-insensitive).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "limit": {
      "description": "Most customers to return, 1-500 (default 100).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "offset": {
      "description": "Skip this many matches (default 0). Pass the previous reply's next_offset to read on.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add a customer record (name required; email, phone and custom booking-form answers optional). It does not book anything. POST /api/v3/customers.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Customer's full name."
    },
    "email": {
      "description": "Customer's email.",
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "phone": {
      "description": "Customer's phone number.",
      "type": "string",
      "minLength": 3,
      "maxLength": 40
    },
    "custom_fields": {
      "description": "Custom booking-form answers as {field_name: value}, with underscores for spaces, e.g. {\"What_is_your_DOB\": \"1990\"}.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]{1,60}$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change a customer's details. Bookafy needs the name every time, so pass the current name when you only change the email or phone. Fields you leave out are not sent. PUT /api/v3/customers/{id}.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Customer id (from bookafy_list_customers)."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Customer's full name (required by Bookafy on every update)."
    },
    "email": {
      "description": "New email.",
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "phone": {
      "description": "New phone number.",
      "type": "string",
      "minLength": 3,
      "maxLength": 40
    },
    "custom_fields": {
      "description": "Custom booking-form answers as {field_name: value}, with underscores for spaces, e.g. {\"What_is_your_DOB\": \"1990\"}.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_]{1,60}$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    }
  },
  "required": [
    "customer_id",
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List every service (appointment type) with id, name, price, duration, buffers, category, scheduling mode and online-meeting options. Use the ids when booking. GET /api/v3/services.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The appointment types grouped by category, each with its public booking-page link — use it to give a customer the link to book themselves. GET /api/v3/appointment_types.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the staff users (id, name, email, booking-page URL). Use the id or email for appointments. GET /api/v3/staff_members.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List classes and one-off appointments with price, duration, location, seats, booking link and their sessions (date, seats total/filled/remaining, zoom link). GET /api/v3/classes.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One class with its sessions and the attendees booked on each (name, email, phone, booking time). Optional filters narrow the sessions. GET /api/v3/classes/{id}.

{
  "type": "object",
  "properties": {
    "class_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Class id (from bookafy_list_classes)."
    },
    "price": {
      "description": "Only sessions with this price.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000
    },
    "duration": {
      "description": "Only sessions of this length in minutes.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "attendee_name": {
      "description": "Only sessions with an attendee of this name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "provider_name": {
      "description": "Only sessions run by this provider.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "from": {
      "description": "Only sessions starting at or after this moment (yyyy-mm-dd or ISO 8601 date-time with timezone).",
      "type": "string"
    },
    "to": {
      "description": "Only sessions ending before this moment (yyyy-mm-dd or ISO 8601 date-time with timezone).",
      "type": "string"
    }
  },
  "required": [
    "class_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The attendees of one class session (name, email, phone). Get session ids from bookafy_list_classes. GET /api/v3/sessions.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Session id (sessionId in bookafy_list_classes)."
    }
  },
  "required": [
    "session_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the webhook subscriptions (id, callback URL, event type such as appointment_created or customer_updated). Read-only. GET /api/v3/api_subscriptions.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}