---
title: "Create a list"
method: POST
path: "/v2/lists"
tags: ["Lists"]
---

# Create a list

`POST /v2/lists`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/lists`
- Auth: HTTP bearer

Create a new list to organize people or companies. Use this to start building collections for outreach, tracking, or organization. Provide: title (required), type (people or company), and optional description. The creator becomes the list owner. List creation may be limited based on your subscription plan.

## Request body

- CreateListRequest: Request body for creating a new list
  - `title` string, required: List title
  - `type` 'people' | 'company': Type of entities in the list
  - `description` string: Optional list description
  - `is_public` boolean: Whether the list is publicly accessible

## Response `200`

List created successfully

- object
  - `data` CreateListResponse, required: Response after creating a new list
    - `id` number, required: Unique list identifier
    - `title` string, required: List title
    - `type` 'people' | 'company', required: Type of entities in the list
    - `description` string, nullable, required: List description
    - `item_count` number, required: Number of items in the list
    - `notifications_enabled` boolean, required: Whether the list is opted into the daily "new search results" email sweep
    - `is_public` boolean, required: Whether anyone holding the public identifier can read this list.
    - `public_id` string, nullable, required: Public identifier, minted the first time the list is published. Null until then.
    - `results_diff_since_last_run` number, nullable, required: New items appended by the most recent completed fill run (creation fill, manual refresh, or nightly re-run). Null until a run records one.
    - `created_at` string, required: ISO 8601 creation timestamp
    - `updated_at` string, required: ISO 8601 last update timestamp
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `422`: Plan limit reached

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)