Leads

Manage CRM leads programmatically.

List leads

GET /v1/leads

Query parameters

Parameter	Type	Description
`pageSize`	integer	Results per page (default `10`, max `100`)
`pageIndex`	integer	Zero-based page index (default `0`)
`search`	string	Search by name or email
`lead_status`	string	`New` \| `Contacted` \| `Qualified` \| `Lost` \| `Converted`
`sortBy`	string	Field to sort by
`sortOrder`	string	`asc` \| `desc`

Example response

{
  "success": true,
  "data": {
    "data": [
      {
        "cstid": 42,
        "ct_number": "LED-0042",
        "cstname": "Sarah Johnson",
        "cstemail": "sarah@acmecorp.com",
        "lead_status": "New",
        "lead_source": "Website",
        "lead_company_name": "Acme Corp",
        "owner": "John Smith",
        "cstcreated_on": "2026-06-01T09:00:00Z"
      }
    ],
    "current_page": 1,
    "total_records": 84,
    "total_pages": 9
  }
}

Create a lead

POST /v1/leads
Content-Type: application/json

Request body

Field	Type	Required	Description
`cstname`	string	yes	Lead name (max 100 chars)
`cstemail`	string	no	Email address
`cstmobile`	string	no	Phone number digits only
`cstmobile_country_id`	integer	no	Country ID for ISD prefix
`cstaddress`	string	no	Address
`cstnotes`	string	no	Notes / description
`lead_source`	string	no	e.g. `"Website"`, `"Referral"`
`lead_industry`	string	no	Industry
`lead_company_name`	string	no	Company name
`lead_assignedto`	integer	no	User ID to assign the lead to
`lead_assignmentgroup`	integer	no	User group ID
`brand_id`	integer	no	Brand ID
`tag_ids`	integer[]	no	Array of tag IDs
`tag_names`	string[]	no	Array of existing lead tag names. Names are matched case-insensitively within the authenticated organisation.
`custom_fields`	object	no	Custom field values keyed by field name — e.g. `{"budget": "5000", "region": "North"}`

Custom fields: Keys must match the custom field names configured in your YSUITE organisation. Passing an empty object {} clears all custom field values on the record.

Tip: You can pass a full international number in cstmobile (e.g. "+971501234567") without setting cstmobile_country_id — the API will auto-detect the ISD prefix.

Example request

{
  "cstname": "Sarah Johnson",
  "cstemail": "sarah@acmecorp.com",
  "cstmobile": "+971501234567",
  "lead_source": "Website",
  "lead_company_name": "Acme Corp",
  "tag_names": ["Website", "Priority"],
  "custom_fields": {
    "budget": "5000",
    "preferred_contact_time": "Morning"
  }
}

Example response

{
  "success": true,
  "message": "Lead created successfully!",
  "data": {
    "cstid": 42,
    "ct_number": "LED-0042",
    "cstname": "Sarah Johnson"
  }
}

Delete a lead

DELETE /v1/leads/{id}

Parameter	Description
`id`	The `cstid` of the lead

Example response

{
  "success": true,
  "message": "Lead deleted successfully"
}