# Block People

`POST https://api.getprospect.com/v2/blocklist/people/add`

Adds up to 1,000 people to the block list by first and last name, optionally with a LinkedIn profile, and answers every item in `added`, `already_blocked` or `invalid`. A name entry blocks every person with that first and last name in this workspace; the name match ignores case and punctuation. A repeat lands in `already_blocked`. Safe to retry: a repeat never writes a second entry. Free, no credits; spends no rate-limit units, but counts against the per-second window of the `search` bucket. Blocked people and companies are left out of people and company search, people and company enrich, email find and suggestions in this workspace, within 15 seconds. Saving a person by id and email verify are not filtered by workspace block lists, and blocked domains that resolve to more than 10,000 companies are only partly excluded from people search. Any member or API key of the workspace may call it; a credential that belongs to no workspace answers 403.

## Authentication

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

## Body parameters

- `data` (object[], required): The people to block, 1 to 1,000.
  - `first_name` (string, required, max length: 200): First name. Empty, or only spaces, hyphens and apostrophes, puts the item in `invalid` (`missing_field`). Example: `"John"`
  - `last_name` (string, required, max length: 200): Last name. Empty, or only spaces, hyphens and apostrophes, puts the item in `invalid` (`missing_field`). Example: `"Smith"`
  - `linkedin_url` (string, optional, max length: 200): Also block this LinkedIn profile (`https://linkedin.com/in/<profile>`). Not a profile URL: the item goes to `invalid` (`invalid_format`). Example: `"https://linkedin.com/in/john-smith"`
  - `identifier` (string, optional, max length: 200): Your key for this item, echoed in the answer. Defaults to the item index.

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/blocklist/people/add \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "identifier": "crm-1"
    },
    {
      "first_name": "john",
      "last_name": "SMITH",
      "linkedin_url": "https://www.linkedin.com/in/john-smith-42",
      "identifier": "crm-2"
    },
    {
      "first_name": "Mary",
      "last_name": "Jones",
      "identifier": "crm-3"
    },
    {
      "first_name": "Ann",
      "last_name": "Lee",
      "linkedin_url": "https://example.com/ann",
      "identifier": "crm-4"
    }
  ]
}
'
```

## Response 200

Every item, in one of the three buckets; the item counts in `metadata`.

```json
{
  "success": true,
  "data": {
    "added": [
      {
        "identifiers": [
          "crm-1",
          "crm-2"
        ],
        "blocked_person": {
          "id": "6705a1c2e4b0f1a2b3c4d5e6",
          "first_name": "John",
          "last_name": "Smith",
          "linkedin_url": "https://linkedin.com/in/john-smith-42",
          "company_domain": null,
          "created_at": "2026-10-08T09:30:00.000Z"
        }
      }
    ],
    "already_blocked": [
      {
        "identifiers": [
          "crm-3"
        ],
        "blocked_person": {
          "id": "64f0c3d2a1b2c3d4e5f60718",
          "first_name": "Mary",
          "last_name": "Jones",
          "linkedin_url": null,
          "company_domain": "acme.com",
          "created_at": "2023-09-01T12:00:00.000Z"
        }
      }
    ],
    "invalid": [
      {
        "identifier": "crm-4",
        "code": "invalid_format",
        "field": "linkedin_url",
        "reason": "Not a LinkedIn profile URL (https://linkedin.com/in/<profile>)"
      }
    ]
  },
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z",
    "total": 4,
    "added_count": 2,
    "already_blocked_count": 1,
    "invalid_count": 1
  }
}
```

## Response 400

Invalid body (`VALIDATION_ERROR`): `missing_field` (`data`), `out_of_range` (no items, more than 1,000, or a string over 200 characters), `wrong_type`, `unknown_field` (with `allowed_fields`), or `conflicting_fields` (one `identifier` on two different items, listed in `payload.conflicts`). An item that is only unusable lands in `invalid` instead.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "data must contain no more than 1000 elements",
      "payload": {
        "field": "data",
        "code": "out_of_range",
        "received_value": {
          "_omitted": true,
          "type": "array",
          "length": 1001,
          "sample": [
            {
              "first_name": "Ann",
              "last_name": "Lee"
            },
            {
              "first_name": "Bob",
              "last_name": "Ray"
            },
            {
              "first_name": "Cy",
              "last_name": "Fox"
            }
          ]
        },
        "received_type": "object",
        "constraints": {
          "arrayMaxSize": "data must contain no more than 1000 elements"
        }
      }
    }
  ]
}
```

## Response 401

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

## Response 403

The credential belongs to no workspace (`FORBIDDEN`, `workspace_required`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z"
  },
  "errors": [
    {
      "name": "FORBIDDEN",
      "message": "This operation works inside a workspace, and the credential used belongs to none",
      "payload": {
        "code": "workspace_required"
      }
    }
  ]
}
```

## Response 409

The add would take the list past its cap of 200,000 people (`CONFLICT`, `limit_reached`, with `payload.limit` and `payload.current_count`). Nothing was written.

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T09:30:00.000Z"
  },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "A workspace block list holds at most 200000 people; it holds 199990 and this request adds 25",
      "payload": {
        "limit": 200000,
        "current_count": 199990,
        "code": "limit_reached"
      }
    }
  ]
}
```

## Response 429

Over the per-second window of the `search` bucket (`RATE_LIMIT`). Sent only where rate-limit enforcement is on; wait `Retry-After` seconds.

## Response 500

Unexpected server error; also, rarely, a concurrent change of the same entries. Safe to retry.