# Companies

Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.

## List all companies

 - [GET /v2/companies](https://docs.featurebase.app/rest-api/companies/listcompanies.md): Returns all companies in your organization with cursor-based pagination.

### Query Parameters

- limit - Number of companies to return (1-100, default: 10)
- cursor - Opaque cursor from a previous response for pagination

### Response Structure

The response includes:
- object - Always "list"
- data - Array of company objects
- nextCursor - Cursor for the next page (null if no more results)

### Company Object

Each company includes:
- id - Featurebase internal ID (MongoDB ObjectId)
- companyId - External company ID from your system
- name - Company name
- monthlySpend - Monthly spend/revenue
- industry - Industry
- website - Company website URL
- plan - Plan/tier name
- linkedUsers - Number of users linked to this company
- companySize - Employee headcount
- lastActivity - Last activity timestamp
- customFields - Custom field values
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example Response

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


### Version Availability

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

## Create or update a company

 - [POST /v2/companies](https://docs.featurebase.app/rest-api/companies/upsertcompany.md): 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.

## Get company by ID

 - [GET /v2/companies/{id}](https://docs.featurebase.app/rest-api/companies/getcompanybyid.md): Retrieves a single company by its Featurebase ID.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Response

Returns a company object with:
- id - Featurebase internal ID
- companyId - External company ID from your system
- name - Company name
- monthlySpend - Monthly spend/revenue
- industry - Industry
- website - Company website URL
- plan - Plan/tier name
- linkedUsers - Number of users linked to this company
- companySize - Employee headcount
- lastActivity - Last activity timestamp
- customFields - Custom field values
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example Response

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


### Error Responses

- 404 Not Found - Company with the specified ID does not exist

### Version Availability

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

## Delete a company

 - [DELETE /v2/companies/{id}](https://docs.featurebase.app/rest-api/companies/deletecompanybyid.md): Deletes a company by its Featurebase ID.

This will also remove the company from all linked users' associations.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Response

Returns a deletion confirmation object:

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "company",
  "deleted": true
}


### Error Responses

- 404 Not Found - Company with the specified ID does not exist

### Version Availability

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

## List contacts attached to a company

 - [GET /v2/companies/{id}/contacts](https://docs.featurebase.app/rest-api/companies/listcompanycontacts.md): Returns all contacts (customers) attached to a specific company.

Only returns contacts with type "customer" that have the company in their companyIds array.
Uses cursor-based pagination.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Query Parameters

- limit - Number of contacts to return (1-100, default: 10)
- cursor - Opaque cursor from a previous response for pagination

### Response Structure

The response includes:
- object - Always "list"
- data - Array of contact objects
- nextCursor - Cursor for the next page (null if no more results)

### Example Response

json
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "507f1f77bcf86cd799439011",
      "userId": "usr_12345",
      "email": "john@acme.com",
      "name": "John Doe",
      "type": "customer",
      "companies": [...],
      "createdAt": "2025-01-01T12:00:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Error Responses

- 404 Not Found - Company with the specified ID does not exist

### Version Availability

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

## Attach a contact to a company

 - [POST /v2/companies/{id}/contacts](https://docs.featurebase.app/rest-api/companies/attachcontacttocompany.md): Attaches a contact (customer) to a company.

Adds the company to the contact's companyIds array and embedded companies array.
This operation is additive - existing company associations are preserved.
Also increments the linkedUsers count on the company.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| contactId | string | Yes | The Featurebase internal ID of the contact to attach (MongoDB ObjectId) |

### Example Request

json
{
  "contactId": "507f1f77bcf86cd799439012"
}


### Response

Returns the updated contact object with the new company association.

### Example Response

json
{
  "object": "contact",
  "id": "507f1f77bcf86cd799439012",
  "userId": "usr_12345",
  "email": "john@acme.com",
  "name": "John Doe",
  "type": "customer",
  "companies": [
    {
      "object": "company",
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "name": "Acme Inc"
    }
  ]
}


### Error Responses

- 404 Not Found - Company or contact does not exist

### Version Availability

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

## Remove a contact from a company

 - [DELETE /v2/companies/{id}/contacts/{contactId}](https://docs.featurebase.app/rest-api/companies/removecontactfromcompany.md): Removes a contact (customer) from a company.

Removes the company from the contact's companyIds array and embedded companies array.
Also decrements the linkedUsers count on the company.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)
- contactId - The Featurebase internal ID of the contact to remove (MongoDB ObjectId)

### Response

Returns the updated contact object with the company removed.

### Example Response

json
{
  "object": "contact",
  "id": "507f1f77bcf86cd799439012",
  "userId": "usr_12345",
  "email": "john@acme.com",
  "name": "John Doe",
  "type": "customer",
  "companies": []
}


### Error Responses

- 400 Bad Request - Contact is not attached to this company
- 404 Not Found - Company or contact does not exist

### Version Availability

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