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

# Companies

Manage companies in Teamleader Focus CRM.

```php
Teamleader::companies()
```

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

## Endpoints

* `companies.add`
* `companies.delete`
* `companies.info`
* `companies.list`
* `companies.tag`
* `companies.untag`
* `companies.update`
* `companies.uploadLogo`

## Filters

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

| Filter                           | Description                                                                                     |
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
| `email`                          | Email address — a string, or \["type" => "primary", "email" => ...]. Only primary is searchable |
| `ids`                            | Array of company UUIDs (a single UUID string is wrapped)                                        |
| `marketing_mails_consent`        | Marketing mails consent (boolean)                                                               |
| `national_identification_number` | National identification number                                                                  |
| `status`                         | active or deactivated (a single value, not an array)                                            |
| `tags`                           | Array of tag names — companies coupled to all given tags                                        |
| `term`                           | Search term (searches name, VAT number, emails and telephones)                                  |
| `updated_since`                  | ISO 8601 datetime                                                                               |
| `vat_number`                     | VAT number                                                                                      |

## Sorting

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

| Field        | Description                       |
| ------------ | --------------------------------- |
| `added_at`   | Date the company was added        |
| `name`       | Company name                      |
| `updated_at` | Date the company was last updated |

## Includes

| Endpoint | Includes                                |
| -------- | --------------------------------------- |
| `list()` | `custom_fields`                         |
| `info()` | `related_companies`, `related_contacts` |

## Accepted values

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

| Constant             | Values                                                                                                                                                                                                                                                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ADDRESS_TYPES`      | `primary`, `invoicing`, `delivery`, `visiting`                                                                                                                                                                                                                                     |
| `CURRENCIES`         | `BAM`, `CAD`, `CHF`, `CLP`, `CNY`, `COP`, `CZK`, `DKK`, `EUR`, `GBP`, `INR`, `ISK`, `JPY`, `MAD`, `MXN`, `NOK`, `PEN`, `PLN`, `RON`, `SEK`, `TRY`, `USD`, `ZAR`                                                                                                                    |
| `EMAIL_TYPES`        | `primary`, `invoicing`                                                                                                                                                                                                                                                             |
| `FILTER_EMAIL_TYPES` | `primary`                                                                                                                                                                                                                                                                          |
| `STATUSES`           | `active`, `deactivated`                                                                                                                                                                                                                                                            |
| `TELEPHONE_TYPES`    | `phone`, `fax`                                                                                                                                                                                                                                                                     |
| `WRITE_FIELDS`       | `name`, `business_type_id`, `vat_number`, `national_identification_number`, `emails`, `telephones`, `website`, `addresses`, `iban`, `bic`, `language`, `preferred_currency`, `price_list_id`, `responsible_user_id`, `remarks`, `tags`, `custom_fields`, `marketing_mails_consent` |

## Methods

### `search()`

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

Enhanced search method with better field handling

### `list()`

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

List companies

* `$filters` — See $commonFilters; unknown keys throw
* `$options` — page\_size, page\_number, sort, sort\_order, include

**Throws** `InvalidArgumentException` On an unknown filter, sort field or include

### `byEmail()`

```php
byEmail(string $email, array $options = []): array
```

Search by email with proper structure

### `byVatNumber()`

```php
byVatNumber(string $vatNumber, array $options = []): array
```

Search by VAT number

### `byNationalIdentificationNumber()`

```php
byNationalIdentificationNumber(string $number, array $options = []): array
```

Search by national identification number

### `byName()`

> **Deprecated** since v2.2.1 — companies.list has no `name` filter. The API ignored it and returned every company, unfiltered, with HTTP 200. Use search() / the `term` filter, which searches name as well as VAT number, emails and telephones. This method will be removed in v3.0.

```php
byName(string $name, array $options = []): array
```

Fuzzy search by company name

**Throws** `InvalidArgumentException` Always

### `searchAll()`

```php
searchAll(string $query, array $options = []): array
```

General search across multiple fields (name, VAT, email, phone)

### `info()`

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

Get company information

`companies.info` accepts `related_companies` and `related_contacts` as includes — not `custom_fields`, which is a companies.list include. Custom fields and the price list are returned automatically; `price_list` is present whenever the account has access to price lists, and null when no price list is set on the company.

* `$id` — Company UUID
* `$includes` — related\_companies and/or related\_contacts

**Throws** `InvalidArgumentException` When an include is not valid for this endpoint

### `create()`

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

Create a new company

### `update()`

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

Update a company

### `delete()`

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

Delete a company

### `uploadLogo()`

```php
uploadLogo(string $id, ?string $image): array
```

Upload or remove a company logo. Pass a base64 data URI string to set the logo, or null to remove it.

* `$id` — Company UUID
* `$image` — Base64 data URI (e.g. data:image/png;base64,...) or null to remove

### `manageTags()`

```php
manageTags(string $id, array $tagsToAdd = [], array $tagsToRemove = []): array
```

Manage tags (add/remove)

### `tag()`

```php
tag(string $id, $tags): array
```

Tag a company

### `untag()`

```php
untag(string $id, $tags): array
```

Untag a company

### `withTags()`

```php
withTags($tags, array $options = []): array
```

Get companies with specific tags

### `updatedSince()`

```php
updatedSince(string $date, array $options = []): array
```

Get companies updated since a specific date

### `withCustomFields()`

```php
withCustomFields()
```

Include custom fields in the next list() request

The only include companies.list accepts.

### `withRelatedCompanies()`

```php
withRelatedCompanies()
```

Include related companies in the next info() request

companies.info only — not accepted by companies.list.

### `withRelatedContacts()`

```php
withRelatedContacts()
```

Include related contacts in the next info() request

companies.info only — not accepted by companies.list.