Skip to main content
POST
/
api
/
v1
/
entities
/
leadlists
/
{id}
/
add-companies
{
  "companyIds": ["550e8400-e29b-41d4-a716-446655440001"]
}

{
  "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"
    }
  ]
}
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 userIds array) 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

​
id
string (UUID)
required
The unique identifier of the lead list to add companies to.

​
Body Parameters

​
companyIds
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"]
}

​
Response

On success, returns the updated lead list with all companies populated.

​
Lead List Fields

​
id
string (UUID)
required
Unique identifier for the lead list.
​
icpId
string (UUID) | null
required
The ID of the associated Ideal Customer Profile, or null if not linked.
​
name
string
required
The display name of the lead list.
​
type
string
required
The type of leads in this list. Will be "company" for lists that accept companies.
​
startDate
string
required
ISO 8601 timestamp for the campaign start date.
​
endDate
string
required
ISO 8601 timestamp for the campaign end date.
​
personIds
array
required
Array of person/lead IDs. Will be empty for company-type lists.
​
companyIds
array
required
Array of company UUIDs in the list, including the newly added companies.
​
userIds
array
required
Array of user IDs with access to this lead list.
​
createdAt
string
required
ISO 8601 timestamp of when the lead list was created.
​
updatedAt
string
required
ISO 8601 timestamp of when the lead list was last updated.
​
companies
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:
​
companies[].id
string (UUID)
Unique identifier for the company.
​
companies[].name
string
The company name.
​
companies[].legalName
string | null
The company’s legal name.
​
companies[].description
string | null
Company description.
​
companies[].summary
string | null
Short company summary.
​
companies[].domain
string | null
The company’s primary domain.
​
companies[].industry
string | null
The company’s industry classification.
​
companies[].headcount
string | null
Employee headcount range (e.g., "51-200", "1001-5000").
​
companies[].revenue
string | null
Revenue range (e.g., "$10M-$50M").
​
companies[].foundedYear
number | null
The year the company was founded.
​
companies[].city
string | null
Company headquarters city.
​
companies[].country
string | null
Company headquarters country.
​
companies[].postalCode
string | null
Company headquarters postal code.
​
companies[].linkedinUrl
string | null
URL to the company’s LinkedIn page.
​
companies[].websiteUrl
string | null
The company’s website URL.
​
companies[].logoUrl
string | null
URL to the company’s logo image.
​
companies[].phones
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"
    }
  ]
}

​
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 CodeError CodeDescription
200-Companies added successfully (or all already existed)
400BAD_REQUESTRequest validation failed. Check message for details (invalid UUID format, empty array, or wrong list type).
401UNAUTHORIZEDUser is not authenticated or organization ID is missing.
403FORBIDDENUser does not have access to this lead list.
404NOT_FOUNDThe specified lead list does not exist.
500INTERNAL_ERRORAn unexpected server error occurred.