Companies

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

string

Unique company identifier.

string

The agent that owns this company.

string

Company name.

string | null

Primary domain (e.g. acme.com).

string | null

Free-form size band (e.g. "50-200").

string | null

number | null

string | null

string[]

Plain email strings, lowercased. The first item is the primary email.

string[]

Plain phone strings in E.164 format. The first item is the primary number.

string[]

number | null

Sum of deal_value across all contacts linked to this company.

string | null

object

string | null

ISO 8601 timestamp of the most recent activity on a related contact.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

List companies

GET

GET /api/v1/companies

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
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/companies?search=acme" \
  -H "Authorization: Bearer ck_live_example"

{
  "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": ["hello@acme.com"],
      "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

GET

GET /api/v1/companies/{id}

Example

curl https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example"

{
  "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

POST

POST /api/v1/companies

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`	string[]	No	Plain strings, first item is primary. Stored lowercased.
`phone_numbers`	string[]	No	Plain strings in any format, first item is primary. Stored as E.164.
`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

emails and phone_numbers are arrays of plain strings. For compatibility with older integrations the API also accepts { "email": "...", "is_primary": true } and { "phone_number": "...", "is_primary": true } objects; they are converted to strings on save, and any item flagged is_primary is moved to the front. Responses always return plain strings.

Example

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"]
  }'

{
  "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

PATCH

PATCH /api/v1/companies/{id}

Same fields as Create a company. bot_id cannot be changed.

Example

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"] }'

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

Delete a company

DELETE

DELETE /api/v1/companies/{id}

Returns 204 No Content with an empty body on success.

Example

curl -X DELETE https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example"

Deletion is permanent. Contacts that referenced this company will have their company_id cleared but will not themselves be deleted.

Getting Started

Resources

The Company object

List companies

Query parameters

Example

Get a company

Example

Create a company

Body fields

Example

Update a company

Example

Delete a company

Example

​The Company object

​List companies

​Query parameters

​Example

​Get a company

​Example

​Create a company

​Body fields

​Example

​Update a company

​Example

​Delete a company

​Example

The Company object

List companies

Query parameters

Example

Get a company

Example

Create a company

Body fields

Example

Update a company

Example

Delete a company

Example