# Get all team routing settings

> GET /v1/routing/settings · Queues and routing API

Source: https://developer.kustomer.com/api/queues-and-routing/get-all-team-routing-settings

```http
GET https://{orgname}.api.kustomerapp.com/v1/routing/settings
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.routing.read`; or legacy `org.user.routing.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Retrieves a paginated list of team routing settings.

## About Team routing settings

Team routing settings decide how routing treats the agents on one team. They set which queues the team works, how much work each agent can hold at once, and whether routing is turned on for the team.

Routing works through teams. A [team](https://developer.kustomer.com/api/access-management#teams) is a group of users, and its routing settings are a separate record, one per team, that admins edit in Kustomer's routing settings. The record is addressed by the team ID and is created the first time you save it. Agents can route only through teams that have settings with `enabled: true`.

When an agent signs in to routing, their [work session](https://developer.kustomer.com/api/queues-and-routing#work-sessions) is tied to one of their teams, and that team's settings supply the session's queues and capacity. An agent on several routing teams chooses which one to work as, and can switch; switching changes which queues they draw from.

#### Queues

`queues` lists up to 10 [queue](https://developer.kustomer.com/api/queues-and-routing#queues) IDs the team works, and every ID must belong to an existing queue. Agents on the team are offered items only from these queues. When you change the list, Kustomer updates the queues on the team's active work sessions straight away. `externalQueues` takes at most one external queue name, such as `amazon-connect`, for teams that take calls from a third-party phone system that runs its own queues.

#### Capacity

Capacity is how much work an agent can hold at once. Each assigned work item uses capacity equal to the `itemSize` of its queue, and a paused (snoozed) item uses none.

| Field | Meaning |
| --- | --- |
| `workItemCapacity` | Total capacity for each agent on the team, from 1 to 50. Defaults to 1. |
| `capacity` | Optional limits by priority: an object whose keys are queue priority numbers and whose values (1 to 50) are the most capacity items of that priority may use, such as `{ "1": 2, "2": 3 }`. |

Per-priority limits keep low-priority work from filling every slot. On the work session, they appear as the `capacity` array, with `limit` and `remaining` for each priority.

#### Which endpoint to use

| To | Call |
| --- | --- |
| List settings for every team | [`GET /v1/routing/settings`](https://developer.kustomer.com/api/queues-and-routing/get-all-team-routing-settings) |
| Read one team's settings | [`GET /v1/routing/settings/{id}`](https://developer.kustomer.com/api/queues-and-routing/get-team-routing-settings), with the team ID |
| See the settings for the signed-in user's teams | [`GET /v1/routing/users/current/settings`](https://developer.kustomer.com/api/queues-and-routing/get-current-users-team-routing-settings) |
| Create or change a team's settings | [`PUT /v1/routing/settings/{id}`](https://developer.kustomer.com/api/queues-and-routing/update-team-routing-settings), with the team ID |

`PUT` creates the settings if the team has none and otherwise changes only the fields you send; `queues`, when sent, replaces the whole list. `GET /v1/routing/settings/{id}` returns `404` for a team whose settings have never been saved. Updating settings needs a team-admin role (`org.admin.team.write`) or `org.permission.routing.update`.

Related: [Queues](https://developer.kustomer.com/api/queues-and-routing#queues), [Work sessions](https://developer.kustomer.com/api/queues-and-routing#work-sessions), [Teams](https://developer.kustomer.com/api/access-management#teams)

### Recipes

#### 1. Add a queue to a team without dropping the others

Have a team start working one more queue, for example when you launch a new product line, while keeping the queues it already serves.

**Step 1.** [`GET /v1/routing/settings/{id}`](https://developer.kustomer.com/api/queues-and-routing/get-team-routing-settings.md). Read the team's settings with the team's ID. The queue IDs are in `relationships.queues.data`, which is missing when the team has no queues. A `404` means the team's settings have never been saved, so start from an empty list.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/routing/settings/$TEAM_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/routing/settings/$TEAM_ID \
  | jq --arg q "$QUEUE_ID" '{queues: ([.data.relationships.queues.data[]?.id] + [$q] | unique)}' > settings.json
```

