{
"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"]
}
]
}
{
"selection": {
"mode": "manual",
"includedIds": [
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002",
"550e8400-e29b-41d4-a716-446655440003"
]
}
}
{
"selection": {
"mode": "bulk",
"startIndex": 0,
"targetCount": 100,
"excludedIds": ["550e8400-e29b-41d4-a716-446655440005"],
"filters": {
"account": {
"industry": {
"any": {
"include": ["software development", "it services and it consulting"]
}
},
"employeeSize": {
"type": "RANGE",
"range": [{ "start": 50, "end": 500 }]
}
},
"contact": {
"seniority": {
"any": {
"include": ["director", "vp", "c_suite"]
}
},
"departmentAndFunction": {
"any": {
"include": ["sales", "marketing"]
}
}
},
"page": 0,
"size": 100
}
}
}
{
"addedCount": 15
}
{
"addedCount": 0
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{
"path": ["prospects", 0, "firstName"],
"message": "Required"
}
]
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Organization ID required"
}
}
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList not found: 550e8400-e29b-41d4-a716-446655440000"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Lead Lists
Add Prospects to Lead List
Adds prospects (persons) to an existing lead list using either direct data or bulk selection
POST
/
api
/
v1
/
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"]
}
]
}
{
"selection": {
"mode": "manual",
"includedIds": [
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002",
"550e8400-e29b-41d4-a716-446655440003"
]
}
}
{
"selection": {
"mode": "bulk",
"startIndex": 0,
"targetCount": 100,
"excludedIds": ["550e8400-e29b-41d4-a716-446655440005"],
"filters": {
"account": {
"industry": {
"any": {
"include": ["software development", "it services and it consulting"]
}
},
"employeeSize": {
"type": "RANGE",
"range": [{ "start": 50, "end": 500 }]
}
},
"contact": {
"seniority": {
"any": {
"include": ["director", "vp", "c_suite"]
}
},
"departmentAndFunction": {
"any": {
"include": ["sales", "marketing"]
}
}
},
"page": 0,
"size": 100
}
}
}
{
"addedCount": 15
}
{
"addedCount": 0
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{
"path": ["prospects", 0, "firstName"],
"message": "Required"
}
]
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Organization ID required"
}
}
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList not found: 550e8400-e29b-41d4-a716-446655440000"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
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
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
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
Show Person object properties
string (UUID)
Unique identifier for the person.
string
required
The prospect’s first name.
string
required
The prospect’s last name.
string | null
The prospect’s current job title.
string | null
The prospect’s city location.
string | null
The prospect’s country location.
string | null
URL to the prospect’s LinkedIn profile.
array
Array of email addresses for the prospect.
array
Array of phone numbers for the prospect.
string | null
ID of the prospect’s current company.
string | null
The prospect’s seniority level (e.g., “senior”, “manager”, “director”, “c_suite”).
array
Array of department names the prospect belongs to.
array
Array of job functions the prospect performs.
Option 2: Bulk Selection
object
required
A bulk selection payload that describes which prospects to add based on a previous search.
Show Selection object properties
Show Selection object properties
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
array
Array of person IDs to explicitly include. Required for
manual mode.array
Array of person IDs to exclude from the bulk selection range. Used with
bulk mode.integer
The starting index in the search results for bulk selection. Used with
bulk mode.integer
The number of prospects to select starting from
startIndex. Maximum: 1000. Used with bulk mode.object
The search filters used to reproduce the exact search results. Required for
bulk mode.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"]
}
]
}
{
"selection": {
"mode": "manual",
"includedIds": [
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002",
"550e8400-e29b-41d4-a716-446655440003"
]
}
}
{
"selection": {
"mode": "bulk",
"startIndex": 0,
"targetCount": 100,
"excludedIds": ["550e8400-e29b-41d4-a716-446655440005"],
"filters": {
"account": {
"industry": {
"any": {
"include": ["software development", "it services and it consulting"]
}
},
"employeeSize": {
"type": "RANGE",
"range": [{ "start": 50, "end": 500 }]
}
},
"contact": {
"seniority": {
"any": {
"include": ["director", "vp", "c_suite"]
}
},
"departmentAndFunction": {
"any": {
"include": ["sales", "marketing"]
}
}
},
"page": 0,
"size": 100
}
}
}
Response
Returns an object indicating how many prospects were added to the lead list.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
}
{
"addedCount": 0
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{
"path": ["prospects", 0, "firstName"],
"message": "Required"
}
]
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Organization ID required"
}
}
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList not found: 550e8400-e29b-41d4-a716-446655440000"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
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
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
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
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
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.