> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lance.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Companies to Lead List

> Adds one or more companies to an existing company-type lead list

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

<Note>
  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.
</Note>

## Request

### Path Parameters

<ParamField path="id" type="string (UUID)" required>
  The unique identifier of the lead list to add companies to.
</ParamField>

### Body Parameters

<ParamField body="companyIds" type="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
</ParamField>

## Request Examples

<RequestExample>
  ```json Single Company theme={null}
  {
    "companyIds": ["550e8400-e29b-41d4-a716-446655440001"]
  }
  ```

  ```json Multiple Companies theme={null}
  {
    "companyIds": [
      "550e8400-e29b-41d4-a716-446655440001",
      "660e8400-e29b-41d4-a716-446655440002",
      "770e8400-e29b-41d4-a716-446655440003"
    ]
  }
  ```
</RequestExample>

## Response

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

### Lead List Fields

<ResponseField name="id" type="string (UUID)" required>
  Unique identifier for the lead list.
</ResponseField>

<ResponseField name="icpId" type="string (UUID) | null" required>
  The ID of the associated Ideal Customer Profile, or `null` if not linked.
</ResponseField>

<ResponseField name="name" type="string" required>
  The display name of the lead list.
</ResponseField>

<ResponseField name="type" type="string" required>
  The type of leads in this list. Will be `"company"` for lists that accept
  companies.
</ResponseField>

<ResponseField name="startDate" type="string" required>
  ISO 8601 timestamp for the campaign start date.
</ResponseField>

<ResponseField name="endDate" type="string" required>
  ISO 8601 timestamp for the campaign end date.
</ResponseField>

<ResponseField name="personIds" type="array" required>
  Array of person/lead IDs. Will be empty for company-type lists.
</ResponseField>

<ResponseField name="companyIds" type="array" required>
  Array of company UUIDs in the list, including the newly added companies.
</ResponseField>

<ResponseField name="userIds" type="array" required>
  Array of user IDs with access to this lead list.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp of when the lead list was created.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  ISO 8601 timestamp of when the lead list was last updated.
</ResponseField>

<ResponseField name="companies" type="array">
  Array of populated company objects. Only present for company-type lists.
</ResponseField>

### Company Object Fields

When the list type is `"company"`, each company object in the `companies` array contains the full company record:

<ResponseField name="companies[].id" type="string (UUID)">
  Unique identifier for the company.
</ResponseField>

<ResponseField name="companies[].name" type="string">
  The company name.
</ResponseField>

<ResponseField name="companies[].legalName" type="string | null">
  The company's legal name.
</ResponseField>

<ResponseField name="companies[].description" type="string | null">
  Company description.
</ResponseField>

<ResponseField name="companies[].summary" type="string | null">
  Short company summary.
</ResponseField>

<ResponseField name="companies[].domain" type="string | null">
  The company's primary domain.
</ResponseField>

<ResponseField name="companies[].industry" type="string | null">
  The company's industry classification.
</ResponseField>

<ResponseField name="companies[].headcount" type="string | null">
  Employee headcount range (e.g., `"51-200"`, `"1001-5000"`).
</ResponseField>

<ResponseField name="companies[].revenue" type="string | null">
  Revenue range (e.g., `"$10M-$50M"`).
</ResponseField>

<ResponseField name="companies[].foundedYear" type="number | null">
  The year the company was founded.
</ResponseField>

<ResponseField name="companies[].city" type="string | null">
  Company headquarters city.
</ResponseField>

<ResponseField name="companies[].country" type="string | null">
  Company headquarters country.
</ResponseField>

<ResponseField name="companies[].postalCode" type="string | null">
  Company headquarters postal code.
</ResponseField>

<ResponseField name="companies[].linkedinUrl" type="string | null">
  URL to the company's LinkedIn page.
</ResponseField>

<ResponseField name="companies[].websiteUrl" type="string | null">
  The company's website URL.
</ResponseField>

<ResponseField name="companies[].logoUrl" type="string | null">
  URL to the company's logo image.
</ResponseField>

<ResponseField name="companies[].phones" type="array">
  Array of phone numbers for the company.
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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"
      }
    ]
  }
  ```

  ```json 200 All Companies Already Exist theme={null}
  {
    "addedCount": 0
  }
  ```

  ```json 400 Invalid Company ID Format theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Invalid uuid"
    }
  }
  ```

  ```json 400 Empty Array theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "At least one company ID is required"
    }
  }
  ```

  ```json 400 Wrong List Type theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Cannot add companies to a person-type list. This list is of type 'person'."
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Organization ID required"
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "message": "You do not have access to this lead list"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "LeadList not found"
    }
  }
  ```
</ResponseExample>

## 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.                                                                         |