# Teams

## Team Object

Teams are represented as JSON objects with the following properties:

<table data-full-width="true"><thead><tr><th width="150">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>The unique identifier for the team. Used as the <code>id</code> in the path for retrieving a specific team.</td></tr><tr><td>name</td><td>string</td><td>The display name of the team.</td></tr><tr><td>is_active</td><td>boolean</td><td>Indicates if the team is currently active within ClearFeed.</td></tr><tr><td>source</td><td>string</td><td>The source platform where the team originates (e.g., <code>slack</code>).</td></tr><tr><td>source_id</td><td>string</td><td>The identifier of the team in the source platform (e.g., Slack User Group ID).</td></tr><tr><td>created_at</td><td>string (ISO 8601)</td><td>The timestamp when the team was created in ClearFeed.</td></tr><tr><td>updated_at</td><td>string (ISO 8601)</td><td>The timestamp when the team was last updated in ClearFeed.</td></tr><tr><td>team_members</td><td>array</td><td>(Optional) An array of team member objects. This field is only included if the <code>include=team_members</code> query parameter is specified. Details about the object can be found <a href="#team-member-object">here</a>.</td></tr></tbody></table>

## Team Member Object

Team members associated with a team are represented as JSON objects with the following properties. This object is included within the `team_members` array when the `include=team_members` query parameter is specified.

<table data-full-width="true"><thead><tr><th width="150">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>The User ID (e.g., Slack User ID) of the team member.</td></tr><tr><td>created_at</td><td>string (ISO 8601)</td><td>The timestamp when the member was associated with the team in ClearFeed.</td></tr></tbody></table>

## Get All Teams

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

Retrieves a list of all teams configured in your ClearFeed account.

#### Query Parameters

| Name      | Type   | Description                                                                                                                                   |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | string | (Optional) Must be set to the exact value `team_members` to include the list of members (`team_members` array) for each team in the response. |

{% tabs %}
{% tab title="200 OK (Basic)" %}

```json
{
  "teams": [
    {
      "id": 1,
      "name": "Team1",
      "is_active": false,
      "source": "slack",
      "source_id": "S07HSCN0ZBN",
      "created_at": "2025-02-28T06:53:05.723Z",
      "updated_at": "2025-02-28T06:53:05.723Z"
    },
    {
      "id": 2,
      "name": "Team2",
      "is_active": false,
      "source": "slack",
      "source_id": "S07J1F0KAQH",
      "created_at": "2025-02-28T06:53:05.723Z",
      "updated_at": "2025-02-28T06:53:05.723Z"
    }
  ]
}
```

{% endtab %}

{% tab title="200 OK (With Team Members)" %}

```json
{
  "teams": [
    {
      "id": 1,
      "name": "Team1",
      "is_active": false,
      "source": "slack",
      "source_id": "S07HSCN0ZBN",
      "created_at": "2025-02-28T06:53:05.723Z",
      "updated_at": "2025-02-28T06:53:05.723Z",
      "team_members": [
        {
          "id": "U05HQ3DLCGJ",
          "created_at": "2025-02-28T06:53:05.763Z"
        },
        {
          "id": "U05J32X71UH",
          "created_at": "2025-02-28T06:53:05.763Z"
        }
      ]
    },
    {
      "id": 2,
      "name": "Team2",
      "is_active": false,
      "source": "slack",
      "source_id": "S07J1F0KAQH",
      "created_at": "2025-02-28T06:53:05.723Z",
      "updated_at": "2025-02-28T06:53:05.723Z",
      "team_members": [
        {
          "id": "U058TQ656H0",
          "created_at": "2025-02-28T06:53:05.763Z"
        },
        {
          "id": "U05J32X71UH",
          "created_at": "2025-02-28T06:53:05.763Z"
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
{
  // Occurs if the API token is invalid or lacks permission
  "statusCode": 403,
  "message": "Forbidden"
}
```

{% endtab %}
{% endtabs %}

## Get Team by ID

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

Retrieves the details of a specific team using its unique ClearFeed identifier.

#### Path Parameters

| Name                                 | Type    | Description                                                    |
| ------------------------------------ | ------- | -------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | The unique identifier (`id`) of the team you want to retrieve. |

#### Query Parameters

| Name      | Type   | Description                                                                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `include` | string | (Optional) Must be set to the exact value `team_members` to include the list of members (`team_members` array) for the team. |

{% tabs %}
{% tab title="200 OK (Basic)" %}

```json
{
  "team": {
    "id": 2,
    "name": "Team_name",
    "is_active": true,
    "source": "slack",
    "source_id": "S08FH74RLCA",
    "created_at": "2025-02-28T07:04:21.633Z",
    "updated_at": "2025-03-04T09:05:07.542Z"
  }
}
```

{% endtab %}

{% tab title="200 OK (With Team Members)" %}

```json
{
  "team": {
    "id": 2,
    "name": "Team_name",
    "is_active": true,
    "source": "slack",
    "source_id": "S08FH74RLCA",
    "created_at": "2025-02-28T07:04:21.633Z",
    "updated_at": "2025-03-04T09:05:07.542Z",
    "team_members": [
      {
        "id": "U087BT58BE1",
        "created_at": "2025-02-28T07:04:22.372Z"
      },
      {
        "id": "U087T6WGBPB",
        "created_at": "2025-02-28T07:04:22.372Z"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
// Occurs if the API token is invalid or lacks permission
{
  "statusCode": 403,
  "message": "Forbidden"
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
// Occurs if no team exists with the specified id for the account
{
  "statusCode": 404,
  "message": "Team not found"
}
```

{% endtab %}
{% endtabs %}