Skip to main content
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

​
id
string
Unique company identifier.
​
workspace_id
string
​
bot_id
string
The agent that owns this company.
​
name
string
Company name.
​
domain
string | null
Primary domain (e.g. acme.com).
​
website
string | null
​
industry
string | null
​
company_size
string | null
Free-form size band (e.g. "50-200").
​
company_type
string | null
​
employee_count
number | null
​
annual_revenue
number | null
​
description
string | null
​
emails
array
Array of { email, is_primary } objects.
​
phone_numbers
array
Array of { phone_number, is_primary } objects.
​
tags
string[]
​
total_deal_value
number | null
Sum of deal_value across all contacts linked to this company.
​
pipeline_stage_id
string | null
​
address_line1
string | null
​
address_line2
string | null
​
city
string | null
​
state
string | null
​
postal_code
string | null
​
country
string | null
​
linkedin_url
string | null
​
notes
string | null
​
custom_fields
object
​
last_activity_at
string | null
ISO 8601 timestamp of the most recent activity on a related contact.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.

​
List companies

​
method
GET
GET /api/v1/companies
Paginated list of companies in the workspace.

​
Query parameters

ParamTypeDescription
searchstringMatch against name, domain, or industry
tagsstringComma-separated list of tags
industrystringExact-match industry filter
domainstringExact-match domain filter
bot_idstringRestrict to companies owned by a specific agent
pageintegerSee Pagination
page_sizeintegerSee 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": [{ "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

​
method
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

​
method
POST
POST /api/v1/companies
Requires a key with the write scope.

​
Body fields

FieldTypeRequiredDescription
bot_idstringYesOwning agent
namestringYesCompany name
domainstringNo
websitestringNo
industrystringNo
company_sizestringNo
company_typestringNo
employee_countnumberNo
annual_revenuenumberNo
descriptionstringNo
emailsarrayNoArray of { email, is_primary }
phone_numbersarrayNoArray of { phone_number, is_primary }
tagsstring[]No
pipeline_stage_idstringNo
address_line1stringNo
address_line2stringNo
citystringNo
statestringNo
postal_codestringNo
countrystringNo
linkedin_urlstringNo
notesstringNo
custom_fieldsobjectNo

​
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

​
method
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

​
method
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.