## 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

```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.

### Header Parameters

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

  - `"2026-01-01.nova"`

  - `"2025-12-12.clover"`

### Body Parameters

- `companyId: string`

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

- `name: string`

  Company name

- `companySize: optional number`

  Number of employees in the company

- `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

- `monthlySpend: optional number`

  Monthly spend/revenue from this company

- `plan: optional string`

  Current plan/subscription name

- `website: optional string`

  Company website URL

### Returns

- `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

    - `"company"`

  - `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

### Example

```http
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"
        }'
```

#### Response

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