VX Agents

API directory · Booking & Scheduling

Microsoft Bookings Appointments

v1.0.0 · 13 endpoints · 0 connections · shared by vx.ai

For salons, spas and clinics that take bookings through Microsoft 365: see the day's calendar, check which staff are free, book a customer into a service, reschedule or cancel with a message, and keep the customer list current in Microsoft Bookings via Graph.

Connect this API to an AI agent Browse all specs

What you can do with Microsoft Bookings Appointments via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /solutions/bookingBusinesses listBookingBusinesses List the Bookings calendars (businesses) you can access
GET /solutions/bookingBusinesses/{bookingBusiness-id} getBookingBusiness Get a business's hours, address and booking settings
GET /solutions/bookingBusinesses/{bookingBusiness-id}/services listServices List the services customers can book, with duration and price
GET /solutions/bookingBusinesses/{bookingBusiness-id}/staffMembers listStaffMembers List staff members and their roles
POST /solutions/bookingBusinesses/{bookingBusiness-id}/getStaffAvailability getStaffAvailability Check when given staff members are free or busy
GET /solutions/bookingBusinesses/{bookingBusiness-id}/calendarView listCalendarView List appointments between a start and end time
GET /solutions/bookingBusinesses/{bookingBusiness-id}/appointments listAppointments List all appointments of a business
POST /solutions/bookingBusinesses/{bookingBusiness-id}/appointments createAppointment Book a customer into a service with a staff member
GET /solutions/bookingBusinesses/{bookingBusiness-id}/appointments/{bookingAppointment-id} getAppointment Get one appointment
PATCH /solutions/bookingBusinesses/{bookingBusiness-id}/appointments/{bookingAppointment-id} updateAppointment Reschedule or change an appointment
POST /solutions/bookingBusinesses/{bookingBusiness-id}/appointments/{bookingAppointment-id}/cancel cancelAppointment Cancel an appointment and message the customer
GET /solutions/bookingBusinesses/{bookingBusiness-id}/customers listCustomers List the business's customers
POST /solutions/bookingBusinesses/{bookingBusiness-id}/customers createCustomer Add a new customer

Authentication

microsoftOAuth

OAuth 2.0

Scopes: https://graph.microsoft.com/Bookings.Read.All https://graph.microsoft.com/BookingsAppointment.ReadWrite.All offline_access

How to get a credential

  1. Sign in to the Microsoft Entra admin center (entra.microsoft.com) with an account in the Microsoft 365 tenant that uses Bookings.
  2. Go to App registrations → New registration, choose the supported account types and add the VX Agents redirect URI shown on the credential form (platform Web).
  3. Under Certificates & secrets, create a client secret and copy its value.
  4. Under API permissions → Microsoft Graph → Delegated, add the scopes below (an admin may have to grant consent).
  5. Enter the Application (client) ID and secret in VX Agents and sign in with a user who is a staff member or admin of the Bookings calendar.

Permissions used

Scope Operations
Bookings.Read.All listBookingBusinesses, getBookingBusiness, listServices, listStaffMembers, getStaffAvailability, listCalendarView, listAppointments, getAppointment, listCustomers
BookingsAppointment.ReadWrite.All createAppointment, updateAppointment, cancelAppointment, createCustomer
offline_access refresh tokens

Common errors

  • 401 Unauthorized: the token expired; reconnect the credential.
  • 403 Forbidden: consent missing for a scope above, or the signed-in user is not a member of that Bookings business.
  • 400 Bad Request: a date-time without timeZone, or start/end missing on listCalendarView.
  • 429 Too Many Requests: Graph throttling; wait for Retry-After.

Store it as a VX Agents OAuth2 credential.

Usage guide

Setup

  • Credential: Microsoft identity OAuth2 (authorization code) with Bookings.Read.All, BookingsAppointment.ReadWrite.All and offline_access. Sign in as a staff member or admin of the Bookings calendar.
  • Worth pinning: bookingBusiness-id (from listBookingBusinesses; it looks like an email address, e.g. [email protected]).

Book, reschedule or cancel

  1. listBookingBusinesses → pick the business; getBookingBusiness for its business hours and time zone.
  2. listServices for service ids, durations and prices; listStaffMembers for staff ids.
  3. getStaffAvailability with staffIds and startDateTime / endDateTime objects ({"dateTime": "2026-10-20T09:00:00", "timeZone": "Pacific Standard Time"}) to find free slots.
  4. listCalendarView with start and end (ISO 8601, e.g. 2026-10-20T00:00:00Z) to see what is already booked that day.
  5. listCustomers to find the customer; createCustomer with displayName and emailAddress if they are new. Send "@odata.type": "#microsoft.graph.bookingCustomer".
  6. createAppointment with serviceId, staffMemberIds, startDateTime, endDateTime and customers: [{"@odata.type": "#microsoft.graph.bookingCustomerInformation", "customerId": "...", "name": "...", "emailAddress": "..."}].
  7. Reschedule with updateAppointment (new start/end); cancel with cancelAppointment and a cancellationMessage the customer receives.

Always confirm with the user before createAppointment, updateAppointment, cancelAppointment or createCustomer: they notify customers and change the shared calendar.

Good to know

  • Date-times on appointments and availability are {dateTime, timeZone} objects; use the business's time zone.
  • listCalendarView requires both start and end; prefer it over listAppointments for a date range.
  • Supports OData $top, $skip, $filter, $select on list calls; follow @odata.nextLink for more pages.
  • price and priceType on an appointment default from the service.
  • Bookings needs a Microsoft 365 Business Standard/Premium (or similar) licence.
  • On 429, wait for Retry-After.

Source: Microsoft Graph Bookings API reference (https://learn.microsoft.com/en-us/graph/api/resources/booking-api-overview?view=graph-rest-1.0), checked 2026-10-19.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Microsoft Bookings Appointments” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Outlook Calendar (Microsoft Graph) — Find a time that works, then book it in Outlook: check colleagues' free/busy with getSchedule or let findMeetingTimes s…
  • Cliniko Appointments & Availability — For physio, chiro and allied-health clinics on Cliniko: find the next open slot for a practitioner and appointment type…
  • Zoom Scheduler Bookings — For consultants, clinics and sales teams that share Zoom Scheduler booking pages: find open slots on a schedule, book a…
  • Zoom Meetings — Let an agent schedule and manage Zoom meetings: list a user's upcoming meetings, create, reschedule or cancel meetings,…
  • Calendly Bookings & Availability — For salons, clinics and consultants who take bookings through Calendly: check open slots for an event type, see who boo…
  • Google Calendar Events — Let an agent schedule on Google Calendar: list calendars, read upcoming events and recurring instances, check free/busy…