Add Prospects to Lead List

{
  "prospects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "firstName": "John",
      "lastName": "Smith",
      "jobTitle": "VP of Sales",
      "city": "San Francisco",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/johnsmith",
      "emails": ["john.smith@example.com"],
      "phones": ["+1-555-123-4567"],
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "seniority": "vp",
      "departments": ["sales"],
      "functions": ["business_development"]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "firstName": "Jane",
      "lastName": "Doe",
      "jobTitle": "Marketing Director",
      "city": "New York",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe",
      "emails": ["jane.doe@example.com"],
      "phones": [],
      "companyId": "660e8400-e29b-41d4-a716-446655440002",
      "seniority": "director",
      "departments": ["marketing"],
      "functions": ["marketing"]
    }
  ]
}

{
  "addedCount": 15
}

POST

api

entities

leadlists

{id}

add-prospects

{
  "prospects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "firstName": "John",
      "lastName": "Smith",
      "jobTitle": "VP of Sales",
      "city": "San Francisco",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/johnsmith",
      "emails": ["john.smith@example.com"],
      "phones": ["+1-555-123-4567"],
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "seniority": "vp",
      "departments": ["sales"],
      "functions": ["business_development"]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "firstName": "Jane",
      "lastName": "Doe",
      "jobTitle": "Marketing Director",
      "city": "New York",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe",
      "emails": ["jane.doe@example.com"],
      "phones": [],
      "companyId": "660e8400-e29b-41d4-a716-446655440002",
      "seniority": "director",
      "departments": ["marketing"],
      "functions": ["marketing"]
    }
  ]
}

{
  "addedCount": 15
}

Adds prospects to an existing lead list. This endpoint supports two modes of operation:

Direct Data Mode: Provide full prospect data objects directly
Bulk Selection Mode: Provide a selection payload that references prospects from a search result

The endpoint automatically handles syncing prospects from the global database to the tenant database before adding them to the list.

Authentication

This endpoint requires authentication. The user must be signed in and have access to the target lead list.

Only users listed in the lead list’s userIds array (or admin users) can add prospects to the list.

This endpoint only works with person-type lead lists. Attempting to add prospects to a company-type list will result in an error.

Request

Path Parameters

string (UUID)

required

The unique identifier of the lead list to add prospects to.

Body Parameters

The request body accepts one of two formats:

Option 1: Direct Prospect Data

prospects

array

required

Array of person objects to add to the lead list. Each person object contains the prospect’s complete profile data.

Show Person object properties

prospects[].id

string (UUID)

Unique identifier for the person.

prospects[].firstName

string

required

The prospect’s first name.

prospects[].lastName

string

required

The prospect’s last name.

prospects[].jobTitle

string | null

The prospect’s current job title.

prospects[].city

string | null

The prospect’s city location.

prospects[].country

string | null

The prospect’s country location.

prospects[].linkedinUrl

string | null

URL to the prospect’s LinkedIn profile.

prospects[].emails

array

Array of email addresses for the prospect.

prospects[].phones

array

Array of phone numbers for the prospect.

prospects[].companyId

string | null

ID of the prospect’s current company.

prospects[].seniority

string | null

The prospect’s seniority level (e.g., “senior”, “manager”, “director”, “c_suite”).

prospects[].departments

array

Array of department names the prospect belongs to.

prospects[].functions

array

Array of job functions the prospect performs.

Option 2: Bulk Selection

selection

object

required

A bulk selection payload that describes which prospects to add based on a previous search.

Show Selection object properties

selection.mode

string

required

The selection mode. Must be one of:

"manual" - Explicitly selected individual rows by ID
"bulk" - Intent-based selection specifying a count from search results

selection.includedIds

array

Array of person IDs to explicitly include. Required for manual mode.

selection.excludedIds

array

Array of person IDs to exclude from the bulk selection range. Used with bulk mode.

selection.startIndex

integer

The starting index in the search results for bulk selection. Used with bulk mode.

selection.targetCount

integer

The number of prospects to select starting from startIndex. Maximum: 1000. Used with bulk mode.

selection.filters

object

The search filters used to reproduce the exact search results. Required for bulk mode.

Show Filter object structure

selection.filters.account

object

Company/account filters including industry, location, employee size, revenue, etc.

selection.filters.contact

object

Contact/person filters including name, title, seniority, skills, etc.

selection.filters.page

integer

Page number for pagination (0-indexed).

selection.filters.size

integer

Number of results per page (max 100).

Request Examples

{
  "prospects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "firstName": "John",
      "lastName": "Smith",
      "jobTitle": "VP of Sales",
      "city": "San Francisco",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/johnsmith",
      "emails": ["john.smith@example.com"],
      "phones": ["+1-555-123-4567"],
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "seniority": "vp",
      "departments": ["sales"],
      "functions": ["business_development"]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "firstName": "Jane",
      "lastName": "Doe",
      "jobTitle": "Marketing Director",
      "city": "New York",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe",
      "emails": ["jane.doe@example.com"],
      "phones": [],
      "companyId": "660e8400-e29b-41d4-a716-446655440002",
      "seniority": "director",
      "departments": ["marketing"],
      "functions": ["marketing"]
    }
  ]
}

Response

Returns an object indicating how many prospects were added to the lead list.

addedCount

integer

required

The number of prospects that were successfully added to the lead list. This excludes any prospects that were already in the list.

Response Examples

{
  "addedCount": 15
}

Error Codes

Status Code	Error Code	Description
400	`BAD_REQUEST`	Request body validation failed. Check the `details` field for specific field errors.
401	`UNAUTHORIZED`	User is not authenticated or organization ID is missing.
403	`FORBIDDEN`	User does not have access to the specified lead list.
404	`NOT_FOUND`	The specified lead list does not exist.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

Behavior Notes

Duplicate Handling

Prospects that already exist in the lead list are automatically skipped. The addedCount in the response reflects only newly added prospects.

Tenant Synchronization

When adding prospects, the system automatically copies person records from the global database to the tenant’s database. This ensures data isolation between organizations.

List Type Validation

This endpoint only works with person-type lead lists (type: "person"). For company-type lists, use the /add-companies endpoint instead.

Bulk Selection Limits

The maximum number of prospects that can be selected in bulk mode is 1,000. For larger selections, make multiple API calls.

Add Companies to Lead List Get Leads by List

​Authentication

​Request

​Path Parameters

​Body Parameters

​Option 1: Direct Prospect Data

​Option 2: Bulk Selection

​Request Examples

​Response

​Response Examples

​Error Codes

​Behavior Notes

Authentication

Request

Path Parameters

Body Parameters

Option 1: Direct Prospect Data

Option 2: Bulk Selection

Request Examples

Response

Response Examples

Error Codes

Behavior Notes