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

Base URL: /api/v1/customers

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

Model Properties

Property	Type	Required	Description
`id`	integer	auto	Unique identifier
`name`	string	Yes (create)	Company or individual name
`brand_id`	integer	No	FK to brands. Determines invoice styling and logos
`representative_id`	integer	No	FK to users. The internal sales representative
`customer_account`	string	auto	Account number (format: `CL` + zero-padded ID, e.g. `CL000123`). Auto-generated on creation
`accounts_reference`	string	No	Reference in the accounting system (e.g. client code in Sage)
`registration_number`	string	No	Company registration number (e.g. SIRET in France)
`tax_registration_number`	string	No	VAT number (e.g. SIREN or EU VAT ID)
`type`	string	No	Legal form of the entity (e.g. `SAS`, `SARL`, `SA`, `Auto-Entrepreneur`)
`capital`	string	No	Share capital amount
`activity_code`	string	No	NAF/APE activity code
`sector_id`	integer	No	FK to sectors. Business sector classification
`origin_id`	integer	No	FK to origins. How the customer was acquired
`email_address`	string	No	Main contact email address
`account_email_address`	string	No	Billing/account email address (for invoices)
`phone`	string	No	Main phone number
`mobile_phone`	string	No	Mobile phone number
`fax`	string	No	Fax number
`main_contact_first_name`	string	No	First name of the main contact person
`main_contact_last_name`	string	No	Last name of the main contact person
`main_address_line1`	string	No	Address line 1
`main_address_line2`	string	No	Address line 2
`main_address_postal_code`	string	No	Postal code
`main_address_city`	string	No	City
`main_address_country`	string	No	Country (default: `France`)
`website`	string	No	Website URL
`active`	boolean	No	Whether the customer is active (default: `true`)
`is_reseller`	boolean	No	Whether the customer is a reseller
`reseller_level`	integer	No	Reseller tier level
`language_id`	integer	No	FK to languages. Preferred language for communications
`charge_vat`	boolean	No	Whether VAT is applied to invoices
`apply_vat_auto_reverse_operators`	boolean	No	Apply auto-reverse VAT for telecom operators
`comment`	text	No	Internal notes or comments
`merge_invoices`	boolean	No	Whether to merge all files into a single invoice
`on_call_duty`	boolean	No	Customer has an on-call duty contract
`vip`	boolean	No	VIP customer flag
`accept_emails`	boolean	No	Customer accepts email communications (default: `true`)
`accept_calls`	boolean	No	Customer accepts phone calls (default: `true`)
`created_at`	datetime	auto	Creation timestamp
`updated_at`	datetime	auto	Last update timestamp

Read-only computed fields (returned in responses):

Property	Type	Description
`quick_search`	text	Full-text search index blob (updated asynchronously)
`quick_search_label`	string	Human-readable label used in search results
`vip_from_task`	boolean	VIP flag set automatically from task rules
`setup_follow_up`	boolean	Whether a setup follow-up is pending
`setup_follow_up_user_id`	integer	FK to user responsible for the setup follow-up

GET /v1/customers

List all customers with pagination and sorting. Results are filtered based on the authenticated user's role.

Query parameters:

Parameter	Type	Description
`nb`	integer	Items per page (default: varies)
`sort`	string	Field to sort by
`direction`	string	Sort direction (`asc` / `desc`)

Response 200: Paginated list of customer objects.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/customers?nb=25&sort=name&direction=asc" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/customers",
    params={"nb": 25, "sort": "name", "direction": "asc"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
customers = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->get('https://your-instance.bluerocktel.net/api/v1/customers', [
        'nb' => 25,
        'sort' => 'name',
        'direction' => 'asc',
    ]);

$customers = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/customers?nb=25&sort=name&direction=asc",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const customers = await response.json();

POST /v1/customers

Create a new customer. A customer_account is auto-generated (format: CL + zero-padded ID).

Body (JSON): Validated against Customer::rules()['store'].

Response 201: Created customer object. Response 422: Validation error.

Examples:

curl -s -X POST "https://your-instance.bluerocktel.net/api/v1/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name": "Acme Corp", "email": "contact@acme.com"}'

import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/customers",
    json={"name": "Acme Corp", "email": "contact@acme.com"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
customer = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->post('https://your-instance.bluerocktel.net/api/v1/customers', [
        'name' => 'Acme Corp',
        'email' => 'contact@acme.com',
    ]);

$customer = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/customers",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ name: "Acme Corp", email: "contact@acme.com" }),
  }
);
const customer = await response.json();

GET /v1/customers/{id}

Get a single customer with related contacts.

URL parameters:

Parameter	Type	Description
`id`	integer	Customer ID

Response 200: Customer object with contacts relation. Response 404: Not found.

Examples:

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

import requests

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

use Illuminate\Support\Facades\Http;

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

