---
title: "Establishments"
section: "Core Resources"
order: 13
excerpt: "Manage legal establishments (branches, subsidiaries) attached to a customer or prospect, each with its own registration number and address."
---

Base URL: `/api/v1/establishments`

**Auth required:** Yes (`auth:api`) for all endpoints.

Establishments are polymorphic sub-entities of a `Customer` or `Prospect`. They represent distinct legal or administrative entities such as branch offices or subsidiaries. Each has its own name, registration number (SIRET), and address. The `fileable_type` query parameter accepts the short names `customer` or `prospect`.

---

## Model Properties

| Property | Type | Notes |
|---|---|---|
| `id` | integer | Auto-generated unique identifier |
| `fileable_type` | string | Full PHP class name of the owning entity (e.g. `App\Customer`) |
| `fileable_id` | integer | ID of the owning entity |
| `name` | string | Establishment name |
| `registrationNumber` | string | SIRET or registration number |
| `addressLine1` | string | Address line 1 |
| `addressLine2` | string | Address line 2 |
| `postalCode` | string | Postal / ZIP code |
| `city` | string | City |
| `country` | string | Country (default: `France`) |
| `created_at` | datetime | Auto-set on creation |
| `updated_at` | datetime | Auto-updated on each save |

---

## GET /v1/establishments

List all establishments for a given fileable entity.

**Query parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fileable_type` | string | Yes | Short name of the owning entity: `customer` or `prospect` |
| `fileable_id` | integer | Yes | ID of the owning entity |

**Response 200:** Array of establishment objects.

**Examples:**

```bash
curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/establishments?fileable_type=customer&fileable_id=42" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

```python
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/establishments",
    params={"fileable_type": "customer", "fileable_id": 42},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
establishments = response.json()
```

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://your-instance.bluerocktel.net/api/v1/establishments', [
        'fileable_type' => 'customer',
        'fileable_id' => 42,
    ]);

$establishments = $response->json();
```

```javascript
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/establishments?fileable_type=customer&fileable_id=42",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const establishments = await response.json();
```

---

## POST /v1/establishments

Create a new establishment attached to a customer or prospect.

**Query parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fileable_type` | string | Yes | Short name of the owning entity: `customer` or `prospect` |
| `fileable_id` | integer | Yes | ID of the owning entity |

**Body (JSON):**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Establishment name |
| `registrationNumber` | string | No | SIRET or registration number |
| `addressLine1` | string | No | Address line 1 |
| `addressLine2` | string | No | Address line 2 |
| `postalCode` | string | No | Postal / ZIP code |
| `city` | string | No | City |
| `country` | string | No | Country (default: `France`) |

**Response 201:** Created establishment object.

**Examples:**

```bash
curl -s -X POST "https://your-instance.bluerocktel.net/api/v1/establishments?fileable_type=customer&fileable_id=42" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lyon Branch", "registrationNumber": "12345678901234", "addressLine1": "10 Rue de la Paix", "postalCode": "69001", "city": "Lyon", "country": "France"}'
```

```python
import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/establishments",
    params={"fileable_type": "customer", "fileable_id": 42},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    json={
        "name": "Lyon Branch",
        "registrationNumber": "12345678901234",
        "addressLine1": "10 Rue de la Paix",
        "postalCode": "69001",
        "city": "Lyon",
        "country": "France",
    },
)
establishment = response.json()
```

```php
$response = Http::withToken($token)
    ->acceptJson()
    ->post('https://your-instance.bluerocktel.net/api/v1/establishments?fileable_type=customer&fileable_id=42', [
        'name' => 'Lyon Branch',
        'registrationNumber' => '12345678901234',
        'addressLine1' => '10 Rue de la Paix',
        'postalCode' => '69001',
        'city' => 'Lyon',
        'country' => 'France',
    ]);

$establishment = $response->json();
```

```javascript
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/establishments?fileable_type=customer&fileable_id=42",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Lyon Branch",
      registrationNumber: "12345678901234",
      addressLine1: "10 Rue de la Paix",
      postalCode: "69001",
      city: "Lyon",
      country: "France",
    }),
  }
);
const establishment = await response.json();
```

---

## GET /v1/establishments/{id}

Get a single establishment by ID.

**URL parameters:**

| Parameter | Type | Description |
|---|---|---|
| `id` | integer | Establishment ID |

**Response 200:** Establishment object.
**Response 404:** Not found.

**Examples:**

```bash
curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/establishments/7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

```python
import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/establishments/7",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
establishment = response.json()
```

```php
$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://your-instance.bluerocktel.net/api/v1/establishments/7');

$establishment = $response->json();
```

```javascript
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/establishments/7",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const establishment = await response.json();
```

---

## PUT /v1/establishments/{id}

Update an establishment. Only address fields can be changed; `fileable_type` and `fileable_id` cannot be modified after creation.

**URL parameters:**

| Parameter | Type | Description |
|---|---|---|
| `id` | integer | Establishment ID |

**Body (JSON):**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Establishment name |
| `registrationNumber` | string | No | SIRET or registration number |
| `addressLine1` | string | No | Address line 1 |
| `addressLine2` | string | No | Address line 2 |
| `postalCode` | string | No | Postal / ZIP code |
| `city` | string | No | City |
| `country` | string | No | Country |

**Response 201:** Updated establishment object.
**Response 404:** Not found.

**Examples:**

```bash
curl -s -X PUT "https://your-instance.bluerocktel.net/api/v1/establishments/7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"addressLine1": "25 Avenue Berthelot", "postalCode": "69007", "city": "Lyon"}'
```

```python
import requests

response = requests.put(
    "https://your-instance.bluerocktel.net/api/v1/establishments/7",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    json={"addressLine1": "25 Avenue Berthelot", "postalCode": "69007", "city": "Lyon"},
)
establishment = response.json()
```

```php
$response = Http::withToken($token)
    ->acceptJson()
    ->put('https://your-instance.bluerocktel.net/api/v1/establishments/7', [
        'addressLine1' => '25 Avenue Berthelot',
        'postalCode' => '69007',
        'city' => 'Lyon',
    ]);

$establishment = $response->json();
```

```javascript
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/establishments/7",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      addressLine1: "25 Avenue Berthelot",
      postalCode: "69007",
      city: "Lyon",
    }),
  }
);
const establishment = await response.json();
```

---

## DELETE /v1/establishments/{id}

Delete an establishment. Associated customer files that reference this establishment will have their `establishment_id` automatically set to `null` before deletion.

**URL parameters:**

| Parameter | Type | Description |
|---|---|---|
| `id` | integer | Establishment ID |

**Response 200:** Success message.
**Response 404:** Not found.

**Examples:**

```bash
curl -s -X DELETE "https://your-instance.bluerocktel.net/api/v1/establishments/7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

```python
import requests

response = requests.delete(
    "https://your-instance.bluerocktel.net/api/v1/establishments/7",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
```

```php
$response = Http::withToken($token)
    ->acceptJson()
    ->delete('https://your-instance.bluerocktel.net/api/v1/establishments/7');
```

```javascript
const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/establishments/7",
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
```