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.

bookingBusiness

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 https://graph.microsoft.com/beta/bookingBusinesses/

The new v1 endpoint is https://graph.microsoft.com/v1.0/solutions/bookingBusinesses

bookingService

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

GET https://graph.microsoft.com/v1.0/solutions/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/services

bookingStaffMember

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

GET https://graph.microsoft.com/v1.0/solutions/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/staffMembers

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

bookingAppointment

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

GET https://graph.microsoft.com/v1.0/solutions/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/appointments/AAMkADKnAAA=

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": "https://graph.microsoft.com/beta/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
    "customerName": "Jordan Miller",
    "customerEmailAddress": "jordanm@contoso.com",
    "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": "https://graph.microsoft.com/beta/$metadata#bookingBusinesses('Contosolunchdelivery%40M365B489948.onmicrosoft.com')/appointments/$entity",
    "id": "AAMkADKnAAA=",
    "selfServiceAppointmentId": "00000000-0000-0000-0000-000000000000",
    ...
    ...
    ...
   
    "customers": [
        {
            "customerId": "7ed53fa5-9ef2-4f2f-975b-27447440bc09",
            "customerName": "Jordan Miller",
            "customerEmailAddress": "jordanm@contoso.com",
            "customerPhone": "213-555-0199",
            "customerNotes": "notes",
            "customQuestionAnswers": [
                {
                    "questionId": "75fc2eaf-624f-40b2-a289-63e51a56fcf2",
                    "question": "What's your favourite food",
                    "answerInputType": "radioButton",
                    "answerOptions": [
                        "KFC",
                        "McDonald's",
                        "BurgerKing"
                    ],
                    "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

bookingCustomer

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

GET https://graph.microsoft.com/v1.0/solutions/bookingBusinesses/Contosolunchdelivery@M365B489948.onmicrosoft.com/customers

bookingCurrency

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

GET https://graph.microsoft.com/v1.0/solutions/bookingCurrencies

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!

4 comments

Comments are closed. Login to edit/delete your existing comments

  • Bart Vermeersch

    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)?

    Bart

  • Mark Davies

    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

      It’s under

      GraphServiceClient.Solutions.BookingBusinesses

      now. 🙂

  • Gábor Belicza

    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.