Leads

As a Seller, you can 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:

json

{
  "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):

json

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

created_refs are internal IDs. Use GET /leads/{reference}/show with the lead reference for the full record.

Async queued (202):

json

{
  "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):

json

{
  "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 your 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

Response

Success (200):

json

{
  "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):

json

{
  "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):

json

{
  "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:

json

{
  "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):

json

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

Validation error (422):

json

{
  "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:

json

{
  "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):

json

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

Forbidden (403):

json

{
  "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

GET/lead-statuses Bearer Token

List all available lead statuses.

Response

Success (200):

json

{
  "data": [
    {
      "key": "new",
      "label": "New"
    },
    {
      "key": "confirmed",
      "label": "Confirmed"
    },
    {
      "key": "wrong",
      "label": "Wrong"
    },
    {
      "key": "testing",
      "label": "Testing"
    },
    {
      "key": "call_later",
      "label": "Call Later"
    },
    {
      "key": "no_reply",
      "label": "No Reply"
    },
    {
      "key": "cancelled",
      "label": "Cancelled"
    },
    {
      "key": "out_of_stock",
      "label": "Out of Stock"
    },
    {
      "key": "duplicate",
      "label": "Duplicate"
    },
    {
      "key": "expired",
      "label": "Expired"
    },
    {
      "key": "unreachable",
      "label": "Unreachable"
    },
    {
      "key": "preparing",
      "label": "Preparing"
    },
    {
      "key": "blacklist",
      "label": "Blacklist"
    },
    {
      "key": "no_reply_asked_to_recall",
      "label": "No Reply Asked to Recall"
    }
  ],
  "meta": {}
}

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

Leads ​

Bulk Create Leads ​

Response ​

List Leads ​

Response ​

Show Lead ​

Response ​

Update Leads (Bulk) ​

Response ​

Delete Leads (Bulk) ​

Response ​

Lead Statuses ​

Response ​

Leads

Bulk Create Leads

Response

List Leads

Response

Show Lead

Response

Update Leads (Bulk)

Response

Delete Leads (Bulk)

Response

Lead Statuses

Response