> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies

> The organization a contact belongs to, identified by domain.

A company represents the organization one or more contacts belong to. RevyOps automatically associates contacts with companies based on their email domain, or from explicit company data in a webhook payload.

For how companies are searched, filtered, and viewed in the RevyOps UI, see the [Companies](/user-guide/companies) user guide.

## Configuration

|          |                                                                  |
| -------- | ---------------------------------------------------------------- |
| API path | `/public/v2/companies` (recommended) or `/public/companies` (v1) |
| Singular | company                                                          |
| Plural   | companies                                                        |

<Note>
  v2 adds `lookup-by-custom-field` and a global-update endpoint for the master list. See [Versioning](/api-reference/introduction#versioning).
</Note>

## Attributes

| Attribute         | API field               | Type                                                   | Writable?          | Notes                                                                                                                                                                                  |
| ----------------- | ----------------------- | ------------------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID                | `id`                    | integer                                                | Read-only          |                                                                                                                                                                                        |
| Last updated      | `updated_time`          | string (date-time)                                     | Read-only          |                                                                                                                                                                                        |
| Domain            | `domain`                | string                                                 | Writable, required | Primary identifier. RevyOps uses it to auto-associate contacts with this company.                                                                                                      |
| Name              | `name`                  | string                                                 | Writable           |                                                                                                                                                                                        |
| Status            | `company_status`        | string                                                 | Writable           | Reflects the state of the account: `active`, `replied`, `interested`, `not-interested`, or `customer`. See [Archiving and Deleting](/data-model/archiving-and-deleting#status-values). |
| Previous status   | `previous_status`       | string, nullable                                       | Read-only          | The status before the most recent change.                                                                                                                                              |
| Status changed at | `status_changed_at`     | string (date-time), nullable                           | Read-only          | When `company_status` last changed.                                                                                                                                                    |
| Custom fields     | `company_custom_fields` | array of `{id, updated_time, field_name, field_value}` | Writable           | See [Custom Fields](/user-guide/custom-fields). `field_value` is capped at 2500 characters.                                                                                            |

## Relationships

* **Contacts**: one-to-many. Every [Contact](/data-model/contacts) whose `company_id` points at this company. A contact belongs to at most one company.
* **Opportunities**: one-to-many. Deals synced from Close CRM or HubSpot against this company. See [Opportunities](/user-guide/opportunities).

## Filtering by Contacts

Companies can be filtered not just by their own fields, but by properties of the contacts at that company: for example, every company with at least one contact in a given status, or excluding companies whose only contacts are marked [Do Not Contact](/data-model/archiving-and-deleting#do-not-contact). This lets you narrow the company list to accounts where the right kind of contact actually exists. See [Companies](/user-guide/companies#filtering-by-contacts) and the `query_entity` MCP tool's relation filters for how to express this.

## Related Endpoints and MCP Tools

| Method | Endpoint                                                  | Description                                         |
| ------ | --------------------------------------------------------- | --------------------------------------------------- |
| GET    | `/public/v2/companies`                                    | List and filter companies                           |
| POST   | `/public/v2/companies`                                    | Create a company                                    |
| GET    | `/public/v2/companies/{company_id}`                       | Get one company                                     |
| PATCH  | `/public/v2/companies/{company_id}`                       | Update a company                                    |
| DELETE | `/public/companies/{company_id}`                          | Permanently delete a company                        |
| GET    | `/public/v2/companies/lookup-by-custom-field`             | Find companies by a custom field's value            |
| POST   | `/public/companies/{company_id}/custom-fields`            | Add a custom field value                            |
| PATCH  | `/public/companies/{company_id}/custom-fields/{field_id}` | Update a custom field value                         |
| DELETE | `/public/companies/{company_id}/custom-fields/{field_id}` | Remove a custom field value                         |
| GET    | `/public/v2/companies-master-list`                        | List companies across every client (master API key) |

**MCP tools:** `search_companies`, `get_company`, `update_company` (see [MCP Tools](/mcp/tools#company-tools)). For filtering beyond an exact domain or name match, use `query_entity` with `entity: "company"`.