Microsoft Graph Bookings API returns UnknownError when creating appointment with more than 4 customers

Update after additional testing

I performed some additional tests with 5 customers/participants in the customers array.

At one point, I was able to successfully create a booking appointment with 5 participants using the same endpoint:

POST https://graph.microsoft.com/v1.0/solutions/bookingBusinesses/{bookingBusinessId}/appointments

However, when I tried again with the same scenario, the request failed again with the same UnknownError.

This suggests that the issue may not be a documented limit of 4 customers per appointment, because I was able to create an appointment with 5 customers successfully at least once.

The behavior appears to be intermittent. The same request structure, with the same serviceId, staffMemberIds, maximumAttendeesCount, date/time configuration, and valid existing customers, sometimes succeeds and sometimes fails with:

{
  "error": {
    "code": "UnknownError",
    "message": "",
    "innerError": {
      "date": "2026-04-29T11:16:21",
      "request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "client-request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

Based on this new test, it looks more like an internal instability or intermittent backend issue in the Microsoft Graph Bookings API rather than a validation issue in the request payload.

Could someone from Microsoft please investigate this using the request-id and timestamp from the failed requests?

The main points are:

• Creating appointments with up to 4 customers works consistently.
• Creating appointments with 5 customers sometimes works.
• The same or equivalent request with 5 customers sometimes fails with UnknownError.
• maximumAttendeesCount is set to 100 both in the service and in the appointment payload.
• All customers already exist in the Booking Calendar and have valid customerId values.
• The error response does not include a detailed message, only UnknownError.

This intermittent behavior makes it difficult to identify any issue in the request payload itself.

Mason, Richard (LatAm)

Thank you for reaching out to Microsoft Q&A.

There is no officially documented “4 customers” hard limit in Microsoft Graph Bookings. However, a Bookings appointment supports only one primary customer, and the customers[] array is not designed for multi‑attendee group bookings.

When you pass more than 4 customers, the backend fails validation and returns a generic UnknownError, which is a known service‑side limitation/bug, not a client issue.

Why This Happens

Microsoft Bookings has two different concepts that often get confused:

1. Appointment ownership (Customer model)

A booking appointment is owned by exactly one customer

This is represented by:

customerEmailAddress

customerName

2. Attendance capacity (Service model)

maximumAttendeesCount applies to:

Self‑service bookings

Group bookings created through the Bookings UI

It does NOT mean the Graph API supports adding many customers programmatically

The customers[] array exists mainly to:

Store basic references

Support Forwarded / secondary contacts

Maintain compatibility with legacy flows

It is not equivalent to “meeting attendees” in Outlook / Calendar APIs.

What Microsoft Grap Supports

From Microsoft documentation:

Booking Appointment resource

“A booking appointment has one customer and optionally references others.”

Source:

https://learn.microsoft.com/en-us/graph/api/resources/bookingappointment?view=graph-rest-1.0

BookingCustomerInformation

“Represents customer information associated with a booking appointment.”

There is no guarantee of multi‑customer transactional support.

https://learn.microsoft.com/en-us/graph/api/resources/bookingcustomerinformation?view=graph-rest-1.0

Why the Error Is UnknownError

Microsoft Graph returns UnknownError when:

Backend validation fails after request parsing

The Bookings service encounters an unsupported internal state

The failure is not mapped to a public error contract

This is documented generically here:

https://learn.microsoft.com/graph/errors

Some services may return UnknownError when an internal invariant is violated.

Why It Works Up to 4 Customers

This is not a supported guarantee — it’s an artifact of backend tolerance, likely:

Cached object limits

Partial serialization allowance

Legacy UI compatibility

4 working ≠ supported

Microsoft does not guarantee success beyond a single customer, regardless of:

maximumAttendeesCount

Service configuration

UI behavior

Below is the recommended solution:-

1. Use ONE customer per appointment

"customerEmailAddress": "primary@example.com",

"customerName": "Primary Customer"

Track additional attendees:

In custom fields

In notes / labels

In your application database

2.(Group bookings – Correct Model)

If you need true multi‑attendee sessions:

• Create multiple appointments under the same service
• Or allow customers to book themselves using the Bookings UI

Group bookings are designed for:

• Self‑service flows
• UI‑controlled capacity
• Not Graph bulk customer injection

3 (Online meeting workaround)

If your scenario is meeting‑based:

Create an Online Meeting (Graph /onlineMeetings)

Then associate the booking with the meeting link

Manage attendees via Outlook / Teams

Not Recommended

Relying on customers[] for group attendance

Assuming maximumAttendeesCount applies to API‑created appointments

Expecting detailed error messages for Bookings backend failures

Important: There is no documented limit of “4 customers”, but Microsoft Bookings appointments created via Microsoft Graph officially support only one customer per appointment.

The customers array is not intended for group bookings and exceeding a small internal threshold can cause the Bookings backend to fail with UnknownError.

maximumAttendeesCount applies to Bookings UI‑based group bookings, not to programmatic multi‑customer appointment creation.

This is a service‑side limitation/behavior, not an issue with request payload structure or permissions.