Edit

Share via

Use the Microsoft Bookings API in Microsoft Graph for shared bookings

  • Article

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Microsoft Bookings lets enterprise organization and small business owners manage customer bookings and information with minimal setup. A business owner can create one or more businesses, with each business offering a set of services. The owner can set up staff members, and specify the services that each staff member performs. A customer can book an appointment for a specific service in that business in an online or mobile app. Bookings ensures that the appointment time is kept up-to-date for the business, staff members, and customers involved.

Important

The Microsoft Bookings API in Microsoft Graph applies only to shared bookings. The API is not applicable for personal bookings.

Programmatically, a bookingBusiness in the Bookings API involves the following objects:

Using the Bookings REST API

Walk through the following steps before booking customer appointments for a business the first time. Make sure you provide the appropriate access tokens for the corresponding operations.

  1. Make sure the business has an Microsoft 365 Business Premium subscription.
  2. Create a new bookingBusiness by sending a POST operation to the entity set. At minimum, you should specify a name for the new business that customers will see:
POST https://graph.microsoft.com/beta/bookingBusinesses
Authorization: Bearer {access token}
Content-Type: application/json

{
    "displayName":"Contoso"
}

Use the id property of the new bookingBusiness returned in the POST response to continue to customize business settings, and add staff members and services for the business.

  1. Add individual staff members for the business:
POST https://graph.microsoft.com/beta/bookingBusinesses/{id}/staffMembers
Authorization: Bearer {access token}
Content-Type: application/json

{
    "displayName":"Dana Swope",
    "emailAddress": "danas@contoso.com",
    "role": "externalGuest"
}
  1. Define each service offered by the business:
POST https://graph.microsoft.com/beta/bookingBusinesses/{id}/services
Authorization: Bearer {access token}
Content-Type: application/json

{
    "displayName":"Bento"
}
  1. Publish the scheduling page for the business, to let customers and business operators start booking appointments:
POST https://graph.microsoft.com/beta/bookingBusinesses/{id}/publish
Authorization: Bearer {access token}

In general, to list all the booking businesses in the Microsoft 365 tenant:

GET https://graph.microsoft.com/beta/bookingBusinesses
Authorization: Bearer {access token}

Common use cases

The following table lists the common operations for a business in the Bookings API.

Use cases REST resources See also
Create, get, update, or delete a business bookingBusiness Methods of bookingBusiness
Update the scheduling policy bookingSchedulingPolicy Update a bookingBusiness
Add, get, update, or delete staff members bookingStaffMember Methods of bookingStaffMember
Add, get, update, or delete services bookingService Methods of bookingService
Publish or unpublish the scheduling page bookingBusiness publish
unpublish
Create, get, update, delete, or cancel an appointment bookingAppointment Methods of bookingAppointment
Get appointments in a date range bookingBusiness List Bookings calendarView
Get currency bookingCurrency Methods of bookingCurrency

Related content