# Companies

## Concepts

### Company Identifier

Companies are uniquely identified by your **system's company id**. Companies can optionally have a **domain**, but domain must be unique if it's included.

### Default Company Variables

These are the default variables for companies in Conversion. Use these keys when updating or retrieving these variables.

<table><thead><tr><th width="199.28515625">Key</th><th width="140.52734375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>company_name</code></td><td><code>STRING</code></td><td>Company Name</td></tr><tr><td><code>annual_revenue</code></td><td><code>NUMBER</code></td><td>Annual Revenue</td></tr><tr><td><code>number_of_employees</code></td><td><code>NUMBER</code></td><td>Number of Employees</td></tr><tr><td><code>industry</code></td><td><code>STRING</code></td><td>Industry</td></tr></tbody></table>

## Batch Upsert Companies

Create or update multiple companies in a single request. To update a company, include their id and any variables you want to update.

**Rate limits:** 10 / second, 200 companies per batch

**Method:** `POST`&#x20;

**Route:** `/v1/companies/batch`

**Request Body:**

```json
{
  "batch": [
    {
      "domain": "example.com",
      "id": "your_company_id_123",
      "syncToCrm": false,
      "createdAt": "2025-08-12T09:21:45Z",
      "variables": {
        "company_name": "Acme Corporation",
        "industry": "Technology",
        ...
      }
    },
    ...
  ]
}
```

**Field Descriptions:**

* `batch` (required): List of companies to create/update
  * `domain` (optional): Company domain
  * `id`  (required): Your system's company id
  * `syncToCrm` (optional): Defaults to `false`. Denotes if this contact should sync back to your CRM.
  * `createdAt` (optional): Defaults to now. When the company was created in your system.
    * Should be given in ISO 8601 format
  * `variables` (optional): Key-value pairs for custom company fields

**Response:**

Empty object response.

## Get Company by Id

Retrieve a company and it's variables using their id.

**Rate limits:** 10 / second

**Method:** `GET`&#x20;

**Route:** `/v1/companies/{id}`&#x20;

**Response:**

```json
{
  "domain": "example.com",
  "id": "your_company_id_123",
  "syncToCrm": false,
  "createdAt": "2025-08-12T09:21:45Z",
  "variables": {
    "company_name": "Acme Corporation",
    "industry": "Technology",
    ...
  }
}
```

## Delete Company by Id

Remove a company from Conversion using their id.

**Rate limits:** 10 / second

**Method:** `DELETE`&#x20;

**Route:** `/v1/companies/{id}`

**Response:**

Empty object response.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.conversion.ai/companies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.