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.

Autorizaciones

Authorizationstringheaderobligatorio

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

Encabezados

Featurebase-Versionenum<string>header

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

Opciones disponibles: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Ejemplo: 2026-08-19.orbit

Cuerpo

companyIdstringobligatorio

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

Required string length: 1 - 500

Ejemplo: comp_12345

companySizenumber | null

Number of employees in the company

Rango requerido: 0 <= x

Ejemplo: 250

createdAtstring | null

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

Ejemplo: 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

Ejemplo: Technology

monthlySpendnumber

Monthly spend/revenue from this company

Rango requerido: 0 <= x

Ejemplo: 5000

namestringobligatorio

Company name

Required string length: 1 - 500

Ejemplo: Acme Inc

planstring

Current plan/subscription name

Maximum string length: 500

Ejemplo: enterprise

websitestring

Company website URL

Maximum string length: 500

Ejemplo: https://acme.com

Respuesta

Success

companyIdstringobligatorio

External company ID from your system

Ejemplo: comp_12345

companySizenumber | nullobligatorio

Company employee headcount

Ejemplo: 250

createdAtstring | nullobligatorio

ISO date when company was created

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

customFieldsobject

Custom field values

idstringobligatorio

Featurebase internal ID

Ejemplo: 507f1f77bcf86cd799439011

industrystring | nullobligatorio

Industry

Ejemplo: Technology

lastActivitystring | nullobligatorio

ISO date of last activity

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

linkedUsersnumber | nullobligatorio

Number of users linked to this company

Ejemplo: 15

monthlySpendnumber | nullobligatorio

Monthly spend

Ejemplo: 5000

namestringobligatorio

Company name

Ejemplo: Acme Inc

objectenum<string>obligatorio

Object type identifier

Opciones disponibles: company

Ejemplo: company

planstring | nullobligatorio

Plan or tier name

Ejemplo: enterprise

updatedAtstring | nullobligatorio

ISO date when company was last updated

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

websitestring | nullobligatorio

Company website URL

Ejemplo: https://acme.com

¿Aún necesitas ayuda? Pregunta al equipo