Number pools: rotate caller IDs and skip spam numbers

A pool is the answer to one question: does every call need to show the same ? If not, a pool spreads a campaign or high-volume API calling across several numbers and drops any that get flagged as spam. Campaigns and API calls reference the pool’s ID, so you add or swap numbers in one place without touching them. In the dashboard: Sidebar → Inventory → Numbers → Number Pools.

Before you start

Numbers in your workspace

Buy or import them.

Edit access to Numbers

Your workspace role needs the Numbers permission.

Create a pool

Creating a pool with two numbers and Auto purchase on, then opening its page

Open Number Pools

Go to Numbers, keep the Phone tab, and open Number Pools. Click Add pool.

Name the pool

In Create pool, enter a Pool name (for example India Outbound). Description is optional (for example Outbound campaigns).

Add numbers

Open Add numbers to pool and tick the numbers. Each row shows the number, its country and its added date. You can also leave the pool empty and add numbers later.

Turn on Auto purchase (optional)

Switch on Auto purchase (“Auto purchase replacements when spam detected”) and choose a Replacement country: India, United States or Canada.

Create

Click Create pool.

You see “Pool created” and a card for the pool appears.

Which numbers you can add

Number	Can join a pool?
Bought, imported or custom number	Yes
Test number	No. “Test numbers aren’t listed. They’re for trial calls and can’t join a pool.”
Number attached to an inbound agent	No. Detach it first.
Number in a pool with a campaign running	No, until the campaign ends.
Number in another pool with no campaign running	Yes. It moves out of the old pool.

Use a pool in the dashboard

When you create a campaign, the Select number card has two tabs: Individual numbers and Number pool. Choose Number pool and pick a pool. If you have none, the card shows “No number pools yet.” with a Create a pool link.

Use a pool with the API

Send number_pool_id to choose caller IDs from a pool. You need an API key, the agent’s ID (Find an agent’s ID) and the pool’s ID (Copy pool ID on the pool list).

Endpoint	Pool field
Initiate Individual Call (Number Pool) `POST /calling/v2/outbound/individual`	`number_pool_id`. Send at least one of `number_pool_id`, `from_number_id` or `from_number`; with a pool, the pool is used and the other field is ignored.
Start Campaign (Number Pool) `POST /campaign/v2/start`	`number_pool_id`, required with `agent_id` and `list_id`.
Start Large Campaign Calls `POST /campaign/make-call-async`	`number_pool_id` or `from_numbers`, exactly one. Both or neither returns `422`.

A single call from a pool:

curl -X POST "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual" \
  -H "X-API-KEY: $RINGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priya Sharma",
    "mobile_number": "+919876543210",
    "agent_id": "b1972188-038e-4605-916c-3926e9d7bde4",
    "number_pool_id": "c14cbdac-8928-4a19-8aef-df7f5eb49163"
  }'

