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

# Teams

> Create and manage teams, and update team branding settings

## Overview

Teams are organizational units within an organization that help organize users, interviews, candidates, and other resources. You can create teams, list teams, get team details, and update team branding settings.

## Create Teams

Create one or more teams in bulk. Optionally add users to teams during creation.

**Endpoint:** `POST /qsi/gather/teams`

<ParamField name="teams" type="array" required>
  Array of team objects to create
</ParamField>

<ParamField name="teams[].name" type="string" required>
  Team name
</ParamField>

<ParamField name="teams[].displayName" type="string" required>
  Display name shown to users
</ParamField>

<ParamField name="teams[].description" type="string">
  Optional team description
</ParamField>

<ParamField name="teams[].userIds" type="array">
  Array of user IDs to add to the team
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.prod.qualifi.hr/qsi/gather/teams \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "teams": [
          {
            "name": "Engineering Team",
            "displayName": "Engineering",
            "description": "Engineering and development team"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/teams', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        teams: [
          {
            name: 'Engineering Team',
            displayName: 'Engineering',
            description: 'Engineering and development team'
          }
        ]
      })
    });
    const teams = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        'https://api.prod.qualifi.hr/qsi/gather/teams',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'teams': [
                {
                    'name': 'Engineering Team',
                    'displayName': 'Engineering',
                    'description': 'Engineering and development team'
                }
            ]
        }
    )
    teams = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Request theme={null}
  {
    "teams": [
      {
        "name": "Engineering Team",
        "displayName": "Engineering",
        "description": "Engineering and development team",
        "userIds": ["user-uuid-1", "user-uuid-2"]
      },
      {
        "name": "Sales Team",
        "displayName": "Sales",
        "description": "Sales and business development team"
      }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "teams": [
        {
          "id": "team-uuid-1",
          "name": "Engineering Team",
          "displayName": "Engineering",
          "description": "Engineering and development team",
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        },
        {
          "id": "team-uuid-2",
          "name": "Sales Team",
          "displayName": "Sales",
          "description": "Sales and business development team",
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## List Teams

Retrieve a list of teams in your organization. Optionally filter by userId to get only teams that a specific user belongs to.

**Endpoint:** `GET /qsi/gather/teams`

<ParamField query="userId" type="string">
  Filter teams to only those the user belongs to
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.prod.qualifi.hr/qsi/gather/teams?userId=user-uuid" \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const params = new URLSearchParams({
      userId: 'user-uuid'
    });

    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/teams?${params}`,
      {
        headers: {
          'x-api-key': apiKey
        }
      }
    );
    const teams = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    params = {
        'userId': 'user-uuid'
    }
    response = requests.get(
        'https://api.prod.qualifi.hr/qsi/gather/teams',
        headers={'x-api-key': api_key},
        params=params
    )
    teams = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "teams": [
        {
          "id": "team-uuid-1",
          "name": "Engineering Team",
          "displayName": "Engineering",
          "description": "Engineering and development team",
          "logoUrl": "https://example.com/logo.png",
          "accentColor": "482eeb",
          "buttonColor": "ffffff",
          "backgroundImage": "https://example.com/background.jpg",
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z",
          "archivedAt": null
        },
        {
          "id": "team-uuid-2",
          "name": "Sales Team",
          "displayName": "Sales",
          "description": null,
          "logoUrl": null,
          "accentColor": null,
          "buttonColor": null,
          "backgroundImage": null,
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z",
          "archivedAt": null
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Get Team

Retrieve a single team by its ID. The team must belong to your organization.

**Endpoint:** `GET /qsi/gather/teams/{teamId}`

<ParamField path="teamId" type="string" required>
  UUID of the team
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api.prod.qualifi.hr/qsi/gather/teams/{teamId} \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/teams/${teamId}`,
      {
        headers: {
          'x-api-key': apiKey
        }
      }
    );
    const team = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        f'https://api.prod.qualifi.hr/qsi/gather/teams/{team_id}',
        headers={'x-api-key': api_key}
    )
    team = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "team": {
        "id": "team-uuid",
        "name": "Engineering Team",
        "displayName": "Engineering",
        "description": "Engineering and development team",
        "logoUrl": "https://example.com/logo.png",
        "accentColor": "482eeb",
        "buttonColor": "ffffff",
        "backgroundImage": "https://example.com/background.jpg",
        "organizationId": "org-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null
      }
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Update Team Branding

Update branding settings for a team including colors, logo, background image, and display name.

**Endpoint:** `PATCH /qsi/gather/teams/{teamId}/branding`

<ParamField path="teamId" type="string" required>
  UUID of the team
</ParamField>

<ParamField name="accentColor" type="string">
  Accent color (hex code without #)
</ParamField>

<ParamField name="teamButtonColor" type="string">
  Button color (hex code without #)
</ParamField>

<ParamField name="teamBackgroundImage" type="string">
  URL to background image
</ParamField>

<ParamField name="logoUrl" type="string">
  URL to team logo
</ParamField>

<ParamField name="displayName" type="string">
  Updated display name
</ParamField>

<ParamField name="description" type="string">
  Updated description
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X PATCH https://api.prod.qualifi.hr/qsi/gather/teams/{teamId}/branding \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "accentColor": "482eeb",
        "teamButtonColor": "ffffff"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/teams/${teamId}/branding`,
      {
        method: 'PATCH',
        headers: {
          'x-api-key': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          accentColor: '482eeb',
          teamButtonColor: 'ffffff'
        })
      }
    );
    const team = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.patch(
        f'https://api.prod.qualifi.hr/qsi/gather/teams/{team_id}/branding',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'accentColor': '482eeb',
            'teamButtonColor': 'ffffff'
        }
    )
    team = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Request theme={null}
  {
    "accentColor": "482eeb",
    "teamButtonColor": "ffffff",
    "teamBackgroundImage": "https://example.com/background.jpg",
    "logoUrl": "https://example.com/logo.png",
    "displayName": "Engineering Team",
    "description": "Updated description"
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "team": {
        "id": "team-uuid",
        "name": "Engineering Team",
        "displayName": "Engineering Team",
        "description": "Updated description",
        "logoUrl": "https://example.com/logo.png",
        "accentColor": "482eeb",
        "teamButtonColor": "ffffff",
        "teamBackgroundImage": "https://example.com/background.jpg",
        "organizationId": "org-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:30:00Z"
      }
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:30:00Z"
    }
  }
  ```
</CodeGroup>

## Branding Colors

Team branding colors should be provided as hex codes **without** the `#` prefix:

* ✅ `"482eeb"` (correct)
* ❌ `"#482eeb"` (incorrect)

## Related Resources

<CardGroup cols={2}>
  <Card title="Users" icon="user" href="/api-reference/users">
    Learn about creating and managing users
  </Card>

  <Card title="Interviews" icon="file-text" href="/api-reference/interviews">
    Create interviews for your teams
  </Card>
</CardGroup>