# Save People

`POST https://api.getprospect.com/v2/people/save`

Saves up to 500 people into 1-20 of your v2 lists, by GetProspect id or by LinkedIn profile URL (at most 50 URL items). Credits: 1 email credit per person whose stored valid email your workspace does not own yet; when the balance runs out the rest are saved without email, and that email stays billable on a later save, enrich or search. A person already paid for is free to save again. Uses 1 unit of the enrich rate limit per `linkedin_url` item (none for one your workspace already owns); id items use none. Every item comes back in one of `saved`, `not_matched`, `invalid` or `failed`, echoing its `identifier`.

## Authentication

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

## Body parameters

- `data` (one of[], required): People to save (1-500): person id strings or items with exactly one of `id` / `linkedin_url` (at most 50 `linkedin_url` items).
- `list_ids` (string[], required): v2 list ids to attach every saved person to (1-20). Example: `{"list_ids":["64f1a2b3c4d5e6f7a8b9c0f1"]}`

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/people/save \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": [
    "64f1a2b3c4d5e6f7a8b9c0d1",
    {
      "identifier": "row-2",
      "linkedin_url": "https://linkedin.com/in/profile-that-does-not-exist-x1"
    }
  ],
  "list_ids": [
    "64f1a2b3c4d5e6f7a8b9c0f1"
  ]
}
'
```

## Response 200

Every item in one of the four buckets; `metadata.credits` is the balance after the save.

```json
{
  "success": true,
  "data": {
    "saved": [
      {
        "identifier": "64f1a2b3c4d5e6f7a8b9c0d1",
        "id": "64f1a2b3c4d5e6f7a8b9c0d1",
        "matched_by": "id",
        "list_ids": [
          "64f1a2b3c4d5e6f7a8b9c0f1"
        ],
        "saved_at": "2026-10-08T09:30:00.000Z",
        "email": {
          "status": "valid",
          "address": "emily.carter.sample@intercom.com",
          "revealed": true
        }
      }
    ],
    "not_matched": [
      {
        "identifier": "row-2",
        "attempted": [
          "linkedin_url"
        ]
      }
    ],
    "invalid": [],
    "failed": []
  },
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z",
    "credits": {
      "email_search": 499,
      "email_verification": 100,
      "reset_at": "2026-11-01T00:00:00.000Z"
    },
    "total": 2,
    "saved_count": 1,
    "not_matched_count": 1,
    "invalid_count": 0,
    "failed_count": 0
  }
}
```

## Response 400

Invalid request (`VALIDATION_ERROR`; `payload.code` says which kind of mistake), or `list_ids` naming a list that is not a v2 list of your workspace.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "linkedin_url and id exclude each other: send exactly one of them",
      "payload": {
        "field": "data.0.linkedin_url",
        "code": "conflicting_fields",
        "received_value": "https://linkedin.com/in/emily-carter-sample",
        "received_type": "string"
      }
    }
  ]
}
```

## Response 401

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

## Response 402

Your email credit balance is zero (`PAYMENT_REQUIRED`).

## Response 429

Over the `enrich` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced.

## Response 500

Unexpected server error.