const res = await fetch("https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual", {
  method: "POST",
  headers: { "X-API-KEY": process.env.RINGG_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Priya Sharma",
    mobile_number: "+919876543210",
    agent_id: "b1972188-038e-4605-916c-3926e9d7bde4",
    number_pool_id: "c14cbdac-8928-4a19-8aef-df7f5eb49163",
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
    json={
        "name": "Priya Sharma",
        "mobile_number": "+919876543210",
        "agent_id": "b1972188-038e-4605-916c-3926e9d7bde4",
        "number_pool_id": "c14cbdac-8928-4a19-8aef-df7f5eb49163",
    },
)
print(res.json())

A pool ID that doesn’t exist returns 400 “Number pool not found”; a pool with no numbers returns 400 “Number pool has no available numbers”. To find which pool a number is in, read number_pool_id from Get Workspace Numbers.

How a pool picks the number

Ringg rotates through the pool’s numbers in turn (round robin), skipping any number flagged as spam from the moment it is flagged. Each retry of a call picks again, so a contact isn’t tied to one number. If every number in the pool is flagged, Ringg still dials, from the number that was flagged longest ago.

Auto purchase

With Auto purchase on, the pool buys one replacement number from Ringg’s account when one of its numbers is flagged as spam, and adds it to the same pool. The replacement comes from the flagged number’s own country; the Replacement country you chose when creating the pool is used only when that country can’t be worked out or has no numbers for sale. You can turn the switch on or off later on the pool page. The flagged number stays in the pool, is skipped, and keeps its rental. The replacement is billed like any Ringg number you buy; the pool itself costs nothing. If your balance is too low, or the country needs international calling that your workspace doesn’t have, nothing is bought. Workspace admins get an email when a replacement is bought.

The pool list

Each pool card shows:

The pool name, a Default badge on the default pool, and an Active chip while a campaign is using it.
n Numbers, n Active and n Spam counts.
The numbers in the pool. Drag a number onto another card to move it.
Copy pool ID (shown on hover), for number_pool_id in the API.

Click a card to open the pool page.

Number Pools tab with four pool cards: Default pool with a Default badge, India Outbound with 1 Spam, Sales callbacks with an Active chip and locked numbers, and the new Renewals pool — Pool cards with counts and the Default and Active badges

The pool page

The pool page (/numbers/<pool ID>) shows the name, description, the Auto purchase switch, Add number and a delete button. Its table has ID, Country, Mobile number, Provider, Added on and Tags, plus a Spam chip on flagged numbers.

Renewals pool page with description Outbound campaigns, the Auto purchase switch on, Add number and delete buttons, and a table of two numbers with provider, added date and tags — The pool page

Add numbers: click Add number, tick numbers in Add numbers to pool, then click Add.
Remove a number: use the row’s remove button and confirm Remove. “The number stays in your workspace and can be added to another pool.”
Tags: edit a number’s tags from its row.

The default pool

Your workspace has one pool marked Default, which can’t be deleted. Numbers land in it in two cases: when you detach them from an inbound agent, and when their pool is deleted. New numbers don’t; add them to a pool yourself.

Restrictions while a campaign runs

While a campaign is using a pool, the pool shows Active and is frozen (“Campaign in progress — pool is frozen”):

Add number, remove and delete are disabled.
You can’t drag numbers into or out of it (“Locked — campaign running”).
The Auto purchase switch still works.

Delete a pool

Open the pool, click the delete button and confirm with Delete pool. The pool is archived and its numbers move to your default pool. This can’t be undone.

You see “Pool archived” with the number of numbers moved.

You can’t delete a pool while a campaign is using it.

Troubleshooting

All numbers are in use

The picker hides every number that can’t join a pool. Detach the number from its agent, wait for the campaign to end, or buy a number.

No purchased numbers

“Test numbers are for trial calls and can’t join a pool. Buy or import a number first.” See Buy or import a number.

I can't add or remove numbers

The pool is Active: a campaign is using it (restrictions). Wait for the campaign to end.

My pool is greyed out in the campaign form

The pool has no numbers. Add at least one number to it.

Next steps

Run a campaign

Start a campaign that dials from your pool.

Call from your backend

Place single calls with a pool by API.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Number pools

Before you start

Numbers in your workspace

Edit access to Numbers

Create a pool

Which numbers you can add

Use a pool in the dashboard

Use a pool with the API

How a pool picks the number

Auto purchase

The pool list

The pool page

The default pool

Restrictions while a campaign runs

Delete a pool

Troubleshooting

Next steps

Run a campaign

Call from your backend

​Before you start

Numbers in your workspace

Edit access to Numbers

​Create a pool

​Which numbers you can add

​Use a pool in the dashboard

​Use a pool with the API

​How a pool picks the number

​Auto purchase

​The pool list

​The pool page

​The default pool

​Restrictions while a campaign runs

​Delete a pool

​Troubleshooting

​Next steps

Run a campaign

Call from your backend

Before you start

Create a pool

Which numbers you can add

Use a pool in the dashboard

Use a pool with the API

How a pool picks the number

Auto purchase

The pool list

The pool page

The default pool

Restrictions while a campaign runs

Delete a pool

Troubleshooting

Next steps