Companies

Create or update a company

Creates a new company or updates an existing one.

POST

/v2/companies

curl --request POST \
  --url https://do.featurebase.app/v2/companies \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "companyId": "comp_12345",
  "companySize": 250,
  "createdAt": "2024-01-15T10:30:00Z",
  "customFields": {
    "priority": "high",
    "region": "EMEA",
    "tier": "gold"
  },
  "industry": "Technology",
  "monthlySpend": 5000,
  "name": "Acme Inc",
  "plan": "enterprise",
  "website": "https://acme.com"
}
'

{
  "companyId": "comp_12345",
  "companySize": 250,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "customFields": {
    "location": "Europe",
    "priority": "high"
  },
  "id": "507f1f77bcf86cd799439011",
  "industry": "Technology",
  "lastActivity": "2025-01-15T00:00:00.000Z",
  "linkedUsers": 15,
  "monthlySpend": 5000,
  "name": "Acme Inc",
  "object": "company",
  "plan": "enterprise",
  "updatedAt": "2025-01-10T15:30:00.000Z",
  "website": "https://acme.com"
}

Uses the external companyId as the unique identifier for upsert matching. If a company with the given companyId already exists, it will be updated. Otherwise, a new company will be created.

Request Body

Field	Type	Required	Description
`companyId`	string	Yes	External company ID from your system (unique identifier)
`name`	string	Yes	Company name
`monthlySpend`	number	No	Monthly spend/revenue from this company
`industry`	string	No	Industry the company operates in
`website`	string	No	Company website URL
`plan`	string	No	Current plan/subscription name
`companySize`	number	No	Number of employees
`createdAt`	string	No	When the company was created (ISO 8601)
`customFields`	object	No	Custom field values

Example Request

{
  "companyId": "comp_12345",
  "name": "Acme Inc",
  "monthlySpend": 5000,
  "industry": "Technology",
  "website": "https://acme.com",
  "plan": "enterprise",
  "companySize": 250,
  "customFields": {
    "region": "EMEA",
    "tier": "gold"
  }
}

Example Response

{
  "object": "company",
  "id": "507f1f77bcf86cd799439011",
  "companyId": "comp_12345",
  "name": "Acme Inc",
  "monthlySpend": 5000,
  "industry": "Technology",
  "website": "https://acme.com",
  "plan": "enterprise",
  "linkedUsers": 1,
  "companySize": 250,
  "lastActivity": "2025-01-15T00:00:00.000Z",
  "customFields": { "region": "EMEA", "tier": "gold" },
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Error Responses

400 Bad Request - Invalid company data

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

companyIdstringrequired

External company ID from your system. Used as the unique identifier for upsert matching.

Required string length: 1 - 500

Example: comp_12345

companySizenumber | null

Number of employees in the company

Required range: 0 <= x

Example: 250

createdAtstring | null

When the company was created in your system (ISO 8601)

Example: 2024-01-15T10:30:00Z

customFieldsobject

Custom field values on the company. Values can be string, number, boolean, null, or array of primitives.

industrystring

Industry the company operates in

Maximum string length: 500

Example: Technology

monthlySpendnumber

Monthly spend/revenue from this company

Required range: 0 <= x

Example: 5000

namestringrequired

Company name

Required string length: 1 - 500

Example: Acme Inc

planstring

Current plan/subscription name

Maximum string length: 500

Example: enterprise

websitestring

Company website URL

Maximum string length: 500

Example: https://acme.com

Response

Success

companyIdstringrequired

External company ID from your system

Example: comp_12345

companySizenumber | nullrequired

Company employee headcount

Example: 250

createdAtstring | nullrequired

ISO date when company was created

Example: 2025-01-01T12:00:00.000Z

customFieldsobject

Custom field values

idstringrequired

Featurebase internal ID

Example: 507f1f77bcf86cd799439011

industrystring | nullrequired

Industry

Example: Technology

lastActivitystring | nullrequired

ISO date of last activity

Example: 2025-01-15T00:00:00.000Z

linkedUsersnumber | nullrequired

Number of users linked to this company

Example: 15

monthlySpendnumber | nullrequired

Monthly spend

Example: 5000

namestringrequired

Company name

Example: Acme Inc

objectenum<string>required

Object type identifier

Available options: company

Example: company

planstring | nullrequired

Plan or tier name

Example: enterprise

updatedAtstring | nullrequired

ISO date when company was last updated

Example: 2025-01-10T15:30:00.000Z

websitestring | nullrequired

Company website URL

Example: https://acme.com

Still need help? Ask the team