> For the complete documentation index, see [llms.txt](https://docs.cubu.com/guides/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cubu.com/guides/s2s-api-guide/appointments-management-api/book-appointment.md).

# Book Appointment

Books a new appointment in a calendar.

{% hint style="info" %}
This endpoint requires the **Appointments Manager**  role**.**
{% endhint %}

## URL

{% code overflow="wrap" %}

```
POST: https://[base-url]/{applicationId}/calendars/{serviceId}/{date}/{cuIndex}/appointments
```

{% endcode %}

## Headers

```
Authorization: Bearer <accessToken>
```

## Route Params <a href="#route-params" id="route-params"></a>

* **serviceId**: GUID, required.
* **date**: date in `YYYY-MM-dd` format; required.
* **cuIndex**: the calendar's unique identifier

## Input Params <a href="#input-params" id="input-params"></a>

* **serviceTypeId**: (GUID) is the service type for which to book an appointment.
* **startTime**: appointment start time is the number of minutes that have elapsed since midnight. This value must correspond to a vacant time slot.
* **language** (optional): the preferred communication language. It must be one of the languages supported by the organization. Leave empty to use the default language.
* **cusotmerRecordId** (optional): the customer this appointment is booked for. Required if the service was configured to require customer ID.
* **contactPhoneNumber** (optional): the phone number used to communicate with the customer regarding this case. Required if the service was configured to require a phone number.\
  The value must be a valid ISO-formatted 10-digit phone number.
* **contactEmail** (optional): the email used to communicate with the customer in this case. Required if the service was configured to require an email.
* **channel**: FaceToFace | Video | Phone - the communication channel for customer service. The service type must support the selected channel.
* **bypassTimeslotCheck**: Boolean; When set to True, an appointment will be created on the specified time, **regardless** of available timeslots. Note that working hours and other restrictions are still enforced.
* **preventSelfCheckIn**: Boolean; When set to true, the customer cannot check in to the appointment using the kiosk.
* **fields** (optional): A dictionary of `fieldTypeId` and `fieldValue` pairs. :new:
* **tagIds** (optional): An array of tag Ids. :new:

## Response <a href="#response" id="response"></a>

#### Appointment created -> 201

Sample response:

```json
{
  "caseId":"<GUID>",
  "status": "Planned",
  "referenceDate": "YYYY-MM-ddTHH:mm:ssZ",
  "inboxId": "<GUID>",
  "channel": "FaceToFace|Video|Phone|...",
  "language": "en-US",
  "ticket": {
    "prefix": "A",
    "suffix": null,
    "number": 400
  },
  "appointment": {
    "serviceId": "<GUID>",
    "date": "YYYY-MM-dd", // the calendar date
    "cuIndex": 1,
    "start": 480, // number of minutes elapsed since midnight
    "timeUtc": "", // The appointment's start date and time in UTC
    "duration": 10, // appointment duration in minutes
    "noShowProbability": 0.0, 
    "reservationToken: "<GUID>", // for future use
    "reservationExpiryDate": "<UTC-DATE>", // for future use
  },
  "position": 0,
  "queueTimeStamp": "<UTC-DATE>",
}
```

&#x20;


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cubu.com/guides/s2s-api-guide/appointments-management-api/book-appointment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.