> ## 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 Prospects to Lead List

> Adds prospects (persons) to an existing lead list using either direct data or bulk selection

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

1. **Direct Data Mode**: Provide full prospect data objects directly
2. **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.

<Note>
  Only users listed in the lead list's `userIds` array (or admin users) can add
  prospects to the list.
</Note>

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

## Request

### Path Parameters

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

### Body Parameters

The request body accepts one of two formats:

#### Option 1: Direct Prospect Data

<ParamField body="prospects" type="array" required>
  Array of person objects to add to the lead list. Each person object contains the prospect's complete profile data.

  <Expandable title="Person object properties">
    <ParamField body="prospects[].id" type="string (UUID)">
      Unique identifier for the person.
    </ParamField>

    <ParamField body="prospects[].firstName" type="string" required>
      The prospect's first name.
    </ParamField>

    <ParamField body="prospects[].lastName" type="string" required>
      The prospect's last name.
    </ParamField>

    <ParamField body="prospects[].jobTitle" type="string | null">
      The prospect's current job title.
    </ParamField>

    <ParamField body="prospects[].city" type="string | null">
      The prospect's city location.
    </ParamField>

    <ParamField body="prospects[].country" type="string | null">
      The prospect's country location.
    </ParamField>

    <ParamField body="prospects[].linkedinUrl" type="string | null">
      URL to the prospect's LinkedIn profile.
    </ParamField>

    <ParamField body="prospects[].emails" type="array">
      Array of email addresses for the prospect.
    </ParamField>

    <ParamField body="prospects[].phones" type="array">
      Array of phone numbers for the prospect.
    </ParamField>

    <ParamField body="prospects[].companyId" type="string | null">
      ID of the prospect's current company.
    </ParamField>

    <ParamField body="prospects[].seniority" type="string | null">
      The prospect's seniority level (e.g., "senior", "manager", "director", "c\_suite").
    </ParamField>

    <ParamField body="prospects[].departments" type="array">
      Array of department names the prospect belongs to.
    </ParamField>

    <ParamField body="prospects[].functions" type="array">
      Array of job functions the prospect performs.
    </ParamField>
  </Expandable>
</ParamField>

#### Option 2: Bulk Selection

<ParamField body="selection" type="object" required>
  A bulk selection payload that describes which prospects to add based on a previous search.

  <Expandable title="Selection object properties">
    <ParamField body="selection.mode" type="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
    </ParamField>

    <ParamField body="selection.includedIds" type="array">
      Array of person IDs to explicitly include. Required for `manual` mode.
    </ParamField>

    <ParamField body="selection.excludedIds" type="array">
      Array of person IDs to exclude from the bulk selection range. Used with `bulk` mode.
    </ParamField>

    <ParamField body="selection.startIndex" type="integer">
      The starting index in the search results for bulk selection. Used with `bulk` mode.
    </ParamField>

    <ParamField body="selection.targetCount" type="integer">
      The number of prospects to select starting from `startIndex`. Maximum: 1000. Used with `bulk` mode.
    </ParamField>

    <ParamField body="selection.filters" type="object">
      The search filters used to reproduce the exact search results. Required for `bulk` mode.

      <Expandable title="Filter object structure">
        <ParamField body="selection.filters.account" type="object">
          Company/account filters including industry, location, employee size, revenue, etc.
        </ParamField>

        <ParamField body="selection.filters.contact" type="object">
          Contact/person filters including name, title, seniority, skills, etc.
        </ParamField>

        <ParamField body="selection.filters.page" type="integer">
          Page number for pagination (0-indexed).
        </ParamField>

        <ParamField body="selection.filters.size" type="integer">
          Number of results per page (max 100).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Request Examples

<RequestExample>
  ```json Direct Prospect Data theme={null}
  {
    "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"]
      }
    ]
  }
  ```

  ```json Manual Selection Mode theme={null}
  {
    "selection": {
      "mode": "manual",
      "includedIds": [
        "550e8400-e29b-41d4-a716-446655440001",
        "550e8400-e29b-41d4-a716-446655440002",
        "550e8400-e29b-41d4-a716-446655440003"
      ]
    }
  }
  ```

  ```json Bulk Selection Mode theme={null}
  {
    "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
      }
    }
  }
  ```
</RequestExample>

## Response

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

<ResponseField name="addedCount" type="integer" required>
  The number of prospects that were successfully added to the lead list. This
  excludes any prospects that were already in the list.
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "addedCount": 15
  }
  ```

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

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Invalid request body",
      "details": [
        {
          "path": ["prospects", 0, "firstName"],
          "message": "Required"
        }
      ]
    }
  }
  ```

  ```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: 550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

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

<AccordionGroup>
  <Accordion title="Duplicate Handling">
    Prospects that already exist in the lead list are automatically skipped. The `addedCount` in the response reflects only newly added prospects.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="List Type Validation">
    This endpoint only works with person-type lead lists (`type: "person"`). For
    company-type lists, use the `/add-companies` endpoint instead.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>