Capacity Pools

Note

For an introduction to capacity options, see 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. 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 /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 /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.

PATCH /v3/capacity_pools/{id}

Data reference

See Capacity Pool Object 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	Orders used to add channels to a Capacity Pool.
DIDs	DID phone numbers to which dedicated channels can be assigned.
Shared Capacity Groups	Groups through which channels from a Capacity Pool are shared among DIDs.
Countries	Countries supported by a Capacity Pool.
Inbound Trunks	Routing destinations used by inbound voice services.
Common Definitions	Shared embedded objects such as the Quantity Based Price Object.