Establishments — API Documentation — BSS for MSP, Telecom & Cloud

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:

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"

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()

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();

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:

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"}'

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()

$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();

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:

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

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()

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

$establishment = $response->json();

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:

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"}'

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()

$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();

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:

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

import requests

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

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

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