Companies

For a full list of your User / Company Properties see the Properties API

Schema

Fully-expanded Company 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 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 for sending User data to Chameleon

Retrieve a Company

Retrieve a single Company.

HTTP Request

GET

https://api.chameleon.io/v3/analyze/companies/:id

GET

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)

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

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

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

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 with the property and group kinds.
Sort the matching companies by any company property.
Get the Count of Companies matching a set of filters.

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

{
  "cursor": {
    "limit": 50,
    "offset": 50
  }
}

Without filters or sort_by, companies use the standard before / after cursor pagination shown under List Companies.

Examples

All of these examples are based directly on the full schema of Segmentation Filter Expressions. Each example below is showing the value for the filters key in the JSON request body:

{
  "filters": [
    ...
  ]
}

Companies that have a specific uid

Find the company with the uid of 123:

{
  "filters": [
    {
      "kind": "property",
      "prop": "uid",
      "op": "eq",
      "value": "123"
    }
  ]
}

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:

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

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:

{
  "sort_by": "profile_count",
  "sort_dir": "desc"
}

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

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 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; sort_by, sort_dir, limit, and offset do not apply.

HTTP Response

{
  "count": 128
}

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
`uid`	optional	The Company identifier (typically the Database ID from your backend)

HTTP Request

Either id or uid is required.

DELETE

https://api.chameleon.io/v3/edit/companies/:id

DELETE

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.

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

DELETE

https://api.chameleon.io/v3/edit/companies/:id?cascade=profiles

DELETE

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.

{
  "deletion": {
    "id": "5f3c4232c712de665632a6d5"
  },
  "deletions": [
    { "id":  "5f3c4232c712de665632a6d6" },
    { "id":  "5f3c4232c712de665632a6d7" },
    { "id":  "5f3c4232c712de665632a6d8" }
  ]
}

Getting Started

JavaScript API

Guides

Webhooks

REST API

Schema

Fully-expanded Company when listed directly or embedded with `expand` param specified properly

Non-expanded Company when embedded in another (i.e. Microsurvey response)

Create or Update a Company

Retrieve a Company

HTTP Request

List Companies

HTTP Request

Using the `expand` parameter

HTTP Response

Search Companies

HTTP Request

Examples

Companies that have a specific uid

Companies matching multiple properties

Companies sorted by profile count

Counting Companies

HTTP Request

HTTP Response

Delete a Company

HTTP Request

HTTP Response

Deleting a company and all profiles associated with it

HTTP Response

​Schema

​Fully-expanded Company when listed directly or embedded with expand param specified properly

​Non-expanded Company when embedded in another (i.e. Microsurvey response)

​Create or Update a Company

​Retrieve a Company

​HTTP Request

​List Companies

​HTTP Request

​Using the expand parameter

​HTTP Response

​Search Companies

​HTTP Request

​Examples

Companies that have a specific uid

Companies matching multiple properties

Companies sorted by profile count

​Counting Companies

​HTTP Request

​HTTP Response

​Delete a Company

​HTTP Request

​HTTP Response

​Deleting a company and all profiles associated with it

​HTTP Response

Schema

Fully-expanded Company when listed directly or embedded with `expand` param specified properly

Non-expanded Company when embedded in another (i.e. Microsurvey response)

Create or Update a Company

Retrieve a Company

HTTP Request

List Companies

HTTP Request

Using the `expand` parameter

HTTP Response

Search Companies

HTTP Request

Examples

Counting Companies

HTTP Request

HTTP Response

Delete a Company

HTTP Request

HTTP Response

Deleting a company and all profiles associated with it

HTTP Response