Leads API

The Leads API gives you full control over the leads that Synaptiq captures from AI-powered conversations. Create leads from external sources, enrich existing records, search across your pipeline, and sync data with your CRM.

List Leads

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

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number. Default: 1.
limit	integer	No	Results per page. Min: 1, Max: 100. Default: 25.
status	string	No	Filter by status: new, qualified, contacted, converted, lost.
source	string	No	Filter by source: chat, api, import, form.
sortBy	string	No	Sort field: createdAt, updatedAt, score. Default: createdAt.
sortOrder	string	No	Sort direction: asc or desc. Default: desc.
createdAfter	string	No	ISO 8601 date. Return leads created after this date.
createdBefore	string	No	ISO 8601 date. Return leads created before this date.

Request

curl "https://synaptiqintel.com/api/v1/leads?status=qualified&limit=10&sortBy=score&sortOrder=desc" \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

Response

{
  "data": [
    {
      "id": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
      "email": "sarah.chen@acmecorp.com",
      "name": "Sarah Chen",
      "company": "Acme Corp",
      "title": "VP of Sales",
      "phone": "+1-555-0142",
      "status": "qualified",
      "score": 87,
      "source": "chat",
      "tags": ["enterprise", "demo-requested"],
      "customFields": {
        "industry": "SaaS",
        "teamSize": "50-100"
      },
      "firstSeenAt": "2026-04-01T09:15:00.000Z",
      "lastActiveAt": "2026-04-05T11:42:00.000Z",
      "createdAt": "2026-04-01T09:15:00.000Z",
      "updatedAt": "2026-04-05T11:42:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 48,
    "totalPages": 5,
    "hasMore": true
  }
}

Get a Lead

Retrieve a single lead by its ID, including full conversation history summary and activity timeline.

Request

curl https://synaptiqintel.com/api/v1/leads/lead_01HQ3VXK9BWMN4F6T2P8R5GYSC \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

Response

{
  "id": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
  "email": "sarah.chen@acmecorp.com",
  "name": "Sarah Chen",
  "company": "Acme Corp",
  "title": "VP of Sales",
  "phone": "+1-555-0142",
  "status": "qualified",
  "score": 87,
  "source": "chat",
  "tags": ["enterprise", "demo-requested"],
  "customFields": {
    "industry": "SaaS",
    "teamSize": "50-100"
  },
  "conversationCount": 3,
  "lastIntent": "demo_request",
  "assignedTo": "user_01HQ3VXK9BWMN4F6T2P8R5GYSD",
  "firstSeenAt": "2026-04-01T09:15:00.000Z",
  "lastActiveAt": "2026-04-05T11:42:00.000Z",
  "createdAt": "2026-04-01T09:15:00.000Z",
  "updatedAt": "2026-04-05T11:42:00.000Z"
}

Create a Lead

Create a new lead manually. Useful for importing leads from external sources or forms.

Request Body

Parameter	Type	Required	Description
email	string	Yes	The lead's email address. Must be unique.
name	string	No	Full name of the lead.
company	string	No	Company or organization name.
title	string	No	Job title.
phone	string	No	Phone number in E.164 format.
status	string	No	Initial status. Default: new.
source	string	No	Lead source. Default: api.
tags	string[]	No	Array of tags for categorization.
customFields	object	No	Key-value pairs for custom data.
assignedTo	string	No	User ID of the assigned sales rep.

Request

curl -X POST https://synaptiqintel.com/api/v1/leads \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "james.rodriguez@techstart.io",
    "name": "James Rodriguez",
    "company": "TechStart",
    "title": "CTO",
    "phone": "+1-555-0198",
    "status": "new",
    "source": "api",
    "tags": ["inbound", "startup"],
    "customFields": {
      "industry": "FinTech",
      "teamSize": "10-25",
      "budget": "$5k-$10k/mo"
    }
  }'

Response (201 Created)

{
  "id": "lead_01HQ6JKL8MWPN3D5R7S9T1UVWX",
  "email": "james.rodriguez@techstart.io",
  "name": "James Rodriguez",
  "company": "TechStart",
  "title": "CTO",
  "phone": "+1-555-0198",
  "status": "new",
  "score": 0,
  "source": "api",
  "tags": ["inbound", "startup"],
  "customFields": {
    "industry": "FinTech",
    "teamSize": "10-25",
    "budget": "$5k-$10k/mo"
  },
  "firstSeenAt": "2026-04-05T15:08:42.000Z",
  "lastActiveAt": "2026-04-05T15:08:42.000Z",
  "createdAt": "2026-04-05T15:08:42.000Z",
  "updatedAt": "2026-04-05T15:08:42.000Z"
}

Update a Lead

Update one or more fields on an existing lead. Only the fields you include in the request body will be modified.

Request

curl -X PATCH https://synaptiqintel.com/api/v1/leads/lead_01HQ6JKL8MWPN3D5R7S9T1UVWX \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified",
    "tags": ["inbound", "startup", "hot-lead"],
    "customFields": {
      "industry": "FinTech",
      "teamSize": "10-25",
      "budget": "$5k-$10k/mo",
      "nextStep": "Schedule demo"
    }
  }'

Response (200 OK)

{
  "id": "lead_01HQ6JKL8MWPN3D5R7S9T1UVWX",
  "email": "james.rodriguez@techstart.io",
  "name": "James Rodriguez",
  "company": "TechStart",
  "title": "CTO",
  "phone": "+1-555-0198",
  "status": "qualified",
  "score": 34,
  "source": "api",
  "tags": ["inbound", "startup", "hot-lead"],
  "customFields": {
    "industry": "FinTech",
    "teamSize": "10-25",
    "budget": "$5k-$10k/mo",
    "nextStep": "Schedule demo"
  },
  "firstSeenAt": "2026-04-05T15:08:42.000Z",
  "lastActiveAt": "2026-04-05T15:22:10.000Z",
  "createdAt": "2026-04-05T15:08:42.000Z",
  "updatedAt": "2026-04-05T15:22:10.000Z"
}

Search Leads

Full-text search across lead names, emails, companies, and custom fields.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query. Min 2 characters.
page	integer	No	Page number. Default: 1.
limit	integer	No	Results per page. Max: 100. Default: 25.
status	string	No	Filter results by lead status.

Request

curl "https://synaptiqintel.com/api/v1/leads/search?q=acme&status=qualified" \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

Response

{
  "data": [
    {
      "id": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
      "email": "sarah.chen@acmecorp.com",
      "name": "Sarah Chen",
      "company": "Acme Corp",
      "status": "qualified",
      "score": 87,
      "matchField": "company",
      "lastActiveAt": "2026-04-05T11:42:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

Error Responses

Status Code	Error	Description
400	invalid_request	Validation error. Check the details array.
401	unauthorized	Invalid or missing API key.
404	not_found	Lead with the given ID does not exist.
409	conflict	A lead with this email already exists.
422	unprocessable	The request body is valid JSON but semantically wrong.

{
  "error": {
    "code": "conflict",
    "message": "A lead with email 'sarah.chen@acmecorp.com' already exists.",
    "existingLeadId": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
    "doc_url": "https://synaptiqintel.com/docs/api-reference/leads-api"
  }
}