Company Traits

Overview

Company traits describe the organization a user belongs to. They’re set via identifyCompany() or in the companyTraits config option, stored in the companies table, and included in the AI prompt as [Company: Name].

Recommended fields

Fields marked with column are stored in dedicated database columns; all others go into custom_fields.

Field	Type	Storage	Description
`name`	string	column	Company display name
`domain`	string	column	Company’s website domain
`industry`	string	column	Industry vertical
`plan`	string	column	Subscription plan
`employee_count`	number	column	Number of employees
`monthly_spend`	number	custom_fields	Monthly spend or MRR
`signed_up_at`	string	column	ISO 8601 date the company onboarded in your product. Optional, but strongly recommended for backfills, integration syncs, and any flow where Halo first sees the company well after the real customer relationship started. Populates the dedicated `companies.signed_up_at` column so it powers the “Customer since” view in the dashboard, segments, outreach campaigns targeting customer tenure, broadcasts, the AI prompt, and the `{{ company.signed_up_at }}` email merge field. Same field name and semantics on `userTraits`.
`renewal_status`	string	column	Renewal status. Allowed: `up_for_renewal`, `in_progress`, `likely_to_renew`, `expansion_opportunity`, `set_to_cancel`, `set_to_cancel_trial`, `at_risk`, `renewed`, `lost`. Auto-derived or manual.
`renewal_date`	string	column	Next renewal date (ISO 8601). Auto-derived from Stripe/PandaDoc or manual.
`contract_term`	string	column	Agreement frequency: `monthly`, `quarterly`, `annual`, `bi_annual`
`payment_terms`	string	column	Billing frequency: `monthly`, `quarterly`, `annual`, `bi_annual`
`on_contract`	boolean	column	Whether the company has an active contract

Do not send created_at, updated_at, id, health_score, team_size, or last_contacted_at in companyTraits. Halo manages these. The SDK rejects requests that include any of them with HTTP 400. If you want to set the date the company onboarded in your product, use signed_up_at (above). See System-managed fields for the full list.

System-managed fields

Halo sets these automatically. Do not pass them in companyTraits or in the REST traits body. The SDK returns HTTP 400 on any of these keys.

Field	Type	Description
`id`	string (uuid)	Halo’s internal primary key. Use `company_id` (your external ID) to upsert.
`created_at`	string	ISO 8601 timestamp set when Halo first inserted the row. Distinct from `signed_up_at` (customer-set onboarding date).
`updated_at`	string	ISO 8601 timestamp of the most recent write to the row. Maintained by `upsert_company` and a database trigger.
`health_score`	number	Account health score (0 to 100). See Health Scores.
`team_size`	number	Number of end users linked to this company. Computed at chat time.
`last_contacted_at`	string	ISO 8601 timestamp of the last time any user at this company was contacted (broadcast, series, ticket reply, or chat). Updated automatically.

signed_up_at vs created_at: signed_up_at is yours. Customer-set, optional, treated as a historical timestamp. Pass it to record when the company onboarded in your product. created_at is Halo’s. It tracks when the row was first inserted in our database, which is often days, months, or years later than the actual customer signup (especially for companies backfilled from Intercom, HubSpot, Stripe, or CSV import). The dashboard surfaces both as “Customer since” and “Added to Halo” respectively.

Do I need to send `signed_up_at`?

If you call identifyCompany() synchronously the moment a company is created in your product, sending it is optional. created_at will be approximately equal to the real signup time. You should send it whenever any of these are true:

You’re backfilling existing companies via the API or CSV import
You first identify a company via an integration sync (HubSpot, Stripe, Intercom). The Halo integrations auto-populate signed_up_at from the upstream system precisely so dashboards and outreach campaigns don’t treat every imported company as new.
You want segments and outreach campaigns targeting customer tenure (“Companies that became customers in Q3 2024”, “Renewal reminder 11 months after signup”) to measure from the real start date.

How outreach campaigns and segments read `signed_up_at`

The series “User signs up” trigger (entry_trigger: "user_created") fires on end_users row creation, not on company signed_up_at. It’s not the right tool for “company onboarded” campaigns. Use an event trigger or a segment_match trigger keyed on company.signed_up_at instead.
Audience filter on company.signed_up_at reads the column directly. Companies with no signed_up_at are skipped by that filter. There is no fallback. Send signed_up_at if you want segments based on company tenure to be accurate.
days_since_signup in onboarding rules and Slack mode-determination prefers signed_up_at, falling back to created_at when missing. So that signal degrades gracefully.
{{ company.signed_up_at }} email merge field renders blank when the column is null. Use {{ company.signed_up_at|recently }} if you mix backfilled and SDK-only companies.

Custom fields

Add any field you need:

ha.identifyCompany("company_456", {
  name: "Acme Corp",
  plan: "enterprise",
  industry: "SaaS",
  employee_count: 150,

  renewal_date: "2026-06-15",
  contract_term: "annual",
  payment_terms: "monthly",
  on_contract: true,
  renewal_status: "up_for_renewal",

  space_id: "space_789",
  region: "us-east",
  account_manager: "Sarah Johnson",
  total_ad_spend: 50000,
  active_campaigns: 12,
});

TypeScript interface

interface CompanyTraits {
  name?: string;
  domain?: string;
  industry?: string;
  plan?: string;
  employee_count?: number;
  monthly_spend?: number;
  signed_up_at?: string;
  renewal_status?: string;
  renewal_date?: string;
  contract_term?: string;
  payment_terms?: string;
  on_contract?: boolean;
  [key: string]: unknown;
}

The [key: string]: unknown index signature lets you pass any custom field, but the reserved keys in the System-managed fields table above (id, created_at, updated_at, health_score, team_size, last_contacted_at) are not writable. Sending any of them returns HTTP 400 from /api/sdk/companies/identify.

User-company linking

When you call identifyCompany(), the current user is automatically linked to that company via end_users.company_id -> companies.id. This means:

Every chat message includes both user and company traits/context
You only need to call identifyCompany() once per user. The link persists
Multiple users at the same company share company-scoped data

AI prompt output

For a company with the traits above, the AI sees:

[Company: Acme Corp]
Plan: enterprise
Industry: SaaS
Employee count: 150
Space id: space_789
Region: us-east
Account manager: Sarah Johnson
Contract renewal: 2026-06-15
Total ad spend: 50000
Active campaigns: 12

The formatter automatically converts snake_case keys to readable labels.

Where to go next

Context Entries

Structured state data beyond simple traits.

Examples

Real-world integration patterns.

Getting Started

Web Widget

AI Agents

Ask AI

Inbox

Knowledge

Channels

Help Center

Contacts & Companies

Outreach

Settings

Advanced

Overview

Recommended fields

System-managed fields

Do I need to send `signed_up_at`?

How outreach campaigns and segments read `signed_up_at`

Custom fields

TypeScript interface

User-company linking

AI prompt output

Where to go next

Context Entries

Examples

​Overview

​Recommended fields

​System-managed fields

​Do I need to send signed_up_at?

​How outreach campaigns and segments read signed_up_at

​Custom fields

​TypeScript interface

​User-company linking

​AI prompt output

​Where to go next

Context Entries

Examples

Overview

Recommended fields

System-managed fields

Do I need to send `signed_up_at`?

How outreach campaigns and segments read `signed_up_at`

Custom fields

TypeScript interface

User-company linking

AI prompt output

Where to go next