Companies API
The Company object
The following fields are accepted on write via POST /api/v1/companies.
| Field | Type | Notes |
|---|---|---|
id | string | CUID, assigned on create (read-only) |
name | string (required) | Max 200 characters |
domain | string | null | Primary web domain, e.g. acme.com (max 200 chars) |
industry | string | null | Industry / vertical (max 200 chars) |
size | string | null | Free-form company size, e.g. employee count band (max 100 chars) |
website | string | null | Full website URL (max 500 chars) |
notes | string | null | Free-form notes about the company |
externalId | string | null | Your system's ID — upsert key and dedupe handle (max 200 chars) |
customFields | object | null | Workspace-defined custom field values |
createdAt | string (ISO 8601) | Assigned on create (read-only) |
updatedAt | string (ISO 8601) | Updated on every write (read-only) |
Example object
{
"id": "cmq1abc2def3ghi4jkl5",
"name": "Acme Corp",
"domain": "acme.com",
"industry": "Retail",
"size": null,
"website": null,
"notes": null,
"externalId": "SHOP-CO-1",
"customFields": null,
"createdAt": "2025-06-01T12:00:00.000Z",
"updatedAt": "2025-06-01T12:00:00.000Z"
}Notes on specific fields
name is the only required field. All other fields are optional on write.
externalId is the upsert key. A row with an externalId that matches an existing company in the workspace updates that company instead of creating a duplicate.
customFields are validated against the workspace's custom field definitions for the Company entity; unknown keys are dropped.