{
"companyIds": ["550e8400-e29b-41d4-a716-446655440001"]
}
{
"companyIds": [
"550e8400-e29b-41d4-a716-446655440001",
"660e8400-e29b-41d4-a716-446655440002",
"770e8400-e29b-41d4-a716-446655440003"
]
}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"icpId": "660e8400-e29b-41d4-a716-446655440001",
"name": "Enterprise Accounts Q1",
"type": "company",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-03-31T23:59:59.000Z",
"personIds": [],
"companyIds": [
"770e8400-e29b-41d4-a716-446655440001",
"770e8400-e29b-41d4-a716-446655440002"
],
"userIds": ["user_xyz789"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-15T14:22:00.000Z",
"companies": [
{
"id": "770e8400-e29b-41d4-a716-446655440001",
"name": "Acme Corporation",
"domain": "acme.com",
"industry": "Technology",
"headcount": "201-500",
"linkedinUrl": "https://www.linkedin.com/company/acme",
"websiteUrl": "https://acme.com",
"city": "San Francisco",
"country": "United States"
},
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "TechStart Inc",
"domain": "techstart.io",
"industry": "Software",
"headcount": "51-200",
"linkedinUrl": "https://www.linkedin.com/company/techstart",
"websiteUrl": "https://techstart.io",
"city": "Austin",
"country": "United States"
}
]
}
{
"addedCount": 0
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid uuid"
}
}
{
"error": {
"code": "BAD_REQUEST",
"message": "At least one company ID is required"
}
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Cannot add companies to a person-type list. This list is of type 'person'."
}
}
{
"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"
}
}
Lead Lists
Add Companies to Lead List
Adds one or more companies to an existing company-type lead list
POST
/
api
/
v1
/
entities
/
leadlists
/
{id}
/
add-companies
{
"companyIds": ["550e8400-e29b-41d4-a716-446655440001"]
}
{
"companyIds": [
"550e8400-e29b-41d4-a716-446655440001",
"660e8400-e29b-41d4-a716-446655440002",
"770e8400-e29b-41d4-a716-446655440003"
]
}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"icpId": "660e8400-e29b-41d4-a716-446655440001",
"name": "Enterprise Accounts Q1",
"type": "company",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-03-31T23:59:59.000Z",
"personIds": [],
"companyIds": [
"770e8400-e29b-41d4-a716-446655440001",
"770e8400-e29b-41d4-a716-446655440002"
],
"userIds": ["user_xyz789"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-15T14:22:00.000Z",
"companies": [
{
"id": "770e8400-e29b-41d4-a716-446655440001",
"name": "Acme Corporation",
"domain": "acme.com",
"industry": "Technology",
"headcount": "201-500",
"linkedinUrl": "https://www.linkedin.com/company/acme",
"websiteUrl": "https://acme.com",
"city": "San Francisco",
"country": "United States"
},
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "TechStart Inc",
"domain": "techstart.io",
"industry": "Software",
"headcount": "51-200",
"linkedinUrl": "https://www.linkedin.com/company/techstart",
"websiteUrl": "https://techstart.io",
"city": "Austin",
"country": "United States"
}
]
}
{
"addedCount": 0
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid uuid"
}
}
{
"error": {
"code": "BAD_REQUEST",
"message": "At least one company ID is required"
}
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Cannot add companies to a person-type list. This list is of type 'person'."
}
}
{
"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"
}
}
Adds companies to an existing lead list. The companies are automatically copied from the global database to the tenant database before being added to the list. Duplicate company IDs are filtered out automatically.
Authentication
This endpoint requires authentication. The user must:- Be signed in with a valid organization
- Have access to the lead list (be in the
userIdsarray) OR be an admin user
This endpoint only works with lead lists of type
"company". Attempting to
add companies to a person-type list will result in a validation error.Request
Path Parameters
string (UUID)
required
The unique identifier of the lead list to add companies to.
Body Parameters
array
required
Array of company UUIDs to add to the lead list. Must contain at least one
valid UUID. Validation: - Each ID must be a valid UUID format - Array must
contain at least one company ID - Duplicate IDs within the request are allowed
(they will be deduplicated) - Companies already in the list are automatically
filtered out
Request Examples
{
"companyIds": ["550e8400-e29b-41d4-a716-446655440001"]
}
{
"companyIds": [
"550e8400-e29b-41d4-a716-446655440001",
"660e8400-e29b-41d4-a716-446655440002",
"770e8400-e29b-41d4-a716-446655440003"
]
}
Response
On success, returns the updated lead list with all companies populated.Lead List Fields
string (UUID)
required
Unique identifier for the lead list.
string (UUID) | null
required
The ID of the associated Ideal Customer Profile, or
null if not linked.string
required
The display name of the lead list.
string
required
The type of leads in this list. Will be
"company" for lists that accept
companies.string
required
ISO 8601 timestamp for the campaign start date.
string
required
ISO 8601 timestamp for the campaign end date.
array
required
Array of person/lead IDs. Will be empty for company-type lists.
array
required
Array of company UUIDs in the list, including the newly added companies.
array
required
Array of user IDs with access to this lead list.
string
required
ISO 8601 timestamp of when the lead list was created.
string
required
ISO 8601 timestamp of when the lead list was last updated.
array
Array of populated company objects. Only present for company-type lists.
Company Object Fields
When the list type is"company", each company object in the companies array contains the full company record:
string (UUID)
Unique identifier for the company.
string
The company name.
string | null
The company’s legal name.
string | null
Company description.
string | null
Short company summary.
string | null
The company’s primary domain.
string | null
The company’s industry classification.
string | null
Employee headcount range (e.g.,
"51-200", "1001-5000").string | null
Revenue range (e.g.,
"$10M-$50M").number | null
The year the company was founded.
string | null
Company headquarters city.
string | null
Company headquarters country.
string | null
Company headquarters postal code.
string | null
URL to the company’s LinkedIn page.
string | null
The company’s website URL.
string | null
URL to the company’s logo image.
array
Array of phone numbers for the company.
Response Examples
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"icpId": "660e8400-e29b-41d4-a716-446655440001",
"name": "Enterprise Accounts Q1",
"type": "company",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-03-31T23:59:59.000Z",
"personIds": [],
"companyIds": [
"770e8400-e29b-41d4-a716-446655440001",
"770e8400-e29b-41d4-a716-446655440002"
],
"userIds": ["user_xyz789"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-15T14:22:00.000Z",
"companies": [
{
"id": "770e8400-e29b-41d4-a716-446655440001",
"name": "Acme Corporation",
"domain": "acme.com",
"industry": "Technology",
"headcount": "201-500",
"linkedinUrl": "https://www.linkedin.com/company/acme",
"websiteUrl": "https://acme.com",
"city": "San Francisco",
"country": "United States"
},
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "TechStart Inc",
"domain": "techstart.io",
"industry": "Software",
"headcount": "51-200",
"linkedinUrl": "https://www.linkedin.com/company/techstart",
"websiteUrl": "https://techstart.io",
"city": "Austin",
"country": "United States"
}
]
}
{
"addedCount": 0
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid uuid"
}
}
{
"error": {
"code": "BAD_REQUEST",
"message": "At least one company ID is required"
}
}
{
"error": {
"code": "BAD_REQUEST",
"message": "Cannot add companies to a person-type list. This list is of type 'person'."
}
}
{
"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"
}
}
Behavior Notes
Duplicate Handling
- If any of the provided company IDs already exist in the lead list, they are automatically filtered out
- Only new companies are added to the list
- If all provided companies already exist, the endpoint returns
{ "addedCount": 0 }instead of the full list
Tenant Data Sync
Companies are automatically copied from the global database to the tenant database before being added to the list. This ensures data consistency across the multi-tenant architecture.Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 200 | - | Companies added successfully (or all already existed) |
| 400 | BAD_REQUEST | Request validation failed. Check message for details (invalid UUID format, empty array, or wrong list type). |
| 401 | UNAUTHORIZED | User is not authenticated or organization ID is missing. |
| 403 | FORBIDDEN | User does not have access to this lead list. |
| 404 | NOT_FOUND | The specified lead list does not exist. |
| 500 | INTERNAL_ERROR | An unexpected server error occurred. |