Leads — NexaDesk Docs

Manage your CRM leads programmatically. Create leads from external forms, sync with other CRMs, or build custom dashboards.

List Leads

Retrieve a paginated list of leads with optional filtering and sorting.

GET /api/v1/external/leads

Parameter	Type	Description
`stage`	string	Filter by pipeline stage: `new`, `qualified`, `assigned`, `contacted`, `converted`, `lost`
`search`	string	Search by name, email, or company (case-insensitive partial match)
`sort`	string	Sort field and direction (e.g., `created_at:desc`). Allowed fields: `created_at`, `updated_at`, `lead_score`, `visitor_name`
`limit`	number	Results per page (default 50, max 100)
`cursor`	string	Pagination cursor from previous response
`page`	number	Offset-based page number (alternative to cursor)

bash

curl "https://chats.nexadesk.ai/api/v1/external/leads?stage=new&sort=created_at:desc&limit=10" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

json

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "visitor_name": "Jane Smith",
      "visitor_email": "[email protected]",
      "visitor_phone": "+1-555-0123",
      "visitor_company": "Acme Corp",
      "pipeline_stage": "new",
      "need_summary": "Looking for AI chatbot solution for e-commerce site",
      "tags": ["ecommerce", "high-priority"],
      "source": "widget",
      "expected_billing_amount": 5000,
      "assigned_rep_id": null,
      "rep_first_name": null,
      "rep_last_name": null,
      "rep_email": null,
      "created_at": "2026-03-15T10:30:00.000Z",
      "updated_at": "2026-03-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "MTA",
    "total_count": 142,
    "limit": 10
  }
}

Create Lead

Create a new lead in your CRM pipeline.

POST /api/v1/external/leads

Field	Type	Required	Description
`visitor_name`	string	Yes	Lead's name (max 200 characters)
`visitor_email`	string	No	Email address
`visitor_phone`	string	No	Phone number (max 50 characters)
`visitor_company`	string	No	Company name (max 200 characters)
`pipeline_stage`	string	No	Initial stage: `new` (default), `qualified`, `assigned`, `contacted`, `converted`, `lost`
`need_summary`	string	No	Description of what the lead needs (max 2000 characters)
`tags`	string[]	No	Array of tag strings
`source`	string	No	Lead source (max 100 characters, defaults to "api")
`expected_billing_amount`	number	No	Estimated deal value

bash

curl -X POST "https://chats.nexadesk.ai/api/v1/external/leads" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_name": "John Doe",
    "visitor_email": "[email protected]",
    "visitor_company": "TechCorp",
    "pipeline_stage": "new",
    "need_summary": "Needs chatbot for WordPress site",
    "tags": ["wordpress", "small-business"],
    "source": "contact-form",
    "expected_billing_amount": 1200
  }'

json

{
  "success": true,
  "data": {
    "id": "660e9500-f39c-52e5-b827-557766550000",
    "visitor_name": "John Doe",
    "visitor_email": "[email protected]",
    "visitor_company": "TechCorp",
    "pipeline_stage": "new",
    "need_summary": "Needs chatbot for WordPress site",
    "tags": ["wordpress", "small-business"],
    "source": "contact-form",
    "expected_billing_amount": 1200,
    "created_at": "2026-03-20T14:00:00.000Z",
    "updated_at": "2026-03-20T14:00:00.000Z"
  }
}

Update Lead

Update one or more fields on an existing lead.

PATCH /api/v1/external/leads?id={lead_id}

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	The lead ID to update

All fields are optional. Only provided fields are updated.

Field	Type	Description
`pipeline_stage`	string	New stage: `new`, `qualified`, `assigned`, `contacted`, `converted`, `lost`
`assigned_rep_id`	string (UUID) or null	Assign to a sales rep or unassign
`visitor_name`	string	Updated name
`visitor_email`	string	Updated email
`visitor_phone`	string	Updated phone
`visitor_company`	string	Updated company
`need_summary`	string	Updated needs description
`tags`	string[]	Replace tags array
`expected_billing_amount`	number	Updated deal value

bash

curl -X PATCH "https://chats.nexadesk.ai/api/v1/external/leads?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_stage": "qualified",
    "tags": ["ecommerce", "high-priority", "demo-scheduled"]
  }'

Delete Lead

Permanently delete a lead.

DELETE /api/v1/external/leads?id={lead_id}

bash

curl -X DELETE "https://chats.nexadesk.ai/api/v1/external/leads?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

json

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}