# Create or update a company

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

json
{
  "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

json
{
  "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.

Endpoint: POST /v2/companies
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Request fields (application/json):

  - `companyId` (string, required)
    External company ID from your system. Used as the unique identifier for upsert matching.
    Example: "comp_12345"

  - `name` (string, required)
    Company name
    Example: "Acme Inc"

  - `monthlySpend` (number)
    Monthly spend/revenue from this company
    Example: 5000

  - `industry` (string)
    Industry the company operates in
    Example: "Technology"

  - `website` (string)
    Company website URL
    Example: "https://acme.com"

  - `plan` (string)
    Current plan/subscription name
    Example: "enterprise"

  - `companySize` (number,null)
    Number of employees in the company
    Example: 250

  - `createdAt` (string,null)
    When the company was created in your system (ISO 8601)
    Example: "2024-01-15T10:30:00Z"

  - `customFields` (object)
    Custom field values on the company. Values can be string, number, boolean, null, or array of primitives.

  - `customFields.region` (string)
    Example: "EMEA"

  - `customFields.tier` (string)
    Example: "gold"

  - `customFields.priority` (string)
    Example: "high"

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "company"

  - `id` (string, required)
    Featurebase internal ID
    Example: "507f1f77bcf86cd799439011"

  - `companyId` (string, required)
    External company ID from your system
    Example: "comp_12345"

  - `name` (string, required)
    Company name
    Example: "Acme Inc"

  - `monthlySpend` (number,null, required)
    Monthly spend
    Example: 5000

  - `industry` (string,null, required)
    Industry
    Example: "Technology"

  - `website` (string,null, required)
    Company website URL
    Example: "https://acme.com"

  - `plan` (string,null, required)
    Plan or tier name
    Example: "enterprise"

  - `linkedUsers` (number,null, required)
    Number of users linked to this company
    Example: 15

  - `companySize` (number,null, required)
    Company employee headcount
    Example: 250

  - `lastActivity` (string,null, required)
    ISO date of last activity
    Example: "2025-01-15T00:00:00.000Z"

  - `customFields` (object)
    Custom field values
    Example: {"location":"Europe","priority":"high"}

  - `createdAt` (string,null, required)
    ISO date when company was created
    Example: "2025-01-01T12:00:00.000Z"

  - `updatedAt` (string,null, required)
    ISO date when company was last updated
    Example: "2025-01-10T15:30:00.000Z"

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_request"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400