Skip to main content
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 numbers from the pool it dials from. Any campaign of your agency can dial from any of its numbers, in any sub-account. Campaigns that share a number must all be TFU Live campaigns, or all other campaigns. A number nobody uses waits in the pool. Each number in the pool reads as: To pick numbers for one campaign, list the pool with its locationId and engine (gpt_live for a TFU Live agent, anything else for a Standard agent). Add campaignId when you edit a campaign that exists. Each number then carries unavailableReason, by the same rule that saving the campaign refuses with:
  • used_by_tfu_live: a TFU Live agent uses it, and the campaign has a Standard agent. A number’s calls go to one voice system.
  • used_by_standard: a Standard agent uses it, and the campaign has a TFU Live agent.
  • registered_elsewhere: it is registered to another business in the Trust Center.
  • other_voice_account: a Standard agent on another voice account uses it.

​
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 or no_inventory, with the coverage list and suggested alternatives. A country we don’t sell in comes back as unknown_place; out_of_coverage is reserved and not sent yet. Each number found carries smsCapable, Twilio’s own flag for whether it can send texts (null when Twilio did not say). Buying is a paid action and the number lands in the pool. A campaign is optional: name one and the number goes straight onto it, or leave it out and assign the number later. It is billed from purchase either way.
  • 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. The number stays on its other campaigns. These get 409:
    • a number another agency uses (NumberInAnotherAgency);
    • a number used by the other kind of agent, TFU Live or Standard (NumberOnTfuLiveCampaign, NumberOnNonTfuLiveCampaign). A TFU Live number no campaign uses yet still counts as TFU Live;
    • a number registered to another business in the Trust Center, for texts or caller ID, whether or not a campaign uses it (NumberRegisteredToOneBusiness). A draft registration doesn’t count;
    • a number a Standard agent on another voice account uses (NumberCannotBeShared).
  • Unassign takes a number off one campaign. The number stays in the pool, and a bought number keeps billing until you release it. A live campaign’s only number can’t be unassigned. Send pauseCampaigns=true to pause that campaign first in the same call.
  • 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. Send pauseCampaigns: true to pause the campaigns a move needs paused first.
  • 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. One imported from Twilio also gets its previous voice settings back and stays in your Twilio account.
Release is irreversible. The number goes back to general inventory and you cannot get it back. It needs the separate phone_numbers:release scope, and the response says released or releaseFailed per number. A number that is a live campaign’s only number can’t be released. Pause that campaign or give it another number first, or send pauseCampaigns=true to pause it in the same call. A live campaign with other numbers just loses this one.

​
Answers incoming calls

Each number has at most one campaign that answers its incoming calls. The dashboard shows it as Answers inbound calls of new leads. Change it in the number’s details on the Phone Numbers page. Any TFU Live campaign can answer calls. So can an agent of the Inbound type. Outbound and confirmation agents can’t. Who picks up:
  • A lead a campaign called reaches that campaign when they call back, if it is switched on. That can be a campaign of any sub-account using the number. On a TFU Live number, it is the campaign that last called them from this number.
  • A call the lead made to you never counts as being called.
  • If the campaign that called them is paused or deleted, the answering campaign takes the call. It must be in the same sub-account and switched on. Otherwise the call is declined. A lead never goes to another sub-account.
  • Anyone else reaches only the answering campaign. With no answering campaign, the call is declined.
  • If the answering campaign is paused or has no agent, the call is declined. The same happens when its sub-account is paused or its calls are stopped.
  • No other campaign answers in its place, and no receptionist on another number. An outbound campaign only takes calls from leads it called.
  • On a TFU Live number, a paused answering campaign answers as a test call while nothing on the number is live.
When you add a number to a campaign:
  • If nobody answers the number, this campaign answers it, if it can answer calls.
  • If another campaign answers it, in any sub-account, that campaign keeps it. The builders ask which numbers this agent should answer. Nothing is ticked by default.
  • The API never asks. To take a number over, list it in answerCalls. Assign phone number, Move phone number and Update campaign take this list of up to 100 E.164 numbers.
  • A listed number that is not on the campaign after the save gets 400 AnswerCallsNotOnCampaign. A campaign that can’t answer calls gets 422 CampaignCannotAnswerCalls.
  • A move works the same way. The campaign the number leaves does not count.
When the answering campaign leaves a number, the next campaign on it that can answer calls takes over, oldest first. This happens when you take the number off, move it or delete the campaign. With none, nobody answers. Releasing a number takes it off every campaign.

​
Boundaries

  • Campaigns of one agency can share a number across its sub-accounts. They must all be TFU Live campaigns, or all other campaigns. A cloned campaign starts with no numbers.
  • A number registered to one client business stays with that business’s campaigns, even when no campaign uses it.
  • A number has at most one answering campaign in your agency. Only a TFU Live campaign or an Inbound agent can be it.
  • 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.
  • Outbound and confirmation agents dial from their numbers. They can’t be a number’s answering campaign.
  • 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: For one campaign the same endpoints apply: campaigns[] on List phone numbers says which campaign a number is on, Search and Buy take an optional campaignId, and Assign puts a pool number, including one you own in Twilio, on a campaign. List phone numbers returns each number’s answeredBy and answeringNow, and canAnswer on each of its campaigns. Assign phone number, Move phone number and Update campaign take answerCalls.
  • Every field above is defined in the Glossary