# Capacity Pools

Note

For an introduction to capacity options, see
[Capacity](../../../../phone-numbers/capacity/index.html#flexible-capacity).

Use the Capacity Pools resource to retrieve and manage channels used by inbound voice
services.

A Capacity Pool contains channels that can be assigned directly to DID phone numbers or
allocated through [Shared Capacity Groups](../shared-capacity-group/index.html). Each pool
provides its total and assigned channel counts, renewal date, minimum limits, ordering
requirements, and pricing.

Capacity Pools are associated with supported countries, Shared Capacity Groups, and
quantity-based pricing tiers. Use Orders to add channels to a pool, and use the Capacity
Pools resource to remove channels that are not assigned.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Capacity Pools | `GET` | `/v3/capacity_pools` |
| Retrieve Capacity Pool | `GET` | `/v3/capacity_pools/{id}` |
| Update Capacity Pool | `PATCH` | `/v3/capacity_pools/{id}` |

## Retrieve all Capacity Pools

Retrieves all Capacity Pools available for the account.

Use this endpoint to filter pools by ID, name, supported country, or the availability of
unassigned channels. Results can be sorted by channel counts, renewal date, ordering
limits, or pricing. Related countries, Shared Capacity Groups, and quantity-based pricing
tiers can be included in the response.

See [Retrieve All Capacity Pools](get-capacity-pools.html).

```
GET /v3/capacity_pools
```

## Retrieve Capacity Pool

Retrieves a specific Capacity Pool by its unique ID.

Use this endpoint to inspect its channel allocation, renewal date, ordering limits,
pricing, supported countries, Shared Capacity Groups, and quantity-based pricing tiers.

See [Retrieve Capacity Pool](get-capacity-pool.html).

```
GET /v3/capacity_pools/{id}
```

## Update Capacity Pool

Updates the total number of channels in a specific Capacity Pool.

Use this endpoint to remove unassigned channels by reducing `total_channels_count`.
Channels that are already assigned to DIDs or Shared Capacity Groups cannot be removed
through this operation.

See [Update Capacity Pool](update-capacity-pool.html).

```
PATCH /v3/capacity_pools/{id}
```

## Data reference

See [Capacity Pool Object](capacity-pool-object.html) for the complete pool attribute and
relationship definitions.

## Common Capacity Pool use cases

| Use case | Description |
| --- | --- |
| Review inbound capacity | Compare the total and assigned channel counts for each Capacity Pool. |
| Find unassigned channels | Filter for Capacity Pools that currently have channels available for assignment. |
| Find capacity by country | Filter Capacity Pools by the countries in which their channels can be used. |
| Review capacity pricing | Inspect setup, monthly, metered, and quantity-based pricing information. |
| Check ordering requirements | Review the minimum number of channels that can be purchased per Order. |
| Add channels | Create an Order using the Capacity Pool ID and the required quantity. |
| Remove unassigned channels | Reduce `total_channels_count` without affecting channels assigned to DIDs or Shared Capacity Groups. |
| Plan renewals | Use the pool renewal date to plan capacity and billing changes. |

## Related resources

Use Capacity Pools together with Orders, DIDs, and Shared Capacity Groups to manage
inbound voice capacity.

| Resource | Description |
| --- | --- |
| [Orders](../order/index.html) | Orders used to add channels to a Capacity Pool. |
| [DIDs](../did/index.html) | DID phone numbers to which dedicated channels can be assigned. |
| [Shared Capacity Groups](../shared-capacity-group/index.html) | Groups through which channels from a Capacity Pool are shared among DIDs. |
| [Countries](../../coverage-resources/countries/index.html) | Countries supported by a Capacity Pool. |
| [Inbound Trunks](../voice-in-trunks/index.html) | Routing destinations used by inbound voice services. |
| [Common Definitions](../../common-definitions/index.html) | Shared embedded objects such as the Quantity Based Price Object. |

On this page