# Create List

`POST https://api.getprospect.com/v2/lists`

Creates an empty people or company list and answers it with 201. The name is trimmed and must be free for that type within the workspace (case-insensitive): a taken name answers 409 `already_exists` with the `existing_id` of the list holding it. Add records with `POST /v2/people/save` or `POST /v2/companies/save` (`list_ids`), or file already saved people with `POST /v2/people/lists/add`. Free: costs no credits.

> **How are credits spent?**
>
> Lists are free. Creating, reading, renaming and deleting a list, and moving
> records in or out of one, consume no credits. Only saving a record spends
> credits: [Save People](https://getprospect.com/api-docs/people-save.md) and
> [Save Companies](https://getprospect.com/api-docs/company-save.md).

## How lists work

A list is a named folder of your workspace's **saved** records. A list holds
either people or companies, set by `type` when the list is created; the type
never changes. Names are unique per type within the workspace and compared
case-insensitively, so a people list and a company list may share a name.
Every member of the workspace can read, rename and delete every list. See the
[List object](https://getprospect.com/api-docs/list-object.md) for the fields.

A record can be in any number of lists. Taking it out of a list never unsaves
it, and deleting a list never deletes its records unless you ask for that
(`with_records=true` on [Delete List](https://getprospect.com/api-docs/lists-delete.md)).

## Put records into a list

- **Save and file in one call** - send `list_ids` with
  [Save People](https://getprospect.com/api-docs/people-save.md) or
  [Save Companies](https://getprospect.com/api-docs/company-save.md). This is the usual path.
- **File people you already saved** -
  [Add People to List](https://getprospect.com/api-docs/people-lists-add.md) takes up to 500 saved
  person ids. It never saves anyone and never spends credits: an id your
  workspace has not saved comes back as `not_saved`.
- **Set the lists of many records at once** -
  [Set People Lists](https://getprospect.com/api-docs/people-lists-set.md) and
  [Set Company Lists](https://getprospect.com/api-docs/companies-lists-set.md) take a selection (ids, or
  a whole search of up to 25,000 records) and leave it in exactly the
  `list_ids` you send.

Take records out with
[Remove People from List](https://getprospect.com/api-docs/people-lists-remove.md) or
[Remove Companies from List](https://getprospect.com/api-docs/companies-lists-remove.md).

## Read what is in a list

Search your own lists with the search endpoints:

- [People Search](https://getprospect.com/api-docs/people-search.md) with
  `filters.lists.include: ["<list id>"]`
- [Company Search](https://getprospect.com/api-docs/company-search.md) with
  `filters.lists.include: ["<list id>"]`

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/people/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "filters": {
    "lists": {
      "include": ["66f1a2b3c4d5e6f7a8b9c0d1"]
    }
  },
  "per_page": 100
}
'
```

`exclude` hides the members of lists instead, and `saved` scopes a search to
the records your workspace saved (`any`), did not save (`none`) or saved
without filing into any list (`without_list`). A search scoped to your saved
records spends no `search` rate-limit units.
[Get List](https://getprospect.com/api-docs/lists-get.md) and [List Lists](https://getprospect.com/api-docs/lists-list.md) report
each list's `records_count`.

## A taken name

When the workspace already has a list of this type with this name, the answer
is `409` with `payload.code: "already_exists"` and `payload.existing_id`, the id
of that list:

```json
{
  "success": false,
  "data": null,
  "metadata": { "timestamp": "2026-10-17T12:00:00.000Z" },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "A people list named \"Q4 SaaS founders\" already exists",
      "payload": {
        "code": "already_exists",
        "existing_id": "66f1a2b3c4d5e6f7a8b9c0e7"
      }
    }
  ]
}
```

To get a list by name whether or not it exists yet, create it and use
`existing_id` on a `409`. The same answer makes a create safe to retry after
a lost response. [Rename List](https://getprospect.com/api-docs/lists-update.md) answers a taken name
the same way.

## Jobs

[Delete List](https://getprospect.com/api-docs/lists-delete.md) and the two Set Lists operations can
take longer than a request. They answer a job: `200` with `status: "done"`
when the work finished inline, or `202` with `status: "running"` and a
`Location: /v2/jobs/{id}` header. Poll [Get Job](https://getprospect.com/api-docs/jobs-get.md) until it
is done. One such job runs per workspace at a time; a second start answers
`409` with `payload.code: "bulk_action_running"`.


## Authentication

Pass your API key in the `x-api-key` header.

## Body parameters

- `name` (string, required, min length: 1, max length: 100): Display name, trimmed. Unique per type within the workspace (case-insensitive).
- `type` (enum, required): What a list holds: `people` (saved people) or `companies` (saved companies). Fixed at creation. Allowed values: `people`, `companies`.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/lists \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "name": "Q4 SaaS founders",
  "type": "people"
}
'
```

## Response 201

The new list.

```json
{
  "success": true,
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Q4 SaaS founders",
    "type": "people",
    "records_count": 0,
    "last_added_record_at": null,
    "created_at": "2026-09-28T09:12:44.000Z",
    "updated_at": "2026-09-28T09:12:44.000Z",
    "owner": {
      "id": "64f0c1d2e3f4a5b6c7d8e9f0",
      "first_name": "Dana",
      "last_name": "Reyes",
      "photo_url": null
    }
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}
```

## Response 400

Invalid body (`VALIDATION_ERROR` with `payload.code`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "type: \"contacts\" is not an accepted value. Accepted: people, companies",
      "payload": {
        "field": "type",
        "code": "value_not_allowed",
        "received_value": "contacts",
        "received_type": "string",
        "invalid_values": [
          "contacts"
        ],
        "allowed_values": [
          "people",
          "companies"
        ],
        "constraints": {
          "isIn": "type must be one of the following values: people, companies"
        }
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 409

The name is taken: the workspace already has a live list of this type with this name, case-insensitive (`CONFLICT`, `payload.code: already_exists` with the `existing_id` of that list). A create retried after a lost response can treat `existing_id` as the list it made.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "A people list named \"Q4 SaaS founders\" already exists",
      "payload": {
        "code": "already_exists",
        "existing_id": "66f1a2b3c4d5e6f7a8b9c0e7"
      }
    }
  ]
}
```

## Response 429

Too many requests (`RATE_LIMIT`). Not sent today: this operation is not rate limited.

## Response 500

Unexpected server error.