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

# Create Lead List

> Creates a new lead list for organizing prospecting leads

Creates a new lead list for organizing and managing sales prospecting leads. The authenticated user is automatically granted access to the newly created lead list.

## Authentication

This endpoint requires authentication. The user must be signed in to create lead lists.

<Note>
  The creating user is automatically added to the `userIds` array, granting them
  access to the lead list.
</Note>

## Request

<ParamField body="name" type="string" required>
  The display name for the lead list. Should be descriptive of the campaign or
  target audience.
</ParamField>

<ParamField body="type" type="string" default="person">
  The type of leads this list will contain. Must be one of: - `"person"` - For
  individual contact leads (default) - `"company"` - For company/organization
  leads
</ParamField>

<ParamField body="icpId" type="string (UUID) | null" required>
  The ID of the Ideal Customer Profile (ICP) to associate with this lead list.
  Pass `null` if not linking to an ICP.
</ParamField>

<ParamField body="startDate" type="string" required>
  ISO 8601 date string indicating when the lead list campaign starts.
</ParamField>

<ParamField body="endDate" type="string" required>
  ISO 8601 date string indicating when the lead list campaign ends.
</ParamField>

<ParamField body="personIds" type="array" required>
  Array of person/lead IDs to include in the list. Used when `type` is
  `"person"`.
</ParamField>

<ParamField body="companyIds" type="array">
  Array of company UUIDs to include in the list. Used when `type` is
  `"company"`. Defaults to an empty array.
</ParamField>

## Request Examples

<RequestExample>
  ```json Person Lead List theme={null}
  {
    "name": "Q1 2024 Tech Startups",
    "type": "person",
    "icpId": "660e8400-e29b-41d4-a716-446655440001",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-03-31T23:59:59.000Z",
    "personIds": ["lead_abc123", "lead_def456"],
    "companyIds": []
  }
  ```

  ```json Company Lead List theme={null}
  {
    "name": "Enterprise Accounts Q2",
    "type": "company",
    "icpId": null,
    "startDate": "2024-04-01T00:00:00.000Z",
    "endDate": "2024-06-30T23:59:59.000Z",
    "personIds": [],
    "companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
  }
  ```

  ```json Minimal Request theme={null}
  {
    "name": "New Campaign",
    "icpId": null,
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-12-31T23:59:59.000Z"
  }
  ```
</RequestExample>

## Response

Returns the created lead list object with server-generated fields.

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

<ResponseField name="icpId" type="string (UUID) | null" required>
  The ID of the associated Ideal Customer Profile.
</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 (`"person"` or `"company"`).
</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 in the list.
</ResponseField>

<ResponseField name="companyIds" type="array" required>
  Array of company UUIDs in the list.
</ResponseField>

<ResponseField name="userIds" type="array" required>
  Array of user IDs with access (includes the creator).
</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>

## Response Examples

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "icpId": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Q1 2024 Tech Startups",
    "type": "person",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-03-31T23:59:59.000Z",
    "personIds": ["lead_abc123", "lead_def456"],
    "companyIds": [],
    "userIds": ["user_xyz789"],
    "createdAt": "2024-01-02T10:30:00.000Z",
    "updatedAt": "2024-01-02T10:30:00.000Z"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Invalid request body",
      "details": [
        {
          "path": ["name"],
          "message": "Required"
        }
      ]
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Unauthorized"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code       | Description                                                                    |
| ----------- | ---------------- | ------------------------------------------------------------------------------ |
| 400         | `BAD_REQUEST`    | Request body validation failed. Check the `details` field for specific issues. |
| 401         | `UNAUTHORIZED`   | User is not authenticated. Ensure a valid session exists.                      |
| 500         | `INTERNAL_ERROR` | An unexpected server error occurred.                                           |