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

# Workspace Teams

> API endpoints for listing and retrieving workspace teams

The Workspace Teams API lets you list and fetch **teams** in your workspace. In TapTalent, a team is a group within a company (for example "Recruiting Team" or "Engineering Hiring"). Users can belong to one or more teams; when you list [Workspace Users](/api-reference/users), each user includes a `teamId` (primary team) and `teamIds` (all teams). Use this API to resolve those ids to team names and metadata.

**When to use:** Sync your directory with TapTalent teams, display which team a user belongs to, or filter or report by team.

**Response fields:** Each team returns an `id`, `name`, `createdAt` timestamp, `createdBy` (workspace user id of the user who created the team, or `null` if unknown), and `userCount` (number of users in that team). No pagination is applied to the list endpoint; all teams for the company are returned.

***

## List Teams

Returns every team in your workspace. Use this to build a local map of team id → name, or to show a list of teams in your UI.

### `GET /teams`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/teams" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": [
    {
      "id": "team-uuid-1",
      "name": "Recruiting Team",
      "createdAt": 1640000000000,
      "createdBy": "user-id-abc123",
      "userCount": 5
    },
    {
      "id": "team-uuid-2",
      "name": "Engineering Hiring",
      "createdAt": 1640001000000,
      "createdBy": "user-id-abc123",
      "userCount": 3
    }
  ]
}
```

***

## Get Team

Returns one team by `teamId`. Use this when you have a team id from a user’s `teamId` or `teamIds` and need the team’s name or details. The team must belong to your workspace; otherwise the API returns 404.

### `GET /teams/:teamId`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Path Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `teamId`  | string | Yes      | The unique identifier of the team |

### Team Object (list and get-one)

| Field       | Type           | Description                                                                                                                                    |
| ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string         | Unique identifier of the team                                                                                                                  |
| `name`      | string         | Team name                                                                                                                                      |
| `createdAt` | number         | Timestamp when the team was created                                                                                                            |
| `createdBy` | string or null | Workspace user id of the user who created the team. Resolve with `GET /users/:userId` to get creator details. May be `null` for older records. |
| `userCount` | number         | Total number of users in the team.                                                                                                             |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/teams/team-uuid-1" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": "team-uuid-1",
    "name": "Recruiting Team",
    "createdAt": 1640000000000,
    "createdBy": "user-id-abc123",
    "userCount": 5
  }
}
```

### Error Response (404)

When the team is not found or does not belong to your workspace:

```json theme={null}
{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "type": "not_found",
  "errorMessage": "Team not found in this workspace"
}
```

***

## Related

* [Workspace Users](/api-reference/users) — List and fetch users; each user includes `teamId` and `teamIds` that you can resolve with this API.
* [API Reference Overview](/api-reference/overview) — Base URL and authentication for all partner endpoints.