> ## Documentation Index
> Fetch the complete documentation index at: https://developers.chameleon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies

> Companies represent your *accounts*: real customers who were identified to Chameleon. They can store complex (semi-arbitrary) properties.

> For a full list of your User / Company Properties see the [Properties API](/apis/properties)

***

<a id="schema" />

## Schema

#### Fully-expanded [Company](/apis/companies) when listed directly or embedded with `expand` param specified properly

| Property       | Type      | Description                                                                |
| -------------- | --------- | -------------------------------------------------------------------------- |
| `id`           | ID        | The Chameleon ID                                                           |
| `created_at`   | timestamp | When this happened or when this was added to the Database                  |
| `uid`          | string    | The external ID that came from your backend system                         |
| `*any options` | mixed     | Any other options you have sent as Custom Properties will show up here too |

#### Non-expanded [Company](/apis/companies) when embedded in another (i.e. Microsurvey response)

| Property     | Type      | Description                                               |
| ------------ | --------- | --------------------------------------------------------- |
| `id`         | ID        | The Chameleon ID                                          |
| `created_at` | timestamp | When this happened or when this was added to the Database |
| `uid`        | string    | The external ID that came from your backend system        |

## Create or Update a Company

See the [Companies Webhook](/webhooks/companies) for sending User data to Chameleon

<a id="companies-show" />

## Retrieve a Company

Retrieve a single Company.

#### HTTP Request

```http title="GET" theme={null}
https://api.chameleon.io/v3/analyze/companies/:id
```

or

```http title="GET" theme={null}
https://api.chameleon.io/v3/analyze/company?uid=:uid
```

| param | -        | description                                                          |
| ----- | -------- | -------------------------------------------------------------------- |
| `id`  | optional | The Chameleon ID of the Company                                      |
| `uid` | optional | The Company identifier (typically the Database ID from your backend) |

```json theme={null}
{
  "company": {
    "id": "5f3c4232c712de665632a2a1",
    "created_at": "2029-04-07T12:38:00Z",
    "uid": "1868",
    "domain": "example.com",
    "plan": "custom-92",
    "clv": 231902.42,
    ...
  }
}
```

<a id="companies-index" />

## List Companies

List all Companies.

#### HTTP Request

```
GET|POST https://api.chameleon.io/v3/analyze/companies
```

| param            | -        | description                                                                                                                 |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `limit`          | optional | Defaults to `50` with a maximum of `500`                                                                                    |
| `before`         | optional | Used when paginating, use directly from the `cursor` object from the previous response                                      |
| `before`         | optional | Read as "created `before`" and can be given as a timestamp to get only `limit` items that were created before this time     |
| `after`          | optional | Read as "created `after`" and can be given as a timestamp or ID to get only `limit` items that were created after this time |
| `expand`         | optional | Object that specifies relationships to include/exclude. Supported keys are `company`                                        |
| `expand.company` | optional | use values of `all`, `min` to control the properties present in the `company`. Defaults to `all`                            |

#### Using the `expand` parameter

```
# As a URL parameter
expand[profile]=min&expand[company]=skip

# In the Request body
{"expand":{"profile":"min","company":"skip"}}
```

#### HTTP Response

```json theme={null}
{
  "companies": [
    {
      "id": "5f3c4232c712de665632a6d5",
      "created_at": "2029-04-07T12:38:00Z",
      "uid": "1868",
      "domain": "example.com",
      "plan": "custom-92",
      "clv": 231902.42,
      ...
    },
    {
      "id": "5f3c4232c712de665632a2a1",
      "created_at": "2029-04-07T12:38:00Z",
      "uid": "2015",
      "domain": "chameleon.io",
      "plan": "custom-12",
      "clv": 39102.17,
      ...
    },
    ...
  ],
  "cursor": {
    "limit": 50,
    "before": "5f3c4232c712de665632a2a1"
  }
}
```

<a id="companies-search" />

### Search Companies

Searching Companies through the Chameleon API allows you to:

