/v2/bookings API returns "Instant bookings are only supported for team event types" even though frontend booking works

[JunaidHassanCB]

I'm running into an issue with the /v2/bookings endpoint in the Cal.com API.

When I attempt to create a booking for a 1-on-1 event type using this request:

POST https://api.cal.com/v2/bookings
Headers:
  Authorization: Bearer [REDACTED]
  Content-Type: application/json
  cal-api-version: 2024-08-13

Body:
{
  "attendee": {
    "language": "en",
    "name": "[REDACTED]",
    "email": "[REDACTED]",
    "timeZone": "Asia/Karachi",
    "phoneNumber": "[REDACTED]"
  },
  "start": "2025-08-01T10:30:00Z",
  "instant": true,
  "eventTypeId": [REDACTED]
}

I consistently get this error:

{
  "status": "error",
  "error": {
    "code": "BadRequestException",
    "message": "Instant bookings are only supported for team event types, not individual user event types."
  }
}

However, when I book the same slot through the Cal.com frontend, it works perfectly. I noticed the frontend is using:

POST https://cal.com/api/book/event

With a payload like this:

{
  "responses": {
    "name": "[REDACTED]",
    "email": "[REDACTED]",
    "location": {
      "value": "integrations:daily",
      "optionValue": ""
    },
    "guests": []
  },
  "user": "[REDACTED]",
  "start": "2025-08-04T11:30:00+05:00",
  "end": "2025-08-04T12:00:00+05:00",
  "eventTypeId": [REDACTED],
  "eventTypeSlug": "30min",
  "timeZone": "Asia/Karachi",
  "language": "en"
}

This suggests either:

• The public /v2/bookings endpoint has a stricter limitation or missing functionality.
• Or there's a discrepancy between how the public API and the internal/frontend API handle "instant" bookings for individual events.

🙋‍♂️ Questions:

1. Is there a way to use /v2/bookings to replicate the frontend booking behavior?
2. Is instant: true required or recommended for individual event types, or should we be using a different flow?

Any guidance on how to properly book an individual 1-on-1 slot via the public API would be appreciated.

Thanks!

[dosubot[bot]]

Hi @JunaidHassanCB! I'm Dosu and I’m helping the cal.com team.

The /v2/bookings API only allows "instant" bookings for team event types. If you include "instant": true for an individual (1-on-1) event type, you'll always get the error you described—this is enforced by the backend and is intentional, regardless of how the frontend works. The frontend endpoint (/api/book/event) doesn't use or require the "instant" flag for individual bookings, which is why it works there.

To book an individual 1-on-1 event via /v2/bookings, just omit the "instant" field from your payload. The booking will proceed as a standard booking if all other required fields are correct. Your payload should include at least: start (in UTC), an attendee object with name and email (or phone number), and either eventTypeId or both eventTypeSlug and username. If your event type has custom required fields, include them in bookingFieldsResponses as well. The attendee's time zone and language should be valid values (e.g., IANA time zone names) — strict validation applies citation.

So:

• Do not use "instant": true for individual event types in /v2/bookings citation.
• Use the standard booking flow and required fields only.
• If you get a 400 error, double-check that all required fields (including any custom ones) are present and correctly formatted citation.

This difference between the public API and the frontend/internal API is intentional and documented in the backend logic.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}