> For the complete documentation index, see [llms.txt](https://teamleader-sdk.mcore-services.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://teamleader-sdk.mcore-services.dev/api-reference/calendar/calendar-events.md).

# Calendar Events

Manage calendar events in Teamleader Focus.

```php
Teamleader::calendarEvents()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Calendar\Events`               |
| Also available as        | `calenderEvents()`                                                    |
| Create / update / delete | ✓ / ✓ / ✓                                                             |
| Pagination               | `page_size` / `page_number`; no totals — a short page is the last one |

## Endpoints

* `events.cancel`
* `events.create`
* `events.info`
* `events.list`
* `events.update`

## Filters

Passed as the first argument to `list()`. Any other key throws.

| Filter             | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `activity_type_id` | Filter by activity type UUID                                       |
| `attendee`         | Filter by attendee: \[type => contact, id => uuid] (contacts only) |
| `done`             | Filter by completion status (boolean)                              |
| `ends_after`       | Start of the period for which to return events (ISO 8601 format)   |
| `ids`              | Array of event UUIDs                                               |
| `link`             | Filter by linked entity (object with id and type)                  |
| `starts_before`    | End of the period for which to return events (ISO 8601 format)     |
| `task_id`          | Filter events by task UUID                                         |
| `term`             | Searches for a term in title or description                        |
| `user_id`          | Filter events by user UUID                                         |

## Sorting

Pass `sort` (and optionally `sort_order`) in the options. Any other field throws.

| Field       | Description                   |
| ----------- | ----------------------------- |
| `starts_at` | Sort by event start date/time |

## Accepted values

Public constants on the class. Body fields and enum values outside these lists throw before the request is sent.

| Constant                | Values                                                                                                               |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `ATTENDEE_TYPES`        | `user`, `contact`                                                                                                    |
| `CREATE_FIELDS`         | `title`, `description`, `activity_type_id`, `starts_at`, `ends_at`, `location`, `work_type_id`, `attendees`, `links` |
| `FILTER_ATTENDEE_TYPES` | `contact`                                                                                                            |
| `LINK_TYPES`            | `contact`, `company`, `deal`                                                                                         |
| `REQUIRED_ON_CREATE`    | `title`, `activity_type_id`, `starts_at`, `ends_at`                                                                  |
| `UPDATE_FIELDS`         | `title`, `description`, `starts_at`, `ends_at`, `location`, `work_type_id`, `attendees`, `links`                     |

## Methods

### `list()`

```php
list(array $filters = [], array $options = []): array
```

List events with filtering, sorting, and pagination

### `info()`

```php
info($id, $includes = null): array
```

Get event information

### `create()`

```php
create(array $data): array
```

Create a new calendar event

Required fields: title, activity\_type\_id, starts\_at, ends\_at

### `update()`

```php
update($id, array $data): array
```

Update an existing calendar event

All fields except id are optional.

### `cancel()`

```php
cancel(string $id): array
```

Cancel a calendar event (for all attendees)

Note: This is the delete operation for events

### `delete()`

```php
delete($id, ...$additionalParams): array
```

Override delete to use cancel

### `forUser()`

```php
forUser(string $userId, array $options = []): array
```

Get events for a specific user

* `$userId` — User UUID
* `$options` — Additional options

### `forActivityType()`

```php
forActivityType(string $activityTypeId, array $options = []): array
```

Get events for a specific activity type

* `$activityTypeId` — Activity type UUID
* `$options` — Additional options

### `search()`

```php
search(string $term, array $options = []): array
```

Search events by term (searches title and description)

* `$term` — Search term
* `$options` — Additional options

### `betweenDates()`

```php
betweenDates(string $startsAfter, string $endsBefore, array $options = []): array
```

Get events within a date range

* `$startsAfter` — ISO 8601 datetime
* `$endsBefore` — ISO 8601 datetime
* `$options` — Additional options

### `byIds()`

```php
byIds(array $ids, array $options = []): array
```

Get events by specific IDs

* `$ids` — Array of event UUIDs
* `$options` — Additional options

### `forAttendee()`

```php
forAttendee(string $attendeeType, string $attendeeId, array $options = []): array
```

Get events for a specific attendee

events.list filters on contact attendees only. Before v2.2.12 `user` was accepted here too; use forUser() for a user's events.

* `$attendeeType` — Type of attendee: contact
* `$attendeeId` — UUID of the attendee
* `$options` — Additional options

### `forLink()`

```php
forLink(string $linkType, string $linkId, array $options = []): array
```

Get events linked to a specific entity

* `$linkType` — Type of link (contact, company, deal)
* `$linkId` — UUID of the linked entity
* `$options` — Additional options

### `getResponseStructure()`

```php
getResponseStructure(): array
```

Get response structure documentation

## Examples

Get all events:

```php
$events = Teamleader::calendarEvents()->list();
```

Get events for a specific user:

```php
$events = Teamleader::calendarEvents()->forUser("user-uuid");
```

Get events within a date range:

```php
$events = Teamleader::calendarEvents()->list([
    "ends_after" => "2025-01-01T00:00:00+00:00",
    "starts_before" => "2025-12-31T23:59:59+00:00"
]);
```

Create a new calendar event:

```php
$event = Teamleader::calendarEvents()->create([
    "title" => "Meeting with stakeholders",
    "activity_type_id" => "activity-type-uuid",
    "starts_at" => "2025-02-04T16:00:00+00:00",
    "ends_at" => "2025-02-04T18:00:00+00:00",
    "attendees" => [
        ["type" => "user", "id" => "user-uuid"]
    ]
]);
```

Update an existing event:

```php
$event = Teamleader::calendarEvents()->update("event-uuid", [
    "title" => "Updated meeting title",
    "starts_at" => "2025-02-04T17:00:00+00:00"
]);
```

Cancel an event (for all attendees):

```php
$result = Teamleader::calendarEvents()->cancel("event-uuid");
```

Search events by term:

```php
$events = Teamleader::calendarEvents()->search("coffee");
```