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