$customer = $response->json();

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

PUT /v1/customers/{id}

Update a customer. Resets the quick_search_index flag.

URL parameters:

Parameter	Type	Description
`id`	integer	Customer ID

Body (JSON): Validated against Customer::rules()['update'].

Response 200: Updated customer object. Response 404: Not found. Response 422: Validation error.

Examples:

curl -s -X PUT "https://your-instance.bluerocktel.net/api/v1/customers/42" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name": "Acme Corporation"}'

import requests

response = requests.put(
    "https://your-instance.bluerocktel.net/api/v1/customers/42",
    json={"name": "Acme Corporation"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
customer = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->put('https://your-instance.bluerocktel.net/api/v1/customers/42', [
        'name' => 'Acme Corporation',
    ]);

$customer = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/customers/42",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ name: "Acme Corporation" }),
  }
);
const customer = await response.json();

DELETE /v1/customers/{id}

Delete a customer. Fails if the customer has invoices or customer files. Requires admin/tech role.

URL parameters:

Parameter	Type	Description
`id`	integer	Customer ID

Response 200: Success message. Response 403: Forbidden (insufficient role or ownership). Response 404: Not found.

Examples:

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

import requests

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

use Illuminate\Support\Facades\Http;

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

$result = $response->json();

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

GET /v1/customers/search

Search customers by text query. Returns up to 15 results.

Query parameters:

Parameter	Type	Required	Description
`term`	string	Yes	Search term

Response 200: Array of matching customer objects.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/customers/search?term=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/customers/search",
    params={"term": "acme"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
results = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->get('https://your-instance.bluerocktel.net/api/v1/customers/search', [
        'term' => 'acme',
    ]);

$results = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/customers/search?term=acme",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const results = await response.json();

GET /v1/customers/lookup

Look up a customer by account number or phone number. Used by call center integrations.

Query parameters (one required):

Parameter	Type	Description
`customer_account`	string	Customer account number (e.g. `CL000123`)
`phone_number`	string	Phone number

Response 200:

{
  "found": true,
  "data": {
    "id": 1,
    "name": "...",
    "customer_account": "CL000123",
    "vip": false,
    "on_call_duty": false,
    "setup_follow_up": false,
    "setup_follow_up_user": null
  }
}

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/customers/lookup?customer_account=CL000123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/customers/lookup",
    params={"customer_account": "CL000123"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
result = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->get('https://your-instance.bluerocktel.net/api/v1/customers/lookup', [
        'customer_account' => 'CL000123',
    ]);

$result = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/customers/lookup?customer_account=CL000123",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const result = await response.json();

GET /v1/customers/{id}/consumptions

Get total consumption amount for a customer in a given billing month.

URL parameters:

Parameter	Type	Description
`id`	integer	Customer ID

Query parameters:

Parameter	Type	Required	Description
`month`	string	Yes	Month in `YYYYMM` format

Response 200: Total consumption amount (numeric).

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/customers/42/consumptions?month=202603" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/customers/42/consumptions",
    params={"month": "202603"},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
total = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->get('https://your-instance.bluerocktel.net/api/v1/customers/42/consumptions', [
        'month' => '202603',
    ]);

$total = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/customers/42/consumptions?month=202603",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const total = await response.json();

GET /v1/customers/customer_accounts/{customer_account}

Get the internal customer ID from a customer account string.

URL parameters:

Parameter	Type	Description
`customer_account`	string	Account number (e.g. `CL000123`)

Response 200:

{ "customer_id": 42 }

Examples:

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

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/customers/customer_accounts/CL000123",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
data = response.json()
customer_id = data["customer_id"]

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->get('https://your-instance.bluerocktel.net/api/v1/customers/customer_accounts/CL000123');

$customerId = $response->json('customer_id');

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

GET /v1/customer_accounts/{customer_account}

Get the full customer object from a customer account string.

URL parameters:

Parameter	Type	Description
`customer_account`	string	Account number (e.g. `CL000123`)

Response 200: Customer object. Response 404: Not found.

Examples:

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

import requests

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

use Illuminate\Support\Facades\Http;

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

$customer = $response->json();

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

Deprecated Endpoints

The following endpoints are deprecated. Use /v1/customers/lookup instead, which consolidates all of these checks into a single request returning found, vip, on_call_duty, and customer details.

Endpoint	Description
`GET /is_known_customer_account`	Check if a customer account exists
`GET /is_known_phone_number`	Check if a phone number is known
`GET /is_vip_by_customer_account`	Check VIP status by account
`GET /is_vip_by_phone_number`	Check VIP status by phone
`GET /has_on_call_duty_contract_by_phone_number`	Check on-call duty by phone
`GET /has_on_call_duty_contract_by_customer_account`	Check on-call duty by account
`GET /get_customer_id_from_phone_number`	Get customer ID by phone number