Skip to main content
Core Resources

Prospects

Manage sales prospects with auto-generated account numbers, full-text search, and prospect-to-customer conversion.

Base URL: /api/v1/prospects

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

Model Properties

Property Type Required Description
id integer auto Unique identifier
name string Yes Company or individual name (min 2 chars)
brand_id integer No FK to brands
representative_id integer No FK to users. The assigned sales representative. Automatically set to the authenticated user for role-5 users
customer_account string auto Account number (format: PR + zero-padded ID, e.g. PR000042). Auto-generated on creation
accounts_reference string No Reference in the accounting system
registration_number string No Company registration number
tax_registration_number string No VAT number
type string No Legal form of the entity
capital string No Share capital
activity_code string No NAF/APE activity code
sector_id integer No FK to sectors
cluster_id integer No FK to clusters. Geographic or strategic cluster
batch_id integer No FK to batches
email_address string No Main contact email address
account_email_address string No Billing/account email address
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
main_contact_last_name string No Last name of the main contact
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 prospect is active
charge_vat boolean No Whether VAT is applied
comment text No Internal notes
merge_invoices boolean No Whether to merge all files into a single invoice
prospection_code_id integer No FK to prospection_codes. Current stage in the sales pipeline
accept_emails boolean No Whether the prospect accepts email communications (default: true)
accept_calls boolean No Whether the prospect accepts phone calls (default: true)
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

GET /v1/prospects

List prospects with filtering, sorting, and pagination (Spatie QueryBuilder). Filtered by user role: role-5 users only see prospects visible to sales (viewable_by_sale scope).

Query parameters:

Parameter Type Description
filter[name] string Filter by name
filter[id] integer Filter by exact ID
filter[term_match] string Full-text term match
sort string Sort field (id, created_at, updated_at)
per_page integer Items per page

Response 200: Paginated list of prospect objects.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/prospects?filter[name]=Acme&sort=-created_at&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/prospects",
    params={"filter[name]": "Acme", "sort": "-created_at", "per_page": 25},
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
)
prospects = response.json()

use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://your-instance.bluerocktel.net/api/v1/prospects', [
        'filter[name]' => 'Acme',
        'sort' => '-created_at',
        'per_page' => 25,
    ]);

$prospects = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/prospects?filter[name]=Acme&sort=-created_at&per_page=25",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);
const prospects = await response.json();

POST /v1/prospects

Create a new prospect. A customer_account is auto-generated (format: PR + zero-padded ID). Role-5 users automatically have their ID set as representative_id.

Body (JSON): Validated against prospect model attributes (common, store).

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

Examples:

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

import requests

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

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

$prospect = $response->json();

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

GET /v1/prospects/{id}

Get a single prospect with payment_plan, contacts, and documents loaded. Authorization policy enforced.

URL parameters:

Parameter Type Description
id integer Prospect ID

Response 200: Prospect object with relations. Response 403: Forbidden. Response 404: Not found.

Examples:

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

import requests

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

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

$prospect = $response->json();

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

PUT /v1/prospects/{id}

Update a prospect. Role-5 users cannot change representative_id. Auto-generates customer_account if empty.

URL parameters:

Parameter Type Description
id integer Prospect ID

Body (JSON): Validated prospect fields.

Response 201: Updated prospect object. Response 403: Forbidden (role-5 trying to change rep). Response 404: Not found. Response 422: Validation error.

DELETE /v1/prospects/{id}

Delete a prospect.

URL parameters:

Parameter Type Description
id integer Prospect ID

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

Next Contacts