Microsoft Graph Bookings APIs now available on the v1 endpoint

Microsoft Graph team

We are pleased to announce that the current set of Bookings APIs will be moving from beta to v1 endpoint. We will continue to provide the core functionalities we offered in beta along with the new features which were introduced recently.  The new features were highlighted in a recent blog, and it gives our partners the capabilities such as SMS notifications, online meeting, custom questions, and group appointments. Our partners will also receive all the necessary support which Microsoft provides for v1 APIs.


The bookingBusiness is the parent entity of the other resource types in Bookings. There are no changes to the functionalities under this resource type, except for the Microsoft Graph endpoint.

The beta endpoint was

The new v1 endpoint is


The endpoint of the bookingService resource type has changed as well. Here is an example to illustrate the new v1 endpoint:



We have also changed the endpoint for the bookingStaffMember resource type. Here is an example to illustrate the new v1 endpoint:


Attribute removed in v1 from bookingStaffMember

The following attribute is not available in the v1 endpoint. This was very specific to our web application and was removed as it wasn’t relevant for API developers.

  • colorIndex


The endpoint for this resource type has changed. Here is an example to illustrate the new v1 endpoint:


Changes in customer Information

The customer information was available at the root node of bookingAppointment resource type. Now it moves under an attribute “customer” which is a collection of bookingCustomerInformation.

The difference can be seen in the two code snippets below.

Old structure of bookingAppointment

Content-type: application/json

    "@odata.context": "$metadata#bookingBusinesses('')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
    "customerName": "Jordan Miller",
    "customerEmailAddress": "",
    "customerPhone": "213-555-0199",
    "customerNotes": null,
    "serviceId": "57da6774-a087-4d69-b0e6-6fb82c339976",
    "serviceName": "Catered bento",

New structure of bookingAppointment

Content-type: application/json

    "@odata.context": "$metadata#bookingBusinesses('')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    "customers": [
            "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
            "customerName": "Jordan Miller",
            "customerEmailAddress": "",
            "customerPhone": "213-555-0199",
            "customerNotes": "notes",
            "customQuestionAnswers": [
                    "questionId": "75fc2eaf-624f-40b2-a289-63e51a56fcf2",
                    "question": "What's your favourite food",
                    "answerInputType": "radioButton",
                    "answerOptions": [
                    "isRequired": true,
                    "answer": "KFC",
                    "selectedOptions": ["KFC"]
            "customerLocation": {
                "displayName": "home",
                "locationEmailAddress": null,
                "locationUri": "",
                "locationType": null,
                "uniqueId": null,
                "uniqueIdType": null,
                "address": {
                    "type": "home",
                    "postOfficeBox": "",
                    "street": "",
                    "city": "",
                    "state": "",
                    "countryOrRegion": "",
                    "postalCode": ""
                "coordinates": {
                    "altitude": null,
                    "latitude": null,
                    "longitude": null,
                    "accuracy": null,
                    "altitudeAccuracy": null

The new complex type

The complex type is called bookingCustomerInformation. The “customers” attribute within appointment is a collection of this type.

Attribute Complex Type Description
Id bookingCustomerInformation The id of the customer
name bookingCustomerInformation The name of the customer
emailAddress bookingCustomerInformation The email address of the customer
phone bookingCustomerInformation The phone number of the customer
notes bookingCustomerInformation The notes of the customer
location bookingCustomerInformation The address of the customer. Location is of type physicalAddress. However only the “other” address type is supported.
timeZone bookingCustomerInformation The timeZone of the customer

Attributes removed in v1 from bookingAppointment

Since we don’t have payment or invoicing capabilities now, the following attributes won’t be available in v1:

  • invoiceAmount
  • invoiceDate
  • invoiceId
  • invoiceStatus
  • invoiceUrl

Attributes renamed in bookingAppointment

The following attributes have been renamed. The older attributes won’t be available in v1.

start Renamed to startDateTime
end Renamed to endDateTime


The end point for this resource type will change as well. An example to illustrate the new end point for v1 is given below.



We have changed the end point for bookingCurrency. An example to illustrate the new end point for v1 is given below.


Getting Started

We are really excited to launch the Bookings APIs on the v1 endpoint. Check out this link to find resources that will help you get started. We would love to hear your feedback so that we can help fulfill your use cases and requirements.

Happy coding!


Discussion is closed. Login to edit/delete existing comments.

  • Bart Vermeersch 0

    Thank you fo the update! Will the beta endpoints also be updated? Any idea by when?

    Are application permissions on the roadmap for this API (instead of delegated permissions)?


  • Mark Davies 0

    Using the SDK (Microsoft.Graph and Microsoft.Graph.Extensions Nuget V4.13 released on the same day), there appears to be no BookingsBusiness virtual method on GraphServiceClient. How do we use the SDK from on thev1.0 endpoint? Many thanks, Mark.

    • Jason Rea 0

      It’s under


      now. 🙂

  • Gábor Belicza 0

    Good to see bookings has a live API!
    I have a problem, when I list all bookingAppointment in calendarview within a given range, the Customer arrays in every bookingAppointment are always empty!
    Same results when I try with /appointments endpoint, there are no bookingCustomerInformation objects in bookingAppointment’s customer array.
    I using mainly Graph C# SDK, but this is reproducable within Graph Explorer.

Feedback usabilla icon