Create List

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 and Save Companies.

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

Put records into a list

• Save and file in one call - send list_ids with Save People or Save Companies. This is the usual path.
• File people you already saved - Add People to List 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 and Set Company Lists 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 or Remove Companies from List.

Read what is in a list

Search your own lists with the search endpoints:

• People Search with filters.lists.include: ["<list id>"]
• Company Search with filters.lists.include: ["<list id>"]

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 and List Lists 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:

{
  "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 answers a taken name the same way.

Jobs

Delete List 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 until it is done. One such job runs per workspace at a time; a second start answers 409 with payload.code: "bulk_action_running".

Body parameters

• namestringrequiredmin length: 1max length: 100

  Display name, trimmed. Unique per type within the workspace (case-insensitive).

• typeenumrequired

  What a list holds: people (saved people) or companies (saved companies). Fixed at creation.

  Allowed values: people companies

Responses

• 201 The new list.
• 400 Invalid body (VALIDATION_ERROR with payload.code).
• 401 Missing, unknown or inactive credentials (UNAUTHORIZED).
• 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.
• 429 Too many requests (RATE_LIMIT). Not sent today: this operation is not rate limited.
• 500 Unexpected server error.

For error handling see Errors. The list fields are described in List object.