> For the complete documentation index, see [llms.txt](https://api-docs.everreal.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.everreal.co/endpoints/calendar-and-viewings.md).

# Calendar and viewings

Read and change appointments, set viewing slots, invite and book contacts, and read free slots.

## Introduction

The reporting API has the calendar. An agent can read and change appointments, set [viewing](https://api-docs.everreal.co/key-concepts.md#viewing-and-viewing-schedule) slots on a [listing](https://api-docs.everreal.co/key-concepts.md#listing), invite and book [contacts](https://api-docs.everreal.co/key-concepts.md#contact), and read free slots. One person with a [company](https://api-docs.everreal.co/key-concepts.md#company) [user](https://api-docs.everreal.co/key-concepts.md#user-and-member) token can do all of it.

Each call works as in the EverReal web app. The company [scope](https://api-docs.everreal.co/key-concepts.md#scope), the rules, the mails to participants and the sync to connected calendars are the same.

For a step-by-step example, see [Guide: phone booking flow](https://api-docs.everreal.co/endpoints/calendar-and-viewings/guide-phone-booking-flow.md).

**Endpoint:** `POST https://{subdomain}.everreal.co/api/reporting/graphql`

**Auth:** [Bearer token](https://api-docs.everreal.co/key-concepts.md#access-token) with the scope `company_user` or `company_admin`. Any company user can call these operations. A token without one of these scopes gets `FORBIDDEN` with the [`errorLocale`](https://api-docs.everreal.co/key-concepts.md#errorlocale) `calendarAdmin.scope.missing`.

All times are ISO 8601 date-times, for example `2026-10-26T09:00:00Z`.

`companyId` is optional on every operation. Use it to act in another company of your [partner](https://api-docs.everreal.co/key-concepts.md#partner) in which you are a member. Without it, the call acts in the company of your token. Another company answers `NOT_FOUND` with `companyScopedToken.notFoundForCompany`. See [Access model](https://api-docs.everreal.co/master/access-model.md).

## Reads

```graphql
type Query {
  appointments(from: DateTime!, to: DateTime!, userId: ID, listingId: ID, eventTypeId: ID, skip: Int = 0, take: Int = 50, companyId: ID): CalendarAppointmentPage!
  appointment(id: ID!, companyId: ID): CalendarAppointment!
  listingViewingSchedule(listingId: ID!, from: DateTime, to: DateTime, companyId: ID): CalendarViewingSchedule
  freeSlots(userId: ID!, from: DateTime!, to: DateTime!, eventTypeId: ID, durationMinutes: Int, companyId: ID): [CalendarFreeSlot!]!
  userAvailability(userId: ID!, companyId: ID): CalendarUserAvailability
  eventTypes(companyId: ID): [CalendarEventType!]!
}
```

| Operation                | What it does                                                                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appointments`           | Appointments of the company that overlap `from` to `to`, ordered by start. `userId` keeps the appointments that this user is responsible for. `take` is at most 100.                                                                                                                                                |
| `appointment`            | One appointment, with its participants and slots.                                                                                                                                                                                                                                                                   |
| `listingViewingSchedule` | The viewing schedule of a listing, with the slots that overlap `from` to `to`. Without bounds, it reads 90 days back and 90 days ahead. For a listing in a [project](https://api-docs.everreal.co/key-concepts.md#project), it returns the project schedule. The answer is `null` when the listing has no schedule. |
| `freeSlots`              | Free slots of a user: the availability of that user minus appointments and busy time of a connected calendar. `durationMinutes` sets the slot length instead of the default of the event type.                                                                                                                      |
| `userAvailability`       | The weekly availability of a user. If the user has set none, you get the defaults (Monday to Friday, 09:00 to 17:00) and `id` is `null`.                                                                                                                                                                            |
| `eventTypes`             | The event types of the company, system types included. Use an `id` as `eventTypeId`.                                                                                                                                                                                                                                |

Example request:

```graphql
query {
  appointments(from: "2026-10-26T00:00:00Z", to: "2026-10-27T00:00:00Z", take: 10) {
    totalCount
    hasNextPage
    nodes {
      id
      title
      mode
      startDate
      endDate
      status
      participants { id displayName rsvpStatus slotId }
    }
  }
}
```

Example answer:

```json
{
  "data": {
    "appointments": {
      "totalCount": 1,
      "hasNextPage": false,
      "nodes": [
        {
          "id": "3f1c8a52-6d0e-4b7a-9c14-2e5a7b9d0c11",
          "title": "Handover Example Street 5",
          "mode": "DIRECT",
          "startDate": "2026-10-26T09:00:00.000Z",
          "endDate": "2026-10-26T09:30:00.000Z",
          "status": "SCHEDULED",
          "participants": [
            { "id": "a41e7c90-5b3d-4f28-8e6a-17c0d2b9e344", "displayName": "Erika Example", "rsvpStatus": "PENDING", "slotId": null }
          ]
        }
      ]
    }
  }
}
```

## Appointments

```graphql
type Mutation {
  createAppointment(input: CalendarCreateAppointmentInput!, companyId: ID): CalendarAppointmentResult!
  updateAppointment(id: ID!, input: CalendarUpdateAppointmentInput!, companyId: ID): CalendarAppointmentResult!
  rescheduleAppointment(id: ID!, startDate: DateTime!, endDate: DateTime!, timezone: String!, companyId: ID): CalendarAppointmentResult!
  cancelAppointment(id: ID!, reason: String, companyId: ID): CalendarAppointment!
  completeAppointment(id: ID!, companyId: ID): CalendarAppointment!
}
```

| Operation               | What it does                                                                                                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createAppointment`     | Creates an appointment at a fixed time. A participant with a start in the future gets an invitation mail.                                                  |
| `updateAppointment`     | Changes only the fields you give. Participants get an invitation or update mail. `reinviteCompanyContactIds` sends the invitation again to those contacts. |
| `rescheduleAppointment` | Moves an appointment to a new time. Participants get an update mail.                                                                                       |
| `cancelAppointment`     | Cancels an appointment. Participants get a cancellation mail.                                                                                              |
| `completeAppointment`   | Marks an appointment as done.                                                                                                                              |

The fields of `CalendarCreateAppointmentInput`:

* Required: `eventTypeId`, `title`, `startDate`, `endDate`, `responsibleUserId`.
* Optional: `timezone`, `location`, `videoLink`, `notes`, `reminderConfig`, `links`, `participants`, `idempotencyKey`, `enforceBookingRules`.

Rules for the fields:

* `timezone` is an IANA time zone. It defaults to the time zone of the responsible user.
* A participant (`CalendarParticipantInput`) is a contact (`companyContactId`), a user (`userId`), or an outside person (`externalEmail`, `externalName`). `bookingListingId` is also allowed.
* `links` (`CalendarLinkInput`) can hold `dealId`, `companyContactId`, `propertyId`, `unitId`, `listingId` and `projectId`.
* `reminderConfig` is a list of minutes before the start when reminders go out.
* `idempotencyKey` is a key that you choose, at most 128 characters. If you send the same key again, you get the first appointment (`replayed: true`) and nothing new is created.
* `enforceBookingRules` refuses an overlap, or a start inside the booking cutoff, instead of only warning. If you leave it out, it is `true`. The exception is the `VIEWING` event type: there it is `false`, as in the app, and the appointment is saved with overlap warnings. EverReal refuses a fixed-time viewing with the rules on (`calendar.api.viewings.directUnsupported`).

The fields of `CalendarAppointmentResult`:

* `appointment`: the appointment.
* `overlapWarnings`: other appointments at the same time (`kind`, `id`, `title`, `startDate`, `endDate`).
* `participantWarnings`: problems with a participant (`participantId`, `code`, for example `NO_EMAIL`).
* `replayed`: `true` if the `idempotencyKey` was used before.
* `mergedIntoExistingSchedule`, `addedSlotIds`, `notifiedCandidatesCount`, `ignoredFields`: for viewing slots only.

Example request:

```graphql
mutation {
  createAppointment(input: {
    eventTypeId: "c7a2e4f0-81b3-4d56-a9f1-5e0b3c6d7a22"
    title: "Handover Example Street 5"
    startDate: "2026-10-26T09:00:00Z"
    endDate: "2026-10-26T09:30:00Z"
    responsibleUserId: "9b6d1f3e-2a47-4c80-b5e9-0d8c7a1f4e33"
    participants: [{ externalEmail: "erika.example@example.com", externalName: "Erika Example" }]
    idempotencyKey: "handover-example-street-5-2026-10-26"
  }) {
    replayed
    overlapWarnings { kind title }
    participantWarnings { participantId code }
    appointment { id title status startDate endDate }
  }
}
```

Example answer:

```json
{
  "data": {
    "createAppointment": {
      "replayed": false,
      "overlapWarnings": [],
      "participantWarnings": [],
      "appointment": {
        "id": "3f1c8a52-6d0e-4b7a-9c14-2e5a7b9d0c11",
        "title": "Handover Example Street 5",
        "status": "SCHEDULED",
        "startDate": "2026-10-26T09:00:00.000Z",
        "endDate": "2026-10-26T09:30:00.000Z"
      }
    }
  }
}
```

## Viewings

```graphql
type Mutation {
  setListingViewingSchedule(listingId: ID!, input: CalendarViewingScheduleInput!, companyId: ID): CalendarViewingScheduleResult!
  inviteToViewing(listingId: ID!, companyContactIds: [ID!]!, companyId: ID): CalendarAppointmentResult!
  bookViewing(appointmentId: ID!, slotId: ID!, participantId: ID, companyContactId: ID, listingId: ID, companyId: ID): CalendarParticipant!
  moveViewingBooking(appointmentId: ID!, participantId: ID!, toSlotId: ID, startDate: DateTime, endDate: DateTime, companyId: ID): CalendarSlot!
  removeViewingParticipant(
    appointmentId: ID!
    participantId: ID!
    reason: String
    offerNewSlot: Boolean = false
    notifyParticipant: Boolean = true
    keepViewingInvitationOpen: Boolean = false
    companyId: ID
  ): CalendarParticipant!
}
```

| Operation                   | What it does                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `setListingViewingSchedule` | Sets viewing slots on a listing. If the listing has no viewing schedule, the call creates one. Then `eventTypeId` (the `VIEWING` event type) and `title` are required. If the listing has a schedule, the slots are added, or changed when a slot has an `id`. A slot that you leave out stays. `notifyParticipants` (default `false`) mails invited [candidates](https://api-docs.everreal.co/key-concepts.md#candidate) about new slots. |
| `inviteToViewing`           | Invites 1 to 10 contacts to pick a slot of the schedule. Each contact gets one invitation mail. No other participant gets a mail. The listing needs a schedule first.                                                                                                                                                                                                                                                                      |
| `bookViewing`               | Books a person into a slot. Give `participantId` (a person on the schedule) or `companyContactId`, not both. `listingId` is the listing the booking is for. It is needed for a project schedule.                                                                                                                                                                                                                                           |
| `moveViewingBooking`        | Moves one booking to another slot of the same schedule (`toSlotId`), or to a new time (`startDate` and `endDate`). Give one of the two, not both. The person gets one mail. The answer is the slot the booking moved to.                                                                                                                                                                                                                   |
| `removeViewingParticipant`  | Cancels the booking of one person, so the slot is free again. `notifyParticipant` (default `true`) mails the person. `offerNewSlot` invites the person to pick another slot. `keepViewingInvitationOpen` keeps the invitation open. If you set neither, the invitation closes.                                                                                                                                                             |

The fields of `CalendarViewingScheduleInput`:

* Required: `responsibleUserId`, `slots`.
* Optional: `eventTypeId`, `title`, `notes`, `notifyParticipants` (default `false`), `enforceBookingRules` (default `true`), `idempotencyKey`.

The fields of a slot (`CalendarViewingSlotInput`):

* Required: `startDate`, `endDate`.
* Optional: `id`, `capacity`, `bookingCutoffMinutes`, `responsibleUserId`, `title`, `additionalInformation`, `projectCategoryIds`.

A slot without `responsibleUserId` gets the one of the schedule input. A new schedule accepts no slot `id`.

The fields of `CalendarViewingScheduleResult`: `appointment`, `created`, `mergedIntoExistingSchedule`, `overlapWarnings`, `participantWarnings`, `replayed`, `addedSlotIds`, `notifiedCandidatesCount` and `ignoredFields`.

A viewing booked through the API sends the same mails as a booking in the app.

{% hint style="warning" %}
`removeViewingParticipant` refuses a person who has no booking. This is an open invitation, or a booking that was already cancelled. The error is `BAD_USER_INPUT` with the `errorLocale` `calendarAdmin.viewingBooking.notBooked`, and nothing changes. To withdraw an open invitation, call `updateAppointment` with a new `participants` list.
{% endhint %}

Example request (set slots on a listing that has no schedule yet):

```graphql
mutation {
  setListingViewingSchedule(
    listingId: "7d2a9c34-1b8e-4f6a-a3c5-90e1d4b8f255"
    input: {
      eventTypeId: "5a9e0c71-3d2b-48f6-b1c4-8e7f6a5d4c09"
      title: "Viewing Example Street 5"
      responsibleUserId: "9b6d1f3e-2a47-4c80-b5e9-0d8c7a1f4e33"
      slots: [
        { startDate: "2026-10-28T15:00:00Z", endDate: "2026-10-28T15:20:00Z", capacity: 1 }
        { startDate: "2026-10-28T15:30:00Z", endDate: "2026-10-28T15:50:00Z", capacity: 1 }
      ]
    }
  ) {
    created
    addedSlotIds
    appointment { id slots { id startDate endDate bookedCount } }
  }
}
```

Example answer:

```json
{
  "data": {
    "setListingViewingSchedule": {
      "created": true,
      "addedSlotIds": null,
      "appointment": {
        "id": "e08b5d23-7a91-4c64-8f02-b3d1a6c9e577",
        "slots": [
          { "id": "11d4f7a0-92c3-4e58-a6b1-0c5e8d3f2a61", "startDate": "2026-10-28T15:00:00.000Z", "endDate": "2026-10-28T15:20:00.000Z", "bookedCount": 0 },
          { "id": "2b6e9c13-4f85-4a70-9d28-7e1a0b4c5d92", "startDate": "2026-10-28T15:30:00.000Z", "endDate": "2026-10-28T15:50:00.000Z", "bookedCount": 0 }
        ]
      }
    }
  }
}
```

For a new schedule, `addedSlotIds` can be `null`. Read the slot ids from `appointment.slots`.

Example request (book a contact into a slot):

```graphql
mutation {
  bookViewing(
    appointmentId: "e08b5d23-7a91-4c64-8f02-b3d1a6c9e577"
    slotId: "11d4f7a0-92c3-4e58-a6b1-0c5e8d3f2a61"
    companyContactId: "d93a2b60-1e7f-4c85-b4a9-6f0c3e8d1a75"
    listingId: "7d2a9c34-1b8e-4f6a-a3c5-90e1d4b8f255"
  ) {
    id
    slotId
    companyContactId
    displayName
    rsvpStatus
  }
}
```

Example answer:

```json
{
  "data": {
    "bookViewing": {
      "id": "a41e7c90-5b3d-4f28-8e6a-17c0d2b9e344",
      "slotId": "11d4f7a0-92c3-4e58-a6b1-0c5e8d3f2a61",
      "companyContactId": "d93a2b60-1e7f-4c85-b4a9-6f0c3e8d1a75",
      "displayName": "Erika Example",
      "rsvpStatus": "ACCEPTED"
    }
  }
}
```

The value of `rsvpStatus` after a booking can differ. The one shown here is an example.

If two calls book the same person into a slot at the same time, the second call gets `calendarAdmin.viewingBooking.alreadyBooked`.

## Availability

```graphql
type Mutation {
  setUserAvailability(userId: ID!, input: CalendarAvailabilityInput!, companyId: ID): CalendarUserAvailability!
}
```

`setUserAvailability` sets the weekly availability of a user. Any company user can set it for a colleague of the same company, not only for the own user. Only the days you give change. The input is `timezone` (an IANA time zone, for example `Europe/Berlin`) and `days`. `days` has the keys `MON` to `SUN`. Each day has `enabled: Boolean!` and `intervals`, a list of `{ start, end }` in `HH:mm`.

Example request:

```graphql
mutation {
  setUserAvailability(
    userId: "9b6d1f3e-2a47-4c80-b5e9-0d8c7a1f4e33"
    input: {
      timezone: "Europe/Berlin"
      days: { FRI: { enabled: true, intervals: [{ start: "10:00", end: "14:00" }] } }
    }
  ) {
    timezone
    days { FRI { enabled intervals { start end } } }
  }
}
```

Example answer:

```json
{
  "data": {
    "setUserAvailability": {
      "timezone": "Europe/Berlin",
      "days": { "FRI": { "enabled": true, "intervals": [{ "start": "10:00", "end": "14:00" }] } }
    }
  }
}
```

## Errors

Every error has a `code` and an `extensions.errorLocale`.

| code              | errorLocale                                           | When                                                                                                               |
| ----------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `FORBIDDEN`       | `calendarAdmin.scope.missing`                         | The token has neither `company_user` nor `company_admin`.                                                          |
| `BAD_USER_INPUT`  | `calendarAdmin.range.invalid`                         | A start is not before its end (`from`/`to`, `startDate`/`endDate`, or a slot).                                     |
| `BAD_USER_INPUT`  | `calendarAdmin.skip.invalid`                          | `skip` is below 0.                                                                                                 |
| `BAD_USER_INPUT`  | `calendarAdmin.take.invalid`                          | `take` is not between 1 and 100.                                                                                   |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingSchedule.slots.required`        | `setListingViewingSchedule` has no slot.                                                                           |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingSchedule.createFields.required` | The listing has no schedule, and `eventTypeId` or `title` is missing.                                              |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingSchedule.slotId.unknown`        | A slot has an `id`, but the schedule is new.                                                                       |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingInvite.count.invalid`           | `inviteToViewing` has 0 or more than 10 different contacts.                                                        |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingBooking.person.invalid`         | `bookViewing` has both or neither of `participantId` and `companyContactId`.                                       |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingBooking.target.invalid`         | `moveViewingBooking` has both or neither of `toSlotId` and the new time.                                           |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingBooking.alreadyBooked`          | `bookViewing` for a person who already has a booking of a slot that has not started yet. Use `moveViewingBooking`. |
| `BAD_USER_INPUT`  | `calendarAdmin.viewingBooking.notBooked`              | `removeViewingParticipant` for a person with no booking.                                                           |
| `NOT_FOUND`       | `calendarAdmin.viewingSchedule.notFound`              | `inviteToViewing` on a listing with no viewing schedule.                                                           |
| `NOT_FOUND`       | `companyScopedToken.notFoundForCompany`               | `companyId` is a company where you are not a member, or not a company of your partner.                             |
| `NOT_FOUND`       | `calendarAdmin.notFoundForCompany`                    | The record belongs to another company. The answer does not say that it exists.                                     |
| `NOT_FOUND`       | a key that ends in `.notFound`                        | The record does not exist.                                                                                         |
| `BAD_USER_INPUT`  | a key that starts with `calendar.`                    | The calendar refused the request, for example `calendar.api.viewings.directUnsupported`.                           |
| `BAD_USER_INPUT`  | `calendarAdmin.calendar.invalidInput`                 | The calendar refused the input without a key. The message is cut to 200 characters.                                |
| `UNAUTHENTICATED` | `calendarAdmin.calendar.unauthorized`                 | The calendar refused the token.                                                                                    |
| `UPSTREAM_ERROR`  | `calendarAdmin.calendar.unreachable`                  | The calendar could not be reached (timeout 30 seconds).                                                            |
| `UPSTREAM_ERROR`  | `calendarAdmin.calendar.failed`                       | The calendar failed in another way.                                                                                |
