> 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/calls.md).

# Calls

Manage calls in Teamleader Focus Calendar.

```php
Teamleader::calls()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Calendar\Calls`                |
| Create / update / delete | ✓ / ✓ / ✓                                                             |
| Pagination               | `page_size` / `page_number`; the response includes `meta` with totals |

## Endpoints

* `calls.add`
* `calls.complete`
* `calls.delete`
* `calls.info`
* `calls.list`
* `calls.update`

## Filters

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

| Filter             | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `call_outcome_id`  | Filter on completed calls by outcome                             |
| `relates_to`       | Filter calls by related object (company)                         |
| `scheduled_after`  | Filter on calls occurring on or after a given date (YYYY-MM-DD)  |
| `scheduled_before` | Filter on calls occurring on or before a given date (YYYY-MM-DD) |

## Accepted values

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

| Constant          | Values                                                                         |
| ----------------- | ------------------------------------------------------------------------------ |
| `ADD_FIELDS`      | `description`, `participant`, `due_at`, `assignee`, `deal_id`, `custom_fields` |
| `ASSIGNEE_TYPES`  | `user`                                                                         |
| `CUSTOMER_TYPES`  | `contact`, `company`                                                           |
| `REQUIRED_ON_ADD` | `participant`, `due_at`, `assignee`                                            |
| `UPDATE_FIELDS`   | `description`, `participant`, `due_at`, `assignee`, `deal_id`, `custom_fields` |

## Methods

### `info()`

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

Get call information

### `complete()`

```php
complete(string $id, ?string $outcomeId = null, ?string $outcomeSummary = null): array
```

Mark a call as complete

### `upcoming()`

```php
upcoming(array $options = []): array
```

Get upcoming calls (scheduled after today)

### `list()`

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

List calls

`includes=pagination` is always sent, so the response carries the total match count in `meta`.

* `$filters` — scheduled\_after, scheduled\_before (YYYY-MM-DD), relates\_to \[type, id], call\_outcome\_id
* `$options` — page\_size, page\_number

**Throws** `InvalidArgumentException` On an unknown filter key or option

### `overdue()`

```php
overdue(array $options = []): array
```

Get overdue calls (scheduled before today, not completed)

### `forCompany()`

```php
forCompany(string $companyId, array $options = []): array
```

Get calls for a specific company

### `today()`

```php
today(array $options = []): array
```

Get today's calls

### `betweenDates()`

```php
betweenDates(string $startDate, string $endDate, array $options = []): array
```

Get calls within a date range

### `thisWeek()`

```php
thisWeek(array $options = []): array
```

Get this week's calls

### `schedule()`

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

Schedule a call (alias for create with more intuitive naming)

### `create()`

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

Create a call

Requires participant \[customer => \[type, id]], due\_at and assignee \[type => user, id].

**Throws** `InvalidArgumentException` When a required field is missing, or a field or value is not accepted

### `reschedule()`

```php
reschedule(string $id, string $newDateTime): array
```

Reschedule a call (update only the due\_at field)

### `update()`

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

Update an existing call

### `withOutcome()`

```php
withOutcome(string $outcomeId, array $options = []): array
```

Get completed calls with a specific outcome

### `delete()`

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

Delete a call.

* `$id` — Call UUID
* `$additionalParams` — Unused

**Throws** `InvalidArgumentException` When the ID is not a valid UUID