Add People to List

POST/v2/people/lists/add

Adds people the workspace has already saved to one people list. Never saves, reveals or charges: a person the workspace has not saved comes back not_saved (save them with POST /v2/people/save). Safe to repeat: a person already in the list comes back already_in_list and nothing changes. Every requested id comes back once in items, in request order. Free: costs no credits.

Body parameters

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

Responses

200 What happened to each id.
400 Invalid body (VALIDATION_ERROR with payload.code), or list_id is not a live people list of this workspace (invalid_value).
401 Missing, unknown or inactive credentials (UNAUTHORIZED).
429 Too many requests (RATE_LIMIT). Not sent today: this operation is not rate limited.
500 Unexpected server error.

For error handling see Errors. Response objects are described in Person object and Company object.

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

Response

{
  "success": true,
  "data": {
    "added": 1,
    "items": [
      {
        "id": "65a1b2c3d4e5f6a7b8c9d0e1",
        "status": "added"
      },
      {
        "id": "65a1b2c3d4e5f6a7b8c9d0e2",
        "status": "already_in_list"
      },
      {
        "id": "65a1b2c3d4e5f6a7b8c9d0e3",
        "status": "not_saved"
      }
    ]
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}