> 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/deals/lost-reasons.md).

# Lost Reasons

Manage lost reasons for deals in Teamleader Focus.

```php
Teamleader::lostReasons()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Deals\LostReasons`             |
| Create / update / delete | — / — / —                                                             |
| Pagination               | `page_size` / `page_number`; no totals — a short page is the last one |

## Endpoints

* `lostReasons.list`

## Filters

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

| Filter | Description                             |
| ------ | --------------------------------------- |
| `ids`  | Array of lost reason UUIDs to filter by |

## Sorting

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

| Field  | Description              |
| ------ | ------------------------ |
| `name` | Sort by lost reason name |

## Methods

### `list()`

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

List lost reasons with filtering, sorting and pagination

* `$filters` — `ids` only
* `$options` — page\_size, page\_number, sort (name), sort\_order (asc)

**Throws** `\InvalidArgumentException` On an unknown filter, or a sort other than name/asc

### `byIds()`

```php
byIds(array $ids): array
```

Get lost reasons by specific IDs

* `$ids` — Array of lost reason UUIDs

### `all()`

```php
all(string $sortOrder = 'asc', int $maxPages = 50): array
```

Get every lost reason, walking all pages

lostReasons.list sorts by name ascending only. Before v2.2.5 this took a $sortOrder and passed 'desc' straight through; the argument is kept for compatibility and must be 'asc'. It also returned only the first page of 100.

* `$sortOrder` — Must be 'asc'
* `$maxPages` — Runaway guard: 50 pages of 100

**Throws** `\InvalidArgumentException` On a sort order other than asc, or when $maxPages is reached

### `search()`

> **Deprecated** since v2.2.5 — the name suggested a text search, which lostReasons.list does not offer. Use byIds(), or all() and filter client-side. Removed in v3.0.

```php
search(array $ids = []): array
```

Get lost reasons by ID

* `$ids` — Array of IDs to fetch; empty returns all()

### `isValidSortField()`

```php
isValidSortField(string $field): bool
```

Validate sort field (only 'name' is supported)

### `info()`

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

Override info method since this resource doesn't support individual item retrieval

### `getStats()`

```php
getStats(): array
```

Get statistics about available lost reasons (convenience method)

### `exists()`

```php
exists(string $id): bool
```

Check if a lost reason exists by ID

### `getSelectOptions()`

```php
getSelectOptions(): array
```

Get lost reasons as select options for forms

## Examples

Get all lost reasons:

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

Get specific lost reasons by ID:

```php
$lostReasons = Teamleader::lostReasons()->list(['ids' => ['uuid1', 'uuid2']]);
```

Get lost reasons sorted by name:

```php
$lostReasons = Teamleader::lostReasons()->list([], ['sort' => [['field' => 'name', 'order' => 'asc']]]);
```

Get lost reasons with custom pagination:

```php
$lostReasons = Teamleader::lostReasons()->list([], ['page_size' => 50, 'page_number' => 2]);
```