Companies

Practice-side accounts: referring offices, payers, employers, insurance plans.

The company object

Companies don't hold PHI — they're contact-of-contact records. They participate in deals and tickets, and contacts can be associated to a primary company. sizeRange is one of SOLO, SMALL, MEDIUM, LARGE, ENTERPRISE.

POST/api/companiesBearer token

Create a company

Add a new company to the workspace.

Required scopes:contacts.write

Request body

Name	Type	Description
`name`required	`string`	Company display name. 1–200 chars.
`domain`	`string`	Primary web domain — used for auto-association.
`industry`	`string`	Free-form industry label.
`sizeRange`	`string`	Bucketed employee count.
`addressLine1`	`string`	Street address.
`city`	`string`	City.
`state`	`string`	State / region.
`zip`	`string`	Postal code.
`country`	`string`	Country.
`phone`	`string`	Main phone.
`website`	`string`	Website URL.
`ownerId`	`string`	Owning user. Defaults to the caller.

Request body

JSON

{ "name": "Northwell Internal Medicine", "domain": "northwell.com" }

Responses

201 CreatedCreated.

example

{
  "id": "cmp_1f8s7p…",
  "name": "Northwell Internal Medicine",
  "domain": "northwell.com",
  "industry": "Healthcare",
  "sizeRange": "MEDIUM",
  "phone": "+15555550100",
  "city": "Hempstead",
  "state": "NY",
  "ownerId": "usr_8h2c3p…",
  "createdAt": "2026-05-18T14:00:00Z"
}

422 Unprocessable EntityValidation failed.

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/companies \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Northwell Internal Medicine", "domain": "northwell.com" }'

GET/api/companiesBearer token

List companies

Search and list. Returns up to 200 companies.

Required scopes:contacts.read

Query parameters

Name	Type	Description
`q`	`string`	Search over name and domain.
`ownerId`	`string`	Filter by owning user.

Responses

200 OKMatching companies.

example

{ "companies": [{
  "id": "cmp_1f8s7p…",
  "name": "Northwell Internal Medicine",
  "domain": "northwell.com",
  "industry": "Healthcare",
  "sizeRange": "MEDIUM",
  "phone": "+15555550100",
  "city": "Hempstead",
  "state": "NY",
  "ownerId": "usr_8h2c3p…",
  "createdAt": "2026-05-18T14:00:00Z"
}] }

Code samples

Shell

curl -X GET https://app.contactfollowup.com/api/companies \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json"