> For the complete documentation index, see [llms.txt](https://docs.clearfeed.ai/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearfeed.ai/api/reference/api-reference/collections.md).

# Collections

## Collection Object

Collections are represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="200">Name</th><th width="96.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>The ID of the collection.</td></tr><tr><td>name</td><td>string</td><td>The name of the collection.</td></tr><tr><td>owner</td><td>string</td><td>ID of the user who is set as the owner of the collection.</td></tr><tr><td>created_by</td><td>string</td><td>ID of the user who created the collection.</td></tr><tr><td>config</td><td>object</td><td>Details about the object can be found <a href="#config-object">here</a>.</td></tr><tr><td>emoji_config</td><td>object</td><td>Details about the object can be found <a href="#emoji-config-object">here</a>.</td></tr><tr><td>ticketing_config</td><td>object</td><td>Details about the object can be found <a href="#ticketing-config-object">here</a>.</td></tr><tr><td>csat_config</td><td>object</td><td>Details about the object can be found <a href="#csat-config-object">here</a>.</td></tr><tr><td>created_at</td><td>string</td><td>The creation timestamp of the collection</td></tr><tr><td>updated_at</td><td>string</td><td>The update timestamp of the collection</td></tr></tbody></table>

## Config Object

Config is represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="199.33333333333331">Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>story_detection</td><td>boolean</td><td>Indicates if story detection is enabled</td></tr><tr><td>force_story_request</td><td>boolean</td><td>Indicates if forcing story request is enabled</td></tr><tr><td>auto_assign</td><td>object</td><td>Object containing auto assign information</td></tr><tr><td>responders</td><td>array</td><td><p>Array of responder objects. The following two types of objects are possible:</p><pre class="language-json"><code class="lang-json">{
  "responder_type": "users",
  "value": [
    "U038DHU0J6A"
  ]
}
{
  "responder_type": "domains",
  "value": [
    "clearfeed.ai"
  ]
}
</code></pre></td></tr></tbody></table>

## Emoji Config Object

Emoji Config is represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="148.33333333333331">Name</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>emoji_names</td><td>object</td><td><p>Object containing configuration for all emojis that are set up at the collection level. It has the following properties. For all emojis set up, there will be a key with the same emoji_name, and the value will be the config object for that emoji.</p><p><strong>Each emoji_name object contains:</strong></p><ul><li><strong>action:</strong> Type of action (<code>assign</code> or <code>solved</code>)</li><li><strong>enabled:</strong> Indicates if the action is enabled</li><li><strong>action_config:</strong> Object with configuration settings</li></ul><pre class="language-json"><code class="lang-json">"action_config": {
  "apply_on_request_channel": "boolean"
}
</code></pre></td></tr></tbody></table>

## Ticketing Config Object

Ticket Config is represented as a JSON object with the following properties

| Name        | Type    | Description                                                                                                                                         |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| enabled     | boolean | Indicates if the feature is enabled                                                                                                                 |
| integration | string  | The integration being used                                                                                                                          |
| method      | object  | <p>Object containing method information.<br>emoji: Name of the emoji used (if method is emoji)<br>type: Type of method ("emoji" or "automatic")</p> |

## CSAT Config Object

CSAT Config is represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="164">Name</th><th width="137.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>enabled</td><td>boolean</td><td>Indicates if the feature is enabled</td></tr><tr><td>trigger_rules</td><td>array</td><td>Array of trigger rules. If there are no rules selected, then CSAT will be triggered for all REQUESTS. Current possible rules are :<br><code>{"name" : "tickets_only"}</code></td></tr><tr><td>trigger_type</td><td>string</td><td>Type of trigger (<code>automatic</code> or <code>manual</code>)</td></tr><tr><td>survey_config</td><td>object</td><td>Object containing survey configuration information<br>survey_type: Type of survey (e.g., <code>five_point_rating</code>)</td></tr></tbody></table>

## Channel Object

A channel monitored in a collection is represented as a JSON object with the following properties. It is included in the API when the `include` query parameter is passed with the value `channels`.

<table data-full-width="true"><thead><tr><th width="164">Name</th><th width="156.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>ID of the monitored channel</td></tr><tr><td>owner</td><td>string</td><td>User ID of the primary individual responsible for the channel</td></tr><tr><td>name</td><td>string</td><td>Name of the channel</td></tr><tr><td>status</td><td>enum</td><td><p>Denotes the status of the channel in the collection. Possible values:</p><ul><li><strong>active:</strong> Channel belongs to the collection and is being actively monitored.</li><li><strong>processing:</strong> Channel was added to the collection and last few messages of the channel are being processed.</li><li><strong>inactive:</strong> Channel belongs to the collection but is not being monitored.</li></ul></td></tr><tr><td>customer_id</td><td>number</td><td>ID of the associated customer. Only present for Customer Inbox enabled accounts.</td></tr></tbody></table>

## Get Collections

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/collections`

Get all collections in your account

Query Parameters

<table><thead><tr><th width="118">Name</th><th width="320">Type</th><th>Description</th></tr></thead><tbody><tr><td>include?</td><td><pre class="language-typescript"><code class="lang-typescript">'channels'
</code></pre></td><td>Use the include query parameter to include more data for each collection.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```json
{
  "collections": [
    {
      "id": 1,
      "name": "premium customers",
      "owner": "U038DHU0J6A",
      "created_by": "U05HGPBRZJN",
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "config": {
        "story_detection": false,
        "force_story_request": true,
        "auto_assign": {
          "enabled": false
        },
        "responders": [
          {
            "responder_type": "users",
            "value": ["U038DHU0J6A"]
          }
        ]
      },
      "emoji_config": {
        "emoji_names": {
          "eyes": {
            "action": "assign",
            "enabled": true,
            "action_config": {
              "apply_on_request_channel": true
            }
          },
          "white_check_mark": {
            "action": "solved",
            "enabled": true,
            "action_config": {
              "apply_on_request_channel": true
            }
          }
        }
      },
      "csat_config": {
        "enabled": true,
        "trigger_rules": [],
        "trigger_type": "automatic",
        "survey_config": {
          "survey_type": "five_point_rating"
        }
      },
      "ticketing_config": {
        "enabled": true,
        "integration": "zendesk",
        "method": {
          "emoji": "ticket",
          "type": "emoji"
        }
      },
      "channels": [
        {
          "id": "C06ASRDC6R0",
          "owner": "U038DHU0J6A",
          "name": "clearfeed-google",
          "status": "active",
          "customer_id": 123 // Only returned for customer inbox enabled accounts
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}
{% endtabs %}

## Add Channels to a Collection

<mark style="color:green;">`POST`</mark> `https://api.clearfeed.app/v1/rest/collections/:id/channels`

Start monitoring channels by adding them to a collection.

#### Path Parameters

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>Number</td><td>ID of the collection to which the channels should be added. <strong>Warning:</strong> This should be the ID returned by the <a data-mention href="#get-collections">#get-collections</a> API - and not IDs referenced in ClearFeed Webapp URLs</td></tr></tbody></table>

#### Channel Object

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>string</td><td>Slack Channel ID of the channel that needs to be added to the collection. See the <a href="https://docs.slack.dev/reference/methods/conversations.list/">conversations.list</a> Slack API</td></tr><tr><td>owner</td><td>string</td><td>Slack User ID of the primary individual responsible for the channel.</td></tr></tbody></table>

For **Customer-Centric Inbox** accounts the channel object looks like the following:

> **How to check if you are on Customer-Centric Inbox:** See [this guide](https://docs.clearfeed.ai/clearfeed-help-center/clearfeed-helpdesk/customers#which-version-am-i-using) to determine which version you are using.

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>string</td><td>Slack Channel ID of the channel that needs to be added to the collection. See the <a href="https://docs.slack.dev/reference/methods/conversations.list/">conversations.list</a> Slack API</td></tr><tr><td>customer</td><td>object</td><td>Customer association for the channel. See <a href="#customer-object">Customer Object</a> below for details. This is optional in this API. When it's not provided, ClearFeed tries to automatically link the newly monitored channel to an existing customer object based on the domains of the users present in the channel. If no existing customer exists with those domains, ClearFeed will create a new customer object and link it to the channel.</td></tr></tbody></table>

#### Customer Object

The customer object that can be passed with the channel object for Customer-Centric Inbox accounts can be one of two types:

**Existing Customer Object**

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type<mark style="color:red;">*</mark></td><td>string</td><td>Must be set to <code>"existing"</code></td></tr><tr><td>id<mark style="color:red;">*</mark></td><td>number</td><td>The ID of the existing customer (customer secondary_id). Must be a positive integer.</td></tr></tbody></table>

**New Customer Object**

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type<mark style="color:red;">*</mark></td><td>string</td><td>Must be set to <code>"new"</code></td></tr><tr><td>owner</td><td>string | null</td><td>Owner to assign to the new customer record. This will be used as the customer owner during creation. Can be null. If null or not provided, the system will use the owner of the collection that this customer belongs to.</td></tr><tr><td>domains</td><td>array</td><td>List of email domains associated with this customer. Must be valid FQDN (Fully Qualified Domain Names). Free domains (e.g., gmail.com, yahoo.com) are not allowed. Defaults to an empty array if not provided.</td></tr></tbody></table>

#### Sample Payload Format

**For Standard (Channel-Based) Management accounts:**

```json
{
  "channels": [
    {
      "id": "C01AB2CD1T",
      "owner": "U038DHU0J6A"
    },
    {
      "id": "C02EF3GH2X"
    }
  ]
}
```

**For Customer-Centric Inbox accounts:**

**Example 1: Link channel to existing customer**

```json
{
  "channels": [
    {
      "id": "C01AB2CD1T",
      "customer": {
        "type": "existing",
        "id": 123
      }
    }
  ]
}
```

**Example 2: Create new customer**

```json
{
  "channels": [
    {
      "id": "C02EF3GH2X",
      "customer": {
        "type": "new",
        "domains": ["acme.com", "acmecorp.com"]
      }
    }
  ]
}
```

**Example 3: Create new customer without domains**

```json
{
  "channels": [
    {
      "id": "C03HI4JKL5Y",
      "customer": {
        "type": "new"
      }
    }
  ]
}
```

#### Request Body

| Name                                       | Type  | Description                                                                                                                                                                                                                    |
| ------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| channels<mark style="color:red;">\*</mark> | Array | This will be an array of channel objects. For Standard accounts, each object contains a Channel ID `id` and optional `owner`. For Customer-Centric Inbox accounts, each object must also include a required `customer` object. |

{% tabs %}
{% tab title="201: Created Channels successfully added to collections " %}

```json
{
  "channels": [
    {
      "id": "C0A9T968PGT",
      "owner": "U0924MZ1QBZ", // Only returned in case of Standard (Channel-Based) Management accounts
      "name": "abcdef",
      "status": "processing",
      "customer_id": 123
    }
  ]
}
```

{% endtab %}

{% tab title="406: Not Acceptable" %}
Returned if channels cannot be added. This can happen if:

* A channel does not exist in the workspace
* A channel exists but is private and not visible to ClearFeed

If any channel in the request cannot be added (e.g., doesn't exist or isn't accessible), the entire request will fail with a 406 error and no channels will be added.
{% endtab %}
{% endtabs %}

## Clone a Collection

<mark style="color:green;">`POST`</mark> `https://api.clearfeed.app/v1/rest/collections/:id/clone`

Create a Slack collection by copying the configuration of an existing Slack collection. The clone retains settings such as ticketing, responders, assignment rules, SLAs, emojis, and the message bar. Request channels and the triage channel are set from this request instead of being copied from the source collection.

{% hint style="info" %}
This endpoint supports Slack collections only. It requires a Personal Access Token with **Read & Write** access.
{% endhint %}

#### Path Parameters

| Name                                 | Type   | Description                                                                                                                                          |
| ------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | number | Public ID of the source collection. Use the `id` returned by the [Get Collections](#get-collections) API, not the ID shown in ClearFeed Webapp URLs. |

#### Request Body

| Name                                   | Type   | Description                                                                                                            |
| -------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | string | Name of the new collection. Must contain 1–60 alphanumeric characters, spaces, apostrophes, underscores, or hyphens.   |
| channels                               | array  | Request channels to monitor. If provided, the array must contain at least one [Channel Object](#clone-channel-object). |
| triage                                 | object | Triage channel configuration. Set exactly one of `channel_id` or `new_channel_name`.                                   |

#### Clone Channel Object

| Name                                 | Type   | Description                                                                                                                                    |
| ------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | string | Slack channel ID of the request channel to monitor.                                                                                            |
| owner                                | string | Slack user ID to set as the channel owner.                                                                                                     |
| customer                             | object | Optional customer association. It accepts the same existing-customer or new-customer shapes documented in [Customer Object](#customer-object). |

#### Triage Object

| Name               | Type   | Description                                                                                                              |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| channel\_id        | string | ID of an existing Slack channel to use as the triage channel.                                                            |
| new\_channel\_name | string | Name of a Slack triage channel for ClearFeed to create. Must contain 1–80 characters; surrounding whitespace is removed. |

Set exactly one triage field. Requests containing both fields, neither field, or an empty `triage` object return a `400` response.

#### Sample Payload

```json
{
  "name": "Acme Support",
  "channels": [
    {
      "id": "C0123456789",
      "owner": "U04ABCDEF"
    }
  ],
  "triage": {
    "channel_id": "C0987654321"
  }
}
```

The `channels` and `triage` fields are independently optional. To clone only the source configuration, send only the new collection name:

```json
{
  "name": "Acme Support"
}
```

{% tabs %}
{% tab title="201: Collection successfully cloned" %}
The response contains a `collection` object in the same format documented under [Collection Object](#collection-object). When request channels are added, the response includes them in the collection.
{% endtab %}

{% tab title="400: Bad Request" %}
Returned when the payload is invalid, the source is not a Slack collection, or the triage configuration is invalid.
{% endtab %}

{% tab title="403: Forbidden" %}
Returned when a request channel is already monitored by another collection or the authenticated user does not have the required access.
{% endtab %}

{% tab title="404: Not Found" %}
Returned when the source collection does not exist.
{% endtab %}
{% endtabs %}