Phone numbers and caller ID

A campaign shows the lead a phone number when it calls. That number is the caller ID, and it is yours: bought through the platform or brought from your own Twilio account. Local numbers get picked up more than unfamiliar ones, so which number a campaign dials from is a real decision, not plumbing.

​

The pool and the campaign

Your agency has a pool: every number it owns, across every project. A campaign carries fromNumbers, the subset of the pool it dials from. One number can serve several campaigns. Each number in the pool reads as:

​

Getting a number

Two paths, same result.

• Buy one. Search the inventory, then buy. Search takes place (a city or state), areaCode, countryCode (US or CA), contains for a digit pattern, and tollFree. When nothing matches, the response says why: unknown_place, no_inventory or out_of_coverage, with the coverage list and suggested alternatives. Buying is a paid action and the number lands in the pool.
• Bring your own. Connect your Twilio account and attach the numbers you already own. They are never billed by the platform. See Connect your Twilio.

Agent-scoped endpoints under the agent do the same search, buy and attach, and assign the result to that agent’s campaign in one move. Use them when you are setting up one agent. Use the pool endpoints when you manage numbers across the agency.

​

Moving numbers around

• Assign adds a number to a campaign’s fromNumbers. It does not remove it from any other campaign.
• Unassign takes a number off one campaign. The number stays in the pool.
• Move takes a number off one campaign and puts it on another in one step, so there is no moment where neither campaign has it.
• Release hands a platform-bought number back to the carrier and stops the monthly charge. For a number you own, the same call removes it from the pool and leaves your Twilio account untouched.

​

Boundaries

• A live campaign needs at least one number in fromNumbers.
• Numbers travel in E.164 with a leading +. In a URL path the + must be encoded as %2B, so +14155550100 becomes %2B14155550100.
• Inbound campaigns answer on their numbers. Outbound campaigns dial from them. The number does not know the difference; the campaign does.
• Buying spends money. Releasing cannot be undone. Both are deliberate acts and neither is safe to retry without reading the pool first.

​

In the API

Pool, across the agency:

• List phone numbers, Search phone numbers and Buy phone number
• Assign phone number, Unassign phone number and Move phone number
• Release phone number

Scoped to one agent:

• List agent phone numbers, Search agent phone numbers, Buy agent phone number and Attach agent phone number
• Every field above is defined in the Glossary

​

Related

• Phone numbers on a campaign covers the dashboard side and local presence.
• Go live lists a number as one of the three things a campaign needs.