Leads

As an Admin, you have full access to create, view, update, and delete leads via the API.

Bulk Create Leads

POST/leads Bearer Token — create leads

Create up to 100 leads in a single request.

Request Body:

{
  "data": [
    {
      "full_name": "Ahmed El Fassi",
      "phone": "0612345678",
      "city": "Casablanca",
      "address": "123 Main Street",
      "data": [
        {
          "key": "note",
          "value": "Prefers afternoon delivery"
        }
      ],
      "area": "Maarif",
      "products": [
        {
          "sku": "SKU-001",
          "quantity": 2,
          "total": 299
        }
      ]
    }
  ]
}

Field	Type	Required	Description	Rules
data	array	Yes	Array of lead objects	max 100 items
data.*.full_name	string	Yes	Customer name	min 3, max 100 characters
data.*.phone	string	Yes	Primary phone	min 7, max 100 characters
data.*.city	string	Yes	City name	min 3, max 100 characters
data.*.area	string	No	Area / district	min 3, max 100 characters
data.*.address	string	Yes	Delivery address	min 5, max 100 characters
data.*.products	array	Yes	Product items	min 1, max 100 items
data.*.products.*.sku	string	Yes	Product SKU	min 1, max 100 characters, must exist in your account
data.*.products.*.quantity	number	Yes	Quantity	min 1, max 999
data.*.products.*.total	number	Yes	Line total	min 1, max 999999
data.*.data	array	No	Custom key/value pairs (per-lead)	max 100 entries
data.*.data.*.key	string	No	Custom field name	min 1, max 100 characters
data.*.data.*.value	string	No	Custom field value	min 1, max 100 characters

Response

Batches of 10 items or fewer are processed synchronously (201). Larger batches return 202 and are processed asynchronously (see Error handling).

Sync success (201):

{
  "data": {
    "created_refs": ["LED-00001"],
    "failed_count": 0
  },
  "meta": {
    "mode": "sync",
    "total": 1
  }
}

created_refs are public references (e.g. LED-00001). Use GET /leads/{reference}/show for the full record.

Async queued (202):

{
  "data": {
    "batch_id": "batch_550e8400-e29b-41d4-a716-446655440000",
    "queued": true
  },
  "meta": {
    "mode": "async",
    "total": 25
  }
}

When failed_count is greater than zero in sync mode, some rows failed during processing; details are sent via webhooks for async batches.

Validation failure (422):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "fields": {
      "data.0.phone": [
        "The phone field is required."
      ],
      "data.1.full_name": [
        "The full name must be between 3 and 100 characters."
      ]
    }
  }
}

List Leads

GET/leads Bearer Token — view leads

Retrieve a paginated list of leads.

Parameter	Type	Required	Description
page	number	No	Page number
per_page	number	No	Results per page
keyword	string	No	Search term
search_by	string	No	Field to search (reference by default)
match_type	string	No	Match mode: exact, partial, starts_with, ends_with
start_at	date	No	Filter from date
end_at	date	No	Filter to date
status	array	No	Filter by lead status values
sub_status	string	No	Sub-status filter
other_status	integer	No	Additional status filter (1–3)
is_processing	boolean	No	Filter processing leads

Response

Success (200):

{
  "data": [
    {
      "reference": "LED-00001",
      "phone": "0612345678",
      "status": "new",
      "city": "Casablanca",
      "area": "Maarif",
      "data": [],
      "products": [],
      "leadHistories": []
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 120,
      "pages": 3
    }
  }
}

Show Lead

GET/leads/{reference}/show Bearer Token — view leads

Retrieve a single lead by reference.

Response

Success (200):

{
  "data": {
    "full_name": "Ahmed El Fassi",
    "phone": "0612345678",
    "city": "Casablanca",
    "area": "Maarif",
    "status": "New",
    "products": [
      {
        "sku": "SKU-001",
        "quantity": 2,
        "price": "299.00 MAD",
        "total": "299.00 MAD"
      }
    ],
    "created_at": "2025-01-16T10:00:00.000000Z"
  },
  "meta": {}
}

Not found (404):

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Lead not found."
  }
}

Update Leads (Bulk)

PUT/leads Bearer Token — update leads

Bulk update leads. Each item must include the lead reference and the new status.

Request Body:

{
  "leads": [
    {
      "reference": "LED-00001",
      "status": "confirmed"
    },
    {
      "reference": "LED-00002",
      "status": "call_later",
      "action_date": "2025-02-01T14:00:00+01:00"
    }
  ]
}

Field	Type	Required	Description	Rules
leads	array	Yes	Array of lead update objects	max 100 items
leads.*.reference	string	Yes	Lead reference	min 1, max 100 characters
leads.*.status	string	Yes	New status	valid lead status key (case-insensitive)
leads.*.action_date	string	No	Action date (required for some statuses)	ISO 8601 (YYYY-MM-DDTHH:MM:SS±HH:MM)

Response

Success (200):

{
  "data": [
    {
      "reference": "LED-00001"
    },
    {
      "reference": "LED-00002"
    }
  ],
  "meta": {
    "updated_fields": ["status", "action_date"]
  }
}

Validation error (422):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "fields": {
      "leads.0.status": [
        "The selected status is invalid."
      ],
      "leads.1.action_date": [
        "The action date is required for status cancelled."
      ]
    }
  }
}

Delete Leads (Bulk)

DELETE/leads Bearer Token — delete leads

Bulk delete leads by ID. Deletion is only allowed when the system permits it based on business conditions (e.g., lead status).

Request Body:

{
  "ids": [
    "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "01ARZ3NDEKTSV4RRFFQ69G5FAW"
  ]
}

Field	Type	Required	Description	Rules
ids	array	Yes	Array of lead IDs	max 100 items
ids.*	string	Yes	Lead ID	min 3, max 100 characters

Response

Success (200):

{
  "data": {
    "deleted": true,
    "count": 2
  },
  "meta": {}
}

Forbidden (403):

{
  "error": {
    "code": "HTTP_ERROR",
    "message": "This action is unauthorized."
  }
}

WARNING

Leads can only be deleted when system conditions allow it, depending on the current lead status and business rules.

---

Lead Statuses

Reference values for status on create/update and filters. There is no GET /lead-statuses endpoint.

Status	Description
new	Fresh lead, not yet contacted
confirmed	Customer confirmed the order
wrong	Invalid or wrong information
testing	Lead is being tested
call_later	Customer asked to be called back
no_reply	No response from customer
cancelled	Lead canceled
out_of_stock	Product was out of stock
duplicate	Duplicate lead
expired	Lead has expired
unreachable	Customer is unreachable
preparing	Lead is being prepared
blacklist	Customer is blacklisted
no_reply_asked_to_recall	No reply, asked to recall