When creating a booking via the `/v2/bookings` endpoint, the API returns a `400 BAD_REQUEST` error with the message: responses - {title}error_required_field

[thesohailjafri]

Issue Summary

When creating a booking via the /v2/bookings endpoint, the API returns a 400 BAD_REQUEST error with the message:

responses - {title}error_required_field

Even when all required fields appear to be provided, the API does not accept the request and gives no clear documentation that "title" is a required field at the root booking level, not inside attendee.

This contradicts the API documentation and causes booking failures.

Steps to Reproduce

1. Send a POST request to /v2/bookings or https://cal.com/docs/api-reference/v2/bookings/create-a-booking?playground=open
2. Include valid booking data including:
   • start
   • attendee (name, email, phone, timezone, language)
   • eventTypeId
3. API responds with a 400 error asking for a missing "title" field

Example request used:

curl --request POST \
  --url https://api.cal.com/v2/bookings \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: 2024-08-13' \
  --data '{
  "start": "2025-11-10T17:30:00.000Z",
  "attendee": {
    "name": "Sohail",
    "email": "sohail@gmail.com",
    "timeZone": "America/Chicago",
    "phoneNumber": "+13125557890",
    "language": "en"
  },
  "eventTypeId": 3799201
}'

Actual Results

• Booking creation fails
• Server returns:

400 BAD_REQUEST
responses - {title}error_required_field

• Error response does not clarify where "title" should be placed

Expected Results

• Booking should be successfully created or
• Error message should clearly indicate:
  • "title" is required
  • "title" should be at the root booking level
• API documentation should reflect correct required fields and structure

Technical Details

• API: Cal.com /v2/bookings
• Timestamp: 2025-11-02T18:13:12.905Z
• Headers:
  • Content-Type: application/json
  • cal-api-version: 2024-08-13
• Environment:
  • Node.js automation (n8n server)
  • Also reproduced via Postman and cURL

Backend error received:

{"status":"error","timestamp":"2025-11-02T18:13:12.905Z","path":"/v2/bookings","error":{"code":"BAD_REQUEST","message":"responses - {title}error_required_field, "}}

Evidence

• Reproducible from multiple clients (n8n, Postman, cURL)
• Valid JSON structure confirmed
• Attached server error logs
• Booking fails despite required fields present

Additional Context

• This issue is blocking production automation for an AI-powered voice receptionist booking system
• "title" field are not documented as required for /v2/bookings
• Suggested improvements:
  • Update API documentation to reflect required fields
  • Include clear path to missing property in error response

[linear]

CAL-6678

[CarinaWolli]

cc @JDP-Neo

[dfordp]

@thesohailjafri

Inside the main service from where you calling the cal.com service you can basically pass a title booking which will help in your issue like this based on the schema

{
  "title": "Consultation with Sohail",   // ✅ add here
  "start": "2025-11-10T17:30:00.000Z",
  "attendee": {
    "name": "Sohail",
    "email": "sohail@gmail.com",
    "timeZone": "America/Chicago",
    "phoneNumber": "+13125557890",
    "language": "en"
  },
  "eventTypeId": 3799201
}

I will raise a pr adding it to the documentation

[thesohailjafri]

Ok will check if it helps or not

[thesohailjafri]

{
  "status": "error",
  "timestamp": "2025-11-04T12:59:30.132Z",
  "path": "/v2/bookings",
  "error": {
    "code": "BadRequestException",
    "message": "title property is wrong, property title should not exist",
    "details": {
      "message": "title property is wrong, property title should not exist",
      "error": "Bad Request",
      "statusCode": 400
    }
  }
}

this error is thrown

[thesohailjafri]

this error I think was not defined in schema validation, I think is happening in the controller

[thesohailjafri]

@CarinaWolli can you please mark it as High-Priority as it will brake application build over the create booking function, I myself is facing issue with this in two different prod workflows

[dfordp]

First error was not seeing it in the schema validation

2nd one was form data validation on backend

[dfordp]

After digging into the code and database schema, it looks like the title field for a booking isn’t meant to come from the request body at all it’s automatically inherited from the EventType that the booking is created from.

Here’s what’s happening under the hood:

• The Prisma Booking model defines title as a required non-null field:

model Booking {
  id      Int     @id @default(autoincrement())
  eventTypeId Int?
  title   String  // required
  ...
}

• However, the public API input type (CreateBookingInput_2024_08_13) doesn’t include a title field, so clients can’t (and shouldn’t) send it.

The API layer is supposed to populate booking.title automatically from the corresponding EventType.title during booking creation.

This means if the API receives a valid eventTypeId that actually exists in the database, the backend should automatically fill in the title.
But suppose the provided eventTypeId doesn’t exist (for example, an ID from another environment like app.cal.com instead of the local DB). In that case, no EventType is found , and the API ends up trying to insert a booking without a title, triggering the error:

responses - {title}error_required_field

If that returns 404 or empty, it means the event type doesn’t exist in the local instance, so the title can’t be resolved.

Improve the API error message to clarify when an invalid eventTypeId causes a missing title.

[supalarry]

@thesohailjafri the issue is that event type has a booking field that is required when booking but the value for it is not provided when booking.

I checked event type 3799201 in database and it has the following bookingField

{
        "name": "title",
        "type": "text",
        "hidden": false,
        "sources": [
          {
            "id": "default",
            "type": "default",
            "label": "Default"
          }
        ],
        "editable": "system-but-optional",
        "required": true,
        "defaultLabel": "what_is_this_meeting_about",
        "defaultPlaceholder": ""
      },

As you see it has "required" : true set meaning that it must be presetn when booking

You either have to:

1. Set it as required false - you can do it manually via cal web app or api https://cal.com/docs/api-reference/v2/event-types/update-an-event-type#body-booking-fields
2. Provide title when booking under bookingFieldsResponses https://cal.com/docs/api-reference/v2/bookings/create-a-booking#body-booking-fields-responses

bookingFieldsResponses": {
    "title": "some title"
},

I tried that

curl --request POST \
  --url https://api.cal.com/v2/bookings \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: 2024-08-13' \
  --data '{
  "start": "2025-11-10T17:30:00.000Z",
  "attendee": {
    "name": "Sohail",
    "email": "sohail@gmail.com",
    "timeZone": "America/Chicago",
    "phoneNumber": "+13125557890",
    "language": "en"
  },
  "eventTypeId": 3799201,
  "bookingFieldsResponses": {
    "title": "some title"
  }
}'

and then got a new error

{
  "status": "error",
  "timestamp": "2025-11-05T15:26:30.766Z",
  "path": "/v2/bookings",
  "error": {
    "code": "BAD_REQUEST",
    "message": "responses - {aiAgentCallPhoneNumber}error_required_field, "
  }
}

so you then need to add it to booking fields responses and so on

  "bookingFieldsResponses": {
    "title": "some title",
    "aiAgentCallPhoneNumber": "+37228222222"
  }

so you see you must provide all required booking field values.

However, the error message could be clearer so I will work on refactoring that to give what i just wrote above but within api response. I assume that my answer resolves the issue and will close this pr issue - feel free to re-open if needed : )