* Search for a company by `id`, `uid`, or any custom company property you have sent to us.
* Filter companies using [Segmentation Filter Expressions](/concepts/filters) with the `property` and `group` kinds.
* Sort the matching companies by any company property.
* Get the [Count of Companies](#companies-count) matching a set of filters.

> *Note: [Rate Limiting](/concepts/rate-limiting) applies according to the table below.*

| endpoint     | Maximum concurrent requests |
| ------------ | --------------------------- |
| `/companies` | 2                           |

#### HTTP Request

```
GET|POST https://api.chameleon.io/v3/analyze/companies
```

| param        | -        | description                                                                                                                                                         |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters`    | optional | The array of [Segmentation filter expressions](/concepts/filters) used to match companies. Only the `property` and `group` kinds are supported (see the note below) |
| `filters_op` | optional | The operator to apply between each filter. Use either `or` or `and` (default)                                                                                       |
| `sort_by`    | optional | A company property name to sort by — one of `id`, `uid`, `created_at`, `last_seen_at`, `profile_count`, or any custom company property you have sent to us          |
| `sort_dir`   | optional | The sort direction. Use either `asc` (default) or `desc`                                                                                                            |
| `limit`      | optional | Defaults to `50` with a maximum of `500`                                                                                                                            |
| `offset`     | optional | The number of matching companies to skip before returning results — used to page through filtered or sorted results (see the note below). Defaults to `0`           |

> *Note: Company filters support only the `property` and `group` filter kinds. The `event`, `tour`, and `survey` kinds available for [profile search](/apis/profiles-search) are not supported for companies.*

> *Note: When `filters` or `sort_by` is provided, results are paginated with an offset-based `cursor`. Pass the returned `offset` back on the next request to fetch the following page:*

```json theme={null}
{
  "cursor": {
    "limit": 50,
    "offset": 50
  }
}
```

Without `filters` or `sort_by`, companies use the standard `before` / `after` [cursor pagination](/concepts/pagination) shown under [List Companies](#companies-index).

<a id="companies-search-examples" />

#### Examples

All of these examples are based directly on the full schema of [Segmentation Filter Expressions](/concepts/filters).

Each example below is showing the value for the `filters` key in the JSON request body:

```json theme={null}
{
  "filters": [
    ...
  ]
}
```

##### Companies that have a specific uid

Find the company with the `uid` of `123`:

```json theme={null}
{
  "filters": [
    {
      "kind": "property",
      "prop": "uid",
      "op": "eq",
      "value": "123"
    }
  ]
}
```

```bash theme={null}
curl -H "X-Account-Secret: ACCOUNT_SECRET" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"filters":[{"kind":"property","prop":"uid","op":"eq","value":"123"}]}' \
     https://api.chameleon.io/v3/analyze/companies
```

The following examples show the full JSON request body.

##### Companies matching multiple properties

Find companies on the `enterprise` plan **or** with a lifetime value (`clv`) greater than `100000`, combining two property filters with `filters_op`:

```json theme={null}
{
  "filters_op": "or",
  "filters": [
    {
      "kind": "property",
      "prop": "plan",
      "op": "eq",
      "value": "enterprise"
    },
    {
      "kind": "property",
      "prop": "clv",
      "op": "gt",
      "value": 100000
    }
  ]
}
```

```bash theme={null}
curl -H "X-Account-Secret: ACCOUNT_SECRET" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"filters_op":"or","filters":[{"kind":"property","prop":"plan","op":"eq","value":"enterprise"},{"kind":"property","prop":"clv","op":"gt","value":100000}]}' \
     https://api.chameleon.io/v3/analyze/companies
```

##### Companies sorted by profile count

Return companies ordered by `profile_count`, highest first:

```json theme={null}
{
  "sort_by": "profile_count",
  "sort_dir": "desc"
}
```

```bash theme={null}
curl -H "X-Account-Secret: ACCOUNT_SECRET" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"sort_by":"profile_count","sort_dir":"desc"}' \
     https://api.chameleon.io/v3/analyze/companies
```

<a id="companies-count" />

### Counting Companies

Return the number of companies matching a set of filters, without fetching the companies themselves.

#### HTTP Request

```
GET|POST https://api.chameleon.io/v3/analyze/companies/count
```

| param        | -        | description                                                                                                                                    |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters`    | optional | The array of [Segmentation filter expressions](/concepts/filters) used to match companies. Only the `property` and `group` kinds are supported |
| `filters_op` | optional | The operator to apply between each filter. Use either `or` or `and` (default)                                                                  |

Counting uses the same `filters` / `filters_op` as [Search Companies](#companies-search); `sort_by`, `sort_dir`, `limit`, and `offset` do not apply.

#### HTTP Response

```json theme={null}
{
  "count": 128
}
```

<a id="companies-delete" />

## Delete a Company

When deleting a company, the company record itself is deleted and company is removed from all profiles associated with it.
The associated profiles can also be removed by passing `cascade=profiles` with the request.

| param. | -        | description                                                          |
| ------ | -------- | -------------------------------------------------------------------- |
| `id`   | optional | The Chameleon ID of the [Company](/apis/companies)                   |
| `uid`  | optional | The Company identifier (typically the Database ID from your backend) |

#### HTTP Request

Either `id` or `uid` is required.

```http title="DELETE" theme={null}
https://api.chameleon.io/v3/edit/companies/:id
```

or

```http title="DELETE" theme={null}
https://api.chameleon.io/v3/edit/company?uid=:uid
```

#### HTTP Response

The endpoint returns `id` of the Deletion record.
The Deletion is an internal Chameleon record that can be referenced as proof of initiating this request.

```json theme={null}
{
  "deletion": {
    "id": "5f3c4232c712de665632a6d5"
  }
}
```

### Deleting a company and all profiles associated with it

Deleting a company and all profiles associated with it can be done by passing `cascade=profiles`:

```http title="DELETE" theme={null}
https://api.chameleon.io/v3/edit/companies/:id?cascade=profiles
```

or

```http title="DELETE" theme={null}
https://api.chameleon.io/v3/edit/company?uid=:uid&cascade=profiles
```

#### HTTP Response

When cascade deletion is requested, the endpoint also returns deletion ids of all the profiles associated with the company under `deletions` key.

```json theme={null}
{
  "deletion": {
    "id": "5f3c4232c712de665632a6d5"
  },
  "deletions": [
    { "id":  "5f3c4232c712de665632a6d6" },
    { "id":  "5f3c4232c712de665632a6d7" },
    { "id":  "5f3c4232c712de665632a6d8" }
  ]
}
```