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

# Companies

> Manage companies and the contacts that belong to them

Companies represent organizations in your CRM — typically the employers, customers, or accounts that your contacts belong to. Each company is owned by a specific agent (`bot_id`) and inherits the workspace from your API key.

## The Company object

<ResponseField name="id" type="string">
  Unique company identifier.
</ResponseField>

<ResponseField name="workspace_id" type="string" />

<ResponseField name="bot_id" type="string">
  The agent that owns this company.
</ResponseField>

<ResponseField name="name" type="string">
  Company name.
</ResponseField>

<ResponseField name="domain" type="string | null">
  Primary domain (e.g. `acme.com`).
</ResponseField>

<ResponseField name="website" type="string | null" />

<ResponseField name="industry" type="string | null" />

<ResponseField name="company_size" type="string | null">
  Free-form size band (e.g. `"50-200"`).
</ResponseField>

<ResponseField name="company_type" type="string | null" />

<ResponseField name="employee_count" type="number | null" />

<ResponseField name="annual_revenue" type="number | null" />

<ResponseField name="description" type="string | null" />

<ResponseField name="emails" type="array">
  Array of `{ email, is_primary }` objects.
</ResponseField>

<ResponseField name="phone_numbers" type="array">
  Array of `{ phone_number, is_primary }` objects.
</ResponseField>

<ResponseField name="tags" type="string[]" />

<ResponseField name="total_deal_value" type="number | null">
  Sum of `deal_value` across all contacts linked to this company.
</ResponseField>

<ResponseField name="pipeline_stage_id" type="string | null" />

<ResponseField name="address_line1" type="string | null" />

<ResponseField name="address_line2" type="string | null" />

<ResponseField name="city" type="string | null" />

<ResponseField name="state" type="string | null" />

<ResponseField name="postal_code" type="string | null" />

<ResponseField name="country" type="string | null" />

<ResponseField name="linkedin_url" type="string | null" />

<ResponseField name="notes" type="string | null" />

<ResponseField name="custom_fields" type="object" />

<ResponseField name="last_activity_at" type="string | null">
  ISO 8601 timestamp of the most recent activity on a related contact.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## List companies

<ParamField path="method" type="GET">
  `GET /api/v1/companies`
</ParamField>

Paginated list of companies in the workspace.

### Query parameters

| Param       | Type    | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `search`    | string  | Match against name, domain, or industry         |
| `tags`      | string  | Comma-separated list of tags                    |
| `industry`  | string  | Exact-match industry filter                     |
| `domain`    | string  | Exact-match domain filter                       |
| `bot_id`    | string  | Restrict to companies owned by a specific agent |
| `page`      | integer | See [Pagination](/api-reference/pagination)     |
| `page_size` | integer | See [Pagination](/api-reference/pagination)     |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/companies?search=acme" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "co_01HABC...",
      "workspace_id": "w_01HXXX...",
      "bot_id": "b_01HDEF...",
      "name": "Acme Corp",
      "domain": "acme.com",
      "website": "https://acme.com",
      "industry": "Manufacturing",
      "company_size": "200-500",
      "employee_count": 320,
      "annual_revenue": 18000000,
      "emails": [{ "email": "hello@acme.com", "is_primary": true }],
      "phone_numbers": [],
      "tags": ["enterprise"],
      "total_deal_value": 125000,
      "pipeline_stage_id": null,
      "city": "Austin",
      "country": "US",
      "custom_fields": {},
      "last_activity_at": "2026-04-28T13:14:00.000Z",
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-04-28T13:14:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Get a company

<ParamField path="method" type="GET">
  `GET /api/v1/companies/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "co_01HABC...",
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "tags": ["enterprise"],
    "total_deal_value": 125000,
    "created_at": "2026-03-01T10:00:00.000Z",
    "updated_at": "2026-04-28T13:14:00.000Z"
  }
}
```

***

## Create a company

<ParamField path="method" type="POST">
  `POST /api/v1/companies`
</ParamField>

Requires a key with the `write` scope.

### Body fields

| Field               | Type      | Required | Description                             |
| ------------------- | --------- | -------- | --------------------------------------- |
| `bot_id`            | string    | Yes      | Owning agent                            |
| `name`              | string    | Yes      | Company name                            |
| `domain`            | string    | No       |                                         |
| `website`           | string    | No       |                                         |
| `industry`          | string    | No       |                                         |
| `company_size`      | string    | No       |                                         |
| `company_type`      | string    | No       |                                         |
| `employee_count`    | number    | No       |                                         |
| `annual_revenue`    | number    | No       |                                         |
| `description`       | string    | No       |                                         |
| `emails`            | array     | No       | Array of `{ email, is_primary }`        |
| `phone_numbers`     | array     | No       | Array of `{ phone_number, is_primary }` |
| `tags`              | string\[] | No       |                                         |
| `pipeline_stage_id` | string    | No       |                                         |
| `address_line1`     | string    | No       |                                         |
| `address_line2`     | string    | No       |                                         |
| `city`              | string    | No       |                                         |
| `state`             | string    | No       |                                         |
| `postal_code`       | string    | No       |                                         |
| `country`           | string    | No       |                                         |
| `linkedin_url`      | string    | No       |                                         |
| `notes`             | string    | No       |                                         |
| `custom_fields`     | object    | No       |                                         |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/companies \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "b_01HDEF",
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "tags": ["enterprise"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "co_01HABC...",
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "tags": ["enterprise"],
    "created_at": "2026-04-29T18:55:00.000Z",
    "updated_at": "2026-04-29T18:55:00.000Z"
  }
}
```

***

## Update a company

<ParamField path="method" type="PATCH">
  `PATCH /api/v1/companies/{id}`
</ParamField>

Same fields as [Create a company](#create-a-company). `bot_id` cannot be changed.

### Example

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "annual_revenue": 24000000, "tags": ["enterprise", "expansion"] }'
```

```json theme={null}
{
  "data": {
    "id": "co_01HABC...",
    "annual_revenue": 24000000,
    "tags": ["enterprise", "expansion"],
    "updated_at": "2026-04-29T19:01:00.000Z"
  }
}
```

***

## Delete a company

<ParamField path="method" type="DELETE">
  `DELETE /api/v1/companies/{id}`
</ParamField>

Returns `204 No Content` with an empty body on success.

### Example

```bash theme={null}
curl -X DELETE https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example"
```

<Warning>
  Deletion is permanent. Contacts that referenced this company will have their `company_id` cleared but will not themselves be deleted.
</Warning>