Companies

Companies represent organizations in your CRM. Link contacts to companies, track industries, and add custom fields.

Data Model

Field	Type	Description
`id`	`string`	Unique ID with `co_` prefix
`name`	`string`	Company name (required, max 200 chars)
`domain`	`string \| null`	Website domain (unique per workspace, max 255 chars)
`industry`	`string \| null`	Industry vertical (max 100 chars)
`size`	`string \| null`	Company size (max 50 chars)
`custom_fields`	`object`	Custom field key-value pairs
`tags`	`string[]`	Tags for categorization (max 20, each max 50 chars)
`created_at`	`string`	ISO 8601 timestamp
`updated_at`	`string`	ISO 8601 timestamp

Create a Company

curl -X POST https://api.nodestash.io/v1/companies \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Technology",
    "size": "51-200",
    "tags": ["enterprise", "saas"]
  }'

const company = await client.companies.create({
  name: 'Acme Corp',
  domain: 'acme.com',
  industry: 'Technology',
  size: '51-200',
  tags: ['enterprise', 'saas'],
})

Relationship to Contacts

Contacts can be linked to a company via company_id. When you retrieve a company, you can include its contacts:

# Get company with contact count
curl "https://api.nodestash.io/v1/companies/co_abc123?include=contact_count" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

# Get company with full contacts list
curl "https://api.nodestash.io/v1/companies/co_abc123?include=contacts" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

// List contacts for a company
const { data: contacts } = await client.contacts.list({
  company_id: 'co_abc123',
})

Deleting a company does not delete linked contacts. Instead, their company_id is set to null.

Search and Filter

# Filter by domain (substring match)
curl "https://api.nodestash.io/v1/companies?domain=acme.com" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

# Filter by industry
curl "https://api.nodestash.io/v1/companies?industry=Technology&sort=name" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

const { data } = await client.companies.list({
  industry: 'Technology',
  sort: 'name',
  limit: 50,
})

Available Filters

Parameter	Match Type	Description
`name`	Substring (case-insensitive)	Filter by company name
`domain`	Substring (case-insensitive)	Filter by domain
`industry`	Substring (case-insensitive)	Filter by industry
`size`	Substring (case-insensitive)	Filter by company size
`tags`	All match	Comma-separated, must have all specified tags