---
title: "Block a company"
method: POST
path: "/companies/{id}/block"
tags: ["Companies"]
---

# Block a company

`POST /companies/{id}/block`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/companies/{id}/block`
- Auth: HTTP bearer

Puts a company on the board-scoped blocklist. Blocking always stops company-vertical backfill and rejects automated sourcing writes that match this company. Two outcomes are available. The default (`remove` omitted or false) keeps the public profile, archives currently published jobs, and still allows non-automated human posts. With `remove: true` the profile, its jobs, and its directory, sitemap, and search entries are removed from the board while the company stays on the blocklist, and every write that resolves to it is rejected (ADR-0124). Idempotent: blocking an already-blocked company succeeds and reports `was_already_blocked: true`, and `remove: true` upgrades an already-blocked company to the removed outcome. The response reports `removed` (the resulting state) and `removal_scheduled` (whether this call started the removal).

## Path parameters

- `id` string, required: The company's opaque object `id`: the `id` field returned by the company endpoints (e.g. `p17xq4c2b9r5gz3e8j0r6t4k7m2n9d5w`). This is NOT the `slug` or display name; passing a slug like `antler` returns 404. To look up a company by name or slug, use `GET /v1/companies`, `POST /v1/companies/search`, or `POST /v1/companies/find-or-create` and read the returned `id`.

## Request body

- BlockCompanyBody
  - `reason` string: Optional free-text reason recorded on the blocklist audit.
  - `remove` boolean: When true, also removes the company profile and its jobs from the board while keeping it on the blocklist (ADR-0124); default false keeps the profile and archives published jobs.

## Response `200`

Successful response.

- BlockCompanyResult
  - `id` string, required: The blocked company id.
  - `blocked` true, required
  - `jobs_archived_scheduled` boolean, required: Whether a published-job archive pass was scheduled.
  - `was_already_blocked` boolean, required: True when the company was already on the blocklist.
  - `removed` boolean, required: True when the company is removed from the board as well as blocked.
  - `removal_scheduled` boolean, required: Whether this call scheduled the removal of the profile and its jobs.

## Other responses

- `404`: Company not found.

## Changes

- **2026-10-19** `c34152c38176`: 1 info
  - added the optional property `error/upgrade` to the response with the `404` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/companies/:id/block/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)