# Remove People from List

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

Takes people out of one people list. They stay saved, and stay in their other lists. `removed` counts the people who were in the list. Safe to repeat. Free: costs no credits.

## Authentication

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

## Body parameters

- `list_id` (string, required): The people list: an `id` from `GET /v2/lists?type=people`.
- `ids` (string[], required): Person ids (24 hex characters, as `POST /v2/people/search` answers them), 1-500.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/people/lists/remove \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "list_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "ids": [
    "65a1b2c3d4e5f6a7b8c9d0e1",
    "65a1b2c3d4e5f6a7b8c9d0e2"
  ]
}
'
```

## Response 200

How many people left the list.

```json
{
  "success": true,
  "data": {
    "removed": 2
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}
```

## Response 400

Invalid body (`VALIDATION_ERROR` with `payload.code`), or `list_id` is not a live people list of this workspace (`invalid_value`). Also when no id in `ids` is a well-formed person id (`invalid_format`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "66f1a2b3c4d5e6f7a8b9c0e7 is not a people list of this workspace.",
      "payload": {
        "code": "invalid_value",
        "field": "list_id"
      }
    }
  ]
}
```

## Response 401

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

## Response 429

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

## Response 500

Unexpected server error.