> ## Documentation Index
> Fetch the complete documentation index at: https://vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign caller pool API

> Add, list, update, and remove caller IDs for pooled voice campaigns.

Use a caller pool when `caller_id_strategy` is `pool`. The pool rotates calls across eligible numbers and applies per-number limits.

<ParamField path="account_id" type="string" required>
  Your Vobiz account ID. Use the same value in `X-Auth-ID`.
</ParamField>

<ParamField path="campaign_id" type="string" required>
  The pool campaign to update.
</ParamField>

<ParamField header="X-Auth-ID" type="string" required>
  Your Vobiz account ID, for example `MA_XXXXXXXX`.
</ParamField>

<Warning>
  You can edit the pool only while the campaign is `draft` or `ready`. Add, update, and delete return `409` while it is `running`, `paused`, or `queued`.
</Warning>

## Endpoints

| Method   | Path                                        | Description                         |
| -------- | ------------------------------------------- | ----------------------------------- |
| `POST`   | `/campaigns/{campaign_id}/pool`             | Add one or more numbers.            |
| `GET`    | `/campaigns/{campaign_id}/pool`             | List numbers with usage statistics. |
| `PUT`    | `/campaigns/{campaign_id}/pool/{number_id}` | Update a label or active state.     |
| `DELETE` | `/campaigns/{campaign_id}/pool/{number_id}` | Remove a number.                    |

All paths start with `/api/v1/account/{account_id}`.

## Add numbers

```bash cURL theme={null}
curl -X POST \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns/{campaign_id}/pool" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": [
      { "from_number": "+919000000001", "label": "DID-North-1" },
      { "from_number": "+919000000002", "label": "DID-North-2" }
    ]
  }'
```

`from_number` is required in E.164 format. `label` is optional and has a maximum of 100 characters.

```json 201 Created theme={null}
{
  "added": [
    {
      "id": "4b3890ea-e773-4cef-9442-58f644fddca7",
      "from_number": "+919000000001",
      "label": "DID-North-1",
      "total_calls": 0
    }
  ]
}
```

Save the returned `id` as `number_id` for updates or deletion.

## Rotation and limits

Configure these fields on the campaign:

| Field                       | Description                                                                   |
| --------------------------- | ----------------------------------------------------------------------------- |
| `pool_rotation_strategy`    | `round_robin`, `least_used`, or `random`.                                     |
| `pool_max_calls_per_number` | Lifetime cap per number. `null` means unlimited.                              |
| `pool_max_calls_per_day`    | Daily cap per number. Resets at midnight in the campaign timezone.            |
| `pool_cooldown_seconds`     | Minimum time between consecutive calls from the same number. `0` disables it. |

When every number reaches its lifetime cap, the campaign pauses with `caller_pool_exhausted` and requires manual resume after you make capacity available. When every number reaches its daily cap, it pauses with `caller_pool_daily_limit_reached` and resumes automatically at midnight.

## Read pool status

Each object returned by `GET /pool` includes `is_active`, `total_calls`, `daily_calls`, and `pool_status`.

| Status           | Meaning                           |
| ---------------- | --------------------------------- |
| `active`         | Eligible for selection.           |
| `at_limit`       | Reached the lifetime cap.         |
| `at_daily_limit` | Reached the daily cap.            |
| `in_cooldown`    | Within the configured cooldown.   |
| `inactive`       | Disabled with `is_active: false`. |

## Disable a number

```json theme={null}
{
  "label": "Primary DID",
  "is_active": false
}
```

Disabling excludes a number from future selection without removing its history.