Create or update a company

POST/v2/companies

Creates a new company or updates an existing one.

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.

Header ParametersExpand Collapse

"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"

One of the following:

"2026-01-01.nova"

"2025-12-12.clover"

Body ParametersJSONExpand Collapse

companyId: string

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

minLength1

maxLength500

name: string

Company name

minLength1

maxLength500

companySize: optional number

Number of employees in the company

minimum0

createdAt: optional string

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

customFields: optional object { priority, region, tier }

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

priority: optional string

region: optional string

tier: optional string

industry: optional string

Industry the company operates in

maxLength500

monthlySpend: optional number

Monthly spend/revenue from this company

minimum0

plan: optional string

Current plan/subscription name

maxLength500

website: optional string

Company website URL

maxLength500

ReturnsExpand Collapse

Company object { id, companyId, companySize, 11 more }

id: string

Featurebase internal ID

companyId: string

External company ID from your system

companySize: number

Company employee headcount

createdAt: string

ISO date when company was created

industry: string

Industry

lastActivity: string

ISO date of last activity

linkedUsers: number

Number of users linked to this company

monthlySpend: number

Monthly spend

name: string

Company name

object: "company"

Object type identifier

plan: string

Plan or tier name

updatedAt: string

ISO date when company was last updated

website: string

Company website URL

customFields: optional map[unknown]

Custom field values

Create or update a company

curl https://do.featurebase.app/v2/companies \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY" \
    -d '{
          "companyId": "comp_12345",
          "name": "Acme Inc",
          "companySize": 250,
          "createdAt": "2024-01-15T10:30:00Z",
          "industry": "Technology",
          "monthlySpend": 5000,
          "plan": "enterprise",
          "website": "https://acme.com"
        }'

{
  "id": "507f1f77bcf86cd799439011",
  "companyId": "comp_12345",
  "companySize": 250,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "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",
  "customFields": {
    "location": "bar",
    "priority": "bar"
  }
}

Returns Examples

{
  "id": "507f1f77bcf86cd799439011",
  "companyId": "comp_12345",
  "companySize": 250,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "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",
  "customFields": {
    "location": "bar",
    "priority": "bar"
  }
}