# Block Companies

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

Adds up to 1,000 company domains to the block list and answers every item in `added`, `already_blocked` or `invalid`. A domain or website URL is cleaned to its bare host. 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 domains to block, 1 to 1,000.
  - `domain` (string, required, max length: 200): A domain or a website URL, cleaned to its bare host (`https://www.Acme.com/x` -> `acme.com`). A value that is not a domain goes to `invalid` (`invalid_format`). Example: `"acme.com"`
  - `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/companies/add \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "data": [
    {
      "domain": "https://www.Acme.com/about",
      "identifier": "a"
    },
    {
      "domain": "acme.com",
      "identifier": "b"
    },
    {
      "domain": "initech.com",
      "identifier": "c"
    },
    {
      "domain": "not a domain",
      "identifier": "d"
    }
  ]
}
'
```

## Response 200

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

```json
{
  "success": true,
  "data": {
    "added": [
      {
        "identifiers": [
          "a",
          "b"
        ],
        "blocked_company": {
          "id": "6705a1c2e4b0f1a2b3c4d5e7",
          "domain": "acme.com",
          "created_at": "2026-10-08T09:30:00.000Z"
        }
      }
    ],
    "already_blocked": [
      {
        "identifiers": [
          "c"
        ],
        "blocked_company": {
          "id": "64f0c3d2a1b2c3d4e5f60719",
          "domain": "initech.com",
          "created_at": "2023-09-01T12:00:00.000Z"
        }
      }
    ],
    "invalid": [
      {
        "identifier": "d",
        "code": "invalid_format",
        "field": "domain",
        "reason": "not a domain"
      }
    ]
  },
  "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": [
            {
              "domain": "acme.com"
            },
            {
              "domain": "initech.com"
            },
            {
              "domain": "globex.com"
            }
          ]
        },
        "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 100,000 companies (`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 100000 companies; it holds 99990 and this request adds 25",
      "payload": {
        "limit": 100000,
        "current_count": 99990,
        "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.