# Shared Capacity Groups

Note

For an introduction to inbound call capacity, see
[Capacity](../../../../phone-numbers/capacity/index.html#flexible-capacity)
and [Capacity groups](../../../../phone-numbers/capacity/capacity-groups.html#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](../capacity-pool/index.html). 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-shared-capacity-groups.html).

```
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-shared-capacity-group.html).

```
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](create-shared-capacity-group.html).

```
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](update-shared-capacity-group.html).

```
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-shared-capacity-group.html).

```
DELETE /v3/shared_capacity_groups/{id}
```

## Data reference

See [Shared Capacity Group Object](shared-capacity-group-object.html) 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. |

## Related resources

Use Shared Capacity Groups together with Capacity Pools and DIDs to distribute inbound
call capacity among multiple phone numbers.

| Resource | Description |
| --- | --- |
| [Capacity Pools](../capacity-pool/index.html) | Pools that provide the shared channels assigned to a group. |
| [DIDs](../did/index.html) | Eligible DID phone numbers that can use a group's shared or metered channels. |
| [Orders](../order/index.html) | Orders used to add flat-rate channels to a Capacity Pool. |
| [Inbound Trunks](../voice-in-trunks/index.html) | Routing destinations used by DIDs receiving inbound calls. |

On this page