Leads

The Leads resource is available via both the REST API (bearer token) and the Dashboard (session auth).

REST API Endpoints

Bulk Create Leads

POST/api/web/1.0/leads🔒 Bearer Token — CREATE LEADS

Create multiple leads in a single request. Maximum 1,000 leads per request.

Request Body:

Field	Type	Required	Description
leads	array	Yes	Array of lead objects (max 1,000)
leads.*.phone	string	Yes	Phone number (7–100 chars)
leads.*.full_name	string	Yes	Full name (3–100 chars)
leads.*.city	string	No	City name (3–100 chars)
leads.*.area	string	No	Area/district (3–100 chars)
leads.*.address	string	No	Address (5–100 chars)
leads.*.data	array	No	Custom key-value pairs (max 100)
leads.*.data.*.key	string	No	Custom field key (1–100 chars)
leads.*.data.*.value	string	No	Custom field value (1–100 chars)
leads.*.products	array	Yes	Products array (min 1, max 100)
leads.*.products.*.sku	string	Yes	Product SKU — must exist in your account
leads.*.products.*.quantity	number	Yes	Quantity (1–999)
leads.*.products.*.price	number	Yes	Price per unit (1–999,999)

Example Request:

curl -X POST "https://your-domain.com/api/web/1.0/leads" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "phone": "+212600000001",
        "full_name": "Ahmed Benali",
        "city": "Casablanca",
        "address": "123 Boulevard Mohammed V",
        "products": [
          { "sku": "PROD-001", "quantity": 2, "price": 199 }
        ],
        "data": [
          { "key": "source", "value": "facebook-ad" }
        ]
      },
      {
        "phone": "+212600000002",
        "full_name": "Fatima Zahra",
        "city": "Rabat",
        "products": [
          { "sku": "PROD-002", "quantity": 1, "price": 349 }
        ]
      }
    ]
  }'

Example Response (201):

{
  "message": "Leads created successfully."
}

Important

The sku in each product must match an active product in your account. If any SKU is invalid, the entire request is rejected.

List Leads

GET/api/web/1.0/leads🔒 Bearer Token — VIEW LEADS

Retrieve a paginated list of leads.

Query Parameters:

Parameter	Type	Required	Description
search_by	string	No	Field to search: reference, phone, full_name, city
keyWord	string	No	Search keyword
per_page	number	No	Results per page

Example Request:

curl -X GET "https://your-domain.com/api/web/1.0/leads?per_page=25&search_by=phone&keyWord=0600" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response (200):

{
  "data": [
    {
      "reference": "LD-00001",
      "full_name": "Ahmed Benali",
      "phone": "+212600000001",
      "city": "Casablanca",
      "status": "new",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 5, "per_page": 25, "total": 120 }
}

Show Lead

GET/api/web/1.0/leads/{reference}/show🔒 Bearer Token — VIEW LEADS

Retrieve a single lead by its reference.

Path Parameters:

Parameter	Type	Description
reference	string	The lead reference (e.g., LD-00001)

Example Request:

curl -X GET "https://your-domain.com/api/web/1.0/leads/LD-00001/show" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Update Leads (Bulk)

PUT/api/web/1.0/leads🔒 Bearer Token — UPDATE LEADS

Update statuses for multiple leads. Maximum 1,000 per request.

Request Body:

Field	Type	Required	Description
leads	array	Yes	Array of lead updates (max 1,000)
leads.*.reference	string	Yes	Lead reference
leads.*.status	string	Yes	New status (see statuses below)
leads.*.action_date	string	No	Date in ISO 8601 format (Y-m-d\TH:i:sP). Required for certain statuses

Example Request:

curl -X PUT "https://your-domain.com/api/web/1.0/leads" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "reference": "LD-00001",
        "status": "confirmed",
        "action_date": "2025-01-15T14:00:00+01:00"
      }
    ]
  }'

Delete Leads (Bulk)

DELETE/api/web/1.0/leads🔒 Bearer Token — DELETE LEADS

Delete multiple leads by their references. Only leads with a deletable status can be removed.

Request Body:

Field	Type	Required	Description
references	array	Yes	Array of lead reference strings

Example Request:

curl -X DELETE "https://your-domain.com/api/web/1.0/leads" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "references": ["LD-00001", "LD-00002"]
  }'

INFO

Only leads with a status that is open to deletion can be removed. Attempting to delete a lead with a protected status will result in a validation error.

---

Dashboard Endpoints

These endpoints require session authentication and enforce policy-based authorization.

List Leads

GET/leads🔒 Session — can viewAny

Paginated list of leads with filters.

Supports filtering via LeadQueryFilterService. Results are paginated with perPage parameter.

Roles: Admin (all account leads), Seller (own account leads)

Create Lead

POST/leads/store🔒 Session — can create

Create a single lead from the dashboard.

Field	Type	Required	Description
name	string	Yes	Phone number (unique per account)
status	string	Yes	Initial lead status

Show Lead

GET/leads/{lead}/show🔒 Session — can view

View a single lead with full details.

Update Lead

PATCH/leads/{lead}/update🔒 Session — can update

Update lead details.

Field	Type	Required	Description
status	string	Yes	Lead status
full_name	string	Yes	Full name
phone	string	Yes	Phone number
city_id	string	No	City ID (must exist)

Delete Leads (Bulk)

DELETE/leads/delete🔒 Session — can delete

Bulk delete leads by IDs. Also removes associated LeadHistory records.

Field	Type	Required	Description
ids	array	Yes	Array of lead IDs to delete

Import Leads

POST/leads/import🔒 Session — can import

Import leads from an Excel/CSV file. Processed asynchronously via background queue.

Field	Type	Required	Description
file	file	Yes	.xlsx or .csv file. Required columns: phone, sku

Export Leads

POST/leads/export🔒 Session — can export

Export filtered leads to a file. Processed asynchronously via background queue.

Field	Type	Required	Description
file_extension	string	Yes	Export format

Applies the same filters as the list endpoint.

Lead Statuses

Leads progress through the following statuses. The exact values are defined by LeadStatus enum:

Status	Description
new	Freshly created lead
confirmed	Agent confirmed the lead
wrong	Invalid/wrong number
call_later	Customer asked to call back
no_answer	No response from customer
duplicate	Duplicate lead
canceled	Lead canceled