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

# Addresses

Get geographical area information for addresses (level two areas like provinces, states, departments).

```php
Teamleader::addresses()
```

|                          |                                                       |
| ------------------------ | ----------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\CRM\Addresses` |
| Create / update / delete | — / — / —                                             |
| Pagination               | No                                                    |

## Endpoints

* `levelTwoAreas.list`

## Filters

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

| Filter     | Description                                                                          |
| ---------- | ------------------------------------------------------------------------------------ |
| `country`  | ISO country code (required) - e.g., BE, NL, FR                                       |
| `language` | Language for area names (optional) - defaults to the primary language of the country |

## Methods

### `levelTwoAreas()`

```php
levelTwoAreas(string $countryCode, ?string $language = null): array
```

Get level two areas (provinces, states, departments) for a country

* `$countryCode` — ISO country code (e.g., "BE", "NL", "FR")
* `$language` — Language code for area names (e.g., "nl", "fr", "en")

### `list()`

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

List level two areas for a country

* `$filters` — `country` (required) and optionally `language`
* `$options` — Not supported — the endpoint has no paging or sorting

**Throws** `\InvalidArgumentException` When country is missing, or another key or option is passed

### `belgianProvinces()`

```php
belgianProvinces(string $language = 'nl'): array
```

Get Belgian provinces

* `$language` — Language code (nl, fr, de, en)

### `dutchProvinces()`

```php
dutchProvinces(string $language = 'nl'): array
```

Get Dutch provinces

* `$language` — Language code

### `frenchDepartments()`

```php
frenchDepartments(string $language = 'fr'): array
```

Get French departments

* `$language` — Language code

### `germanStates()`

```php
germanStates(string $language = 'de'): array
```

Get German states (Bundesländer)

* `$language` — Language code

### `ukRegions()`

```php
ukRegions(string $language = 'en'): array
```

Get UK countries/regions

* `$language` — Language code

### `usStates()`

```php
usStates(string $language = 'en'): array
```

Get US states

* `$language` — Language code

### `canadianProvinces()`

```php
canadianProvinces(string $language = 'en'): array
```

Get Canadian provinces

* `$language` — Language code

### `forCountries()`

```php
forCountries(array $countries, ?string $defaultLanguage = null): array
```

Get level two areas for multiple countries

* `$countries` — Array of country codes or country/language pairs
* `$defaultLanguage` — Default language if not specified per country

### `search()`

```php
search(string $countryCode, string $query, ?string $language = null, bool $exactMatch = false): array
```

Search level two areas by name (client-side search)

* `$countryCode` — Country to search in
* `$query` — Search query
* `$language` — Language for results
* `$exactMatch` — Whether to match exactly or use partial matching

### `findById()`

```php
findById(string $countryCode, string $areaId, ?string $language = null): ?array
```

Get area by ID within a country

* `$countryCode` — Country code
* `$areaId` — Area ID to find
* `$language` — Language for result

### `getSupportedCountries()`

```php
getSupportedCountries(): array
```

Get supported countries for level two areas (This is a helper method - actual supported countries depend on Teamleader)

### `getSupportedLanguages()`

```php
getSupportedLanguages(): array
```

Get supported languages

### `isValidCountryCode()`

```php
isValidCountryCode(string $countryCode): bool
```

Validate country code format

### `isValidLanguageCode()`

```php
isValidLanguageCode(string $languageCode): bool
```

Validate language code format

### `info()`

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

Override info method as it's not supported for level two areas

**Throws** `\InvalidArgumentException`

### `getResponseStructure()`

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

Get response structure documentation

## Examples

Get provinces for Belgium in Dutch:

```php
$areas = Teamleader::addresses()->levelTwoAreas("BE", "nl");
```

Get states for Germany:

```php
$areas = Teamleader::addresses()->levelTwoAreas("DE");
```

Get departments for France in French:

```php
$areas = Teamleader::addresses()->levelTwoAreas("FR", "fr");
```

Get level two areas for multiple countries:

```php

$belgianProvinces = Teamleader::addresses()->levelTwoAreas("BE");
$dutchProvinces = Teamleader::addresses()->levelTwoAreas("NL");
```