**Step 2.** [`PUT /v1/routing/settings/{id}`](https://developer.kustomer.com/api/queues-and-routing/update-team-routing-settings.md). Send the full list with the new queue added; `queues` replaces the list rather than appending to it. A team can work up to 10 queues, and every ID must be an existing queue or the request fails with `400`. Agents already signed in to routing on the team pick up the change straight away.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/routing/settings/$TEAM_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @settings.json
```

```bash title="kusty"
kusty api PUT /v1/routing/settings/$TEAM_ID --data @settings.json
```

#### 2. Set up routing for a new team

Turn on routing for a team you just created, with its queues and how much work each agent can hold.

**Step 1.** [`GET /v1/teams`](https://developer.kustomer.com/api/access-management/get-teams.md). Find the team's ID. Routing settings are addressed by the team's ID, not by an ID of their own.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/teams?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/teams --all | jq -r 'select(.data.attributes.name == "Tier 2") | .data.id'
```

**Step 2.** [`PUT /v1/routing/settings/{id}`](https://developer.kustomer.com/api/queues-and-routing/update-team-routing-settings.md). `PUT` creates the settings when the team has none. Set `enabled`, the `queues` the team works, and `workItemCapacity` (1 to 50). `capacity` optionally caps how much of that each queue priority may use; here, items from priority 3 queues can use at most 1 of each agent's 3 units.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/routing/settings/$TEAM_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"enabled\": true, \"queues\": [\"$QUEUE_ID\"], \"workItemCapacity\": 3, \"capacity\": {\"3\": 1}}"
```

```bash title="kusty"
kusty api PUT /v1/routing/settings/$TEAM_ID --field enabled:=true --field queues:="[\"$QUEUE_ID\"]" \
  --field workItemCapacity:=3 --field capacity:='{"3": 1}'
```

> Agents also need a [routing user status](https://developer.kustomer.com/api/queues-and-routing#routing-user-statuses) of type `available` before routing offers them work.

#### 3. Find the teams that work a queue

List every team that draws work from a given queue, for example before you retire or restrict the queue.

**Step 1.** [`GET /v1/routing/settings`](https://developer.kustomer.com/api/queues-and-routing/get-all-team-routing-settings.md). Page through every team's settings and keep those whose `relationships.queues` includes the queue. Note each one's `enabled` flag; disabled teams don't route.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/routing/settings?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/routing/settings --all \
  | jq -r --arg q "$QUEUE_ID" 'select(any(.data.relationships.queues.data[]?; .id == $q))
      | [.data.relationships.team.data.id, .data.attributes.enabled] | @tsv' > teams.tsv
```

**Step 2.** [`GET /v1/teams/{id}`](https://developer.kustomer.com/api/access-management/get-team-by-id.md). Settings carry team IDs only. Look each team up for its `name`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/teams/$TEAM_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/teams/$TEAM_ID --fields attributes.name
```

### Example object

A real record from [`GET /v1/routing/settings/{id}`](https://developer.kustomer.com/api/queues-and-routing/get-team-routing-settings.md):

```json
{
  "id": "5de9212aa0497287140676a8",
  "type": "team_routing_settings",
  "attributes": {
    "updatedAt": "2019-12-05T15:24:26.151Z",
    "createdAt": "2019-12-05T15:24:26.151Z",
    "modifiedAt": "2019-12-05T15:24:26.151Z",
    "enabled": true,
    "workItemCapacity": 1,
    "externalQueues": [],
    "capacity": {}
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "57504f64d76808100089eb44"
      },
      "links": {
        "self": "/v1/orgs/57504f64d76808100089eb44"
      }
    },
    "team": {
      "data": {
        "type": "team",
        "id": "5de9211d2448a00014864c76"
      },
      "links": {
        "self": "/v1/teams/5de9211d2448a00014864c76"
      }
    },
    "modifiedBy": {
      "data": {
        "type": "user",
        "id": "57504f644c80120f00f3c378"
      },
      "links": {
        "self": "/v1/users/57504f644c80120f00f3c378"
      }
    },
    "queues": {
      "data": [
        {
          "type": "queue",
          "id": "5de87b2969498a001ace7904"
        }
      ]
    }
  },
  "links": {
    "self": "/v1/routing/settings/5de9212aa0497287140676a8"
  }
}
```

Fields:

- `id` (string): The settings record's own ID. `GET` and `PUT /v1/routing/settings/{id}` take the team's ID instead, from `relationships.team`.
- `attributes.enabled` (boolean): Agents can route through this team only while it's `true`.
- `attributes.workItemCapacity` (integer): Total capacity for each agent on the team, from 1 to 50 (default 1). Each assigned work item uses its `itemSize`; paused items use none.
- `attributes.externalQueues` (array): At most one external queue name, such as `amazon-connect`, for teams that take calls from a third-party phone system with its own queues.
- `attributes.capacity` (object): Optional limits by priority: keys are queue priority numbers, values (1 to 50) are the most capacity items of that priority may use, as in `{ "1": 2, "2": 3 }`. Empty means no per-priority limits.
- `relationships.team` (object): The team these settings belong to. Use its ID in the path to read or change them.
- `relationships.queues` (object): The queues the team works, up to 10. Sending `queues` on `PUT` replaces the whole list. Missing when the team has no queues.

### Relationships

- Points to **Teams** via `relationships.team`: The team these routing settings belong to. Each team has at most one team routing settings record, addressed by the team's ID.
- Points to **Queues** via `relationships.queues` (list): The queues a team works, from its team routing settings. Agents on the team are offered work items only from these queues, up to 10.
- Referenced by **Work sessions** via `relationships.routingSettings`

### Permissions

Fewest roles for a read-only integration: `org.permission.routing.read`. For every endpoint: `org.permission.routing.read`, `org.permission.routing.update`.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | Page number to return. |
| `pageSize` | integer | no | Number of records to return per page. |

## Responses

### 200

OK

- `meta` (object, required)
  - `pageSize` (integer, required)
  - `page` (integer, required)
- `links` (object, required)
  - `self` (string, required)
  - `first` (string, required)
  - `prev` (string, required, nullable)
  - `next` (string, required, nullable)
- `data` (array<object>, required)
  - `id` (string, required)
  - `type` (string, required)
  - `attributes` (object, required)
    - `updatedAt` (string, required)
    - `createdAt` (string, required)
    - `modifiedAt` (string, required)
    - `enabled` (boolean, required)
    - `workItemCapacity` (integer, required)
    - `externalQueues` (array<any>, required)
    - `capacity` (object, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `team` (object, required)
    - `modifiedBy` (object, required)
    - `queues` (object, required)
  - `links` (object, required)
    - `self` (string, required)

```json
{
  "meta": {
    "pageSize": 100,
    "page": 1
  },
  "links": {
    "self": "/v1/routing/settings?page=1&pageSize=100",
    "first": "/v1/routing/settings?page=1&pageSize=100",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "5de9212aa0497287140676a8",
      "type": "team_routing_settings",
      "attributes": {
        "updatedAt": "2019-12-05T15:24:26.151Z",
        "createdAt": "2019-12-05T15:24:26.151Z",
        "modifiedAt": "2019-12-05T15:24:26.151Z",
        "enabled": true,
        "workItemCapacity": 1,
        "externalQueues": [],
        "capacity": {}
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "57504f64d76808100089eb44"
          },
          "links": {
            "self": "/v1/orgs/57504f64d76808100089eb44"
          }
        },
        "team": {
          "data": {
            "type": "team",
            "id": "5de9211d2448a00014864c76"
          },
          "links": {
            "self": "/v1/teams/5de9211d2448a00014864c76"
          }
        },
        "modifiedBy": {
          "data": {
            "type": "user",
            "id": "57504f644c80120f00f3c378"
          },
          "links": {
            "self": "/v1/users/57504f644c80120f00f3c378"
          }
        },
        "queues": {
          "data": [
            {
              "type": "queue",
              "id": "5de87b2969498a001ace7904"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/routing/settings/5de9212aa0497287140676a8"
      }
    }
  ]
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/routing/settings' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```