Skip to main content
GET
cURL

Authorizations

Authorization
string
header
required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Query Parameters

agencyTag
string

Ignored. Your key is always scoped to its own agency, and that agency's pool is what comes back.

Minimum string length: 1
limit
integer

How many numbers per page, 1 to 200. Send it to page the list; the response then carries total, nextCursor and totals. Leave it out to get every number at once.

Required range: 1 <= x <= 200
q
string

Search. Two or more digits match the number itself; anything else matches the name of a campaign the number is on, its client or its agent, ignoring case. Only used with limit.

Maximum string length: 200
source
enum<string>

Only numbers billed to the agency balance (platform) or only numbers imported from the agency's own Twilio account (own-twilio). Only used with limit.

Available options:
platform,
own-twilio
cursor
string

The nextCursor from the previous page, unchanged. Send the same limit, q and source with it. Only used with limit.

Maximum string length: 4000
locationId
string

The sub-account of the campaign you are choosing numbers for. Send it with engine. Each number then carries unavailableReason.

Required string length: 1 - 200
engine
string

The kind of that campaign's agent: gpt_live for a TFU Live agent, anything else for a Standard agent. Send it with locationId.

Required string length: 1 - 40
campaignId
string

The campaign you are editing, if it exists already. Its own numbers do not count against it.

Required string length: 1 - 200

Response

Agency phone number pool.

success
boolean
required
phoneNumbers
object[]
required
needsAgency
boolean
required

Whether the request needs an agency context before results can be returned. Always false for an API key, which always carries an agency.

Example:

false

total
integer

Paged requests only: how many numbers match q and source, across every page.

Required range: x >= 0
Example:

1

nextCursor
string | null

Paged requests only: pass it as cursor for the next page. Null on the last page.

Example:

null

totals
object

Paged requests only: the whole agency's numbers by who bills them, whatever q and source are.