Shared Capacity Groups#

Note

For an introduction to inbound call capacity, see Capacity and Capacity groups.

Use the Shared Capacity Groups resource to create, retrieve, update, and delete groups that provide shared or metered channels to multiple DID phone numbers.

A Shared Capacity Group belongs to a Capacity Pool. DID numbers assigned to the group can use its shared flat-rate channels, metered pay-per-minute channels, or both. Dedicated channels are assigned directly to individual DIDs and do not use a Shared Capacity Group.

When both shared and metered channels are configured, shared channels are used first and metered channels provide overflow after the shared channels are unavailable. Capacity applies to inbound calls only.

Requirements and behavior#

When creating or updating a Shared Capacity Group:

  • Select the Capacity Pool to which the group belongs.

  • Provide a unique group name.

  • Assign at least one shared or metered channel.

  • Do not assign more shared channels than the unassigned channels available in the selected Capacity Pool.

  • Assign no more than 1,000 metered channels.

  • Assign only DIDs that support additional capacity.

DIDs must be assigned to the group before they can use its shared or metered channels. Removing a DID from the group stops that DID from using those channels.

Endpoints#

Action

Method

Endpoint

Retrieve all Shared Capacity Groups

GET

/v3/shared_capacity_groups

Retrieve Shared Capacity Group

GET

/v3/shared_capacity_groups/{id}

Create Shared Capacity Group

POST

/v3/shared_capacity_groups

Update Shared Capacity Group

PATCH

/v3/shared_capacity_groups/{id}

Delete Shared Capacity Group

DELETE

/v3/shared_capacity_groups/{id}

Retrieve all Shared Capacity Groups#

Retrieves all Shared Capacity Groups configured for the account.

Use this endpoint to filter groups by name, external reference ID, or Capacity Pool ID. Related DIDs and Capacity Pool data can be included in the response.

See Retrieve All Shared Capacity Groups.

GET /v3/shared_capacity_groups

Retrieve Shared Capacity Group#

Retrieves a specific Shared Capacity Group by its unique ID.

Use this endpoint to inspect the shared and metered channel counts, group details, assigned DIDs, and related Capacity Pool.

See Retrieve Shared Capacity Group.

GET /v3/shared_capacity_groups/{id}

Create Shared Capacity Group#

Creates a Shared Capacity Group in a selected Capacity Pool.

Provide a unique name, the shared or metered channel counts, and the Capacity Pool relationship. An external reference ID and the DIDs assigned to the group can also be provided.

See Create Shared Capacity Group.

POST /v3/shared_capacity_groups

Update Shared Capacity Group#

Updates a specific Shared Capacity Group.

Use this endpoint to change the group name, external reference ID, shared or metered channel counts, Capacity Pool relationship, or assigned DIDs. Providing an empty DID relationship removes all DIDs from the group.

See Update Shared Capacity Group.

PATCH /v3/shared_capacity_groups/{id}

Delete Shared Capacity Group#

Deletes a specific Shared Capacity Group from the account.

See Delete Shared Capacity Group.

DELETE /v3/shared_capacity_groups/{id}

Data reference#

See Shared Capacity Group Object for the complete group attribute and relationship definitions.

Common Shared Capacity Group use cases#

Use case

Description

Share flat-rate channels

Allow multiple DIDs to use shared channels allocated from a Capacity Pool.

Provide metered overflow

Use pay-per-minute channels when higher-priority capacity is unavailable.

Combine shared and metered channels

Use shared channels for expected traffic and metered channels for overflow.

Assign DIDs to a group

Add eligible DID phone numbers to the group’s dids relationship.

Change channel allocation

Update shared_channels_count or metered_channels_count as requirements change.

Find groups in a Capacity Pool

Filter Shared Capacity Groups by their related Capacity Pool ID.

Synchronize external systems

Store an external_reference_id for the corresponding record in another system.