List phone numbers
List the agency phone number pool and the campaigns currently using each caller ID. Allowed customer role: agency_admin.
Your key is scoped to its own agency, so no parameter is needed. To page a large pool, send limit, then pass each response’s nextCursor back as cursor until it is null; q and source narrow the pages.
To pick numbers for one campaign, send locationId and engine (and campaignId when editing one). Each number then says why that campaign can’t use it (unavailableReason), by the rule that saving the campaign refuses with.
Required API key scope: phone_numbers:read.
Authorizations
Send your API key as Authorization: Bearer YOUR_API_KEY.
Query Parameters
Ignored. Your key is always scoped to its own agency, and that agency's pool is what comes back.
1How 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.
1 <= x <= 200Search. 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.
200Only numbers billed to the agency balance (platform) or only numbers imported from the agency's own Twilio account (own-twilio). Only used with limit.
platform, own-twilio The nextCursor from the previous page, unchanged. Send the same limit, q and source with it. Only used with limit.
4000The sub-account of the campaign you are choosing numbers for. Send it with engine. Each number then carries unavailableReason.
1 - 200The kind of that campaign's agent: gpt_live for a TFU Live agent, anything else for a Standard agent. Send it with locationId.
1 - 40The campaign you are editing, if it exists already. Its own numbers do not count against it.
1 - 200Response
Agency phone number pool.
Whether the request needs an agency context before results can be returned. Always false for an API key, which always carries an agency.
false
Paged requests only: how many numbers match q and source, across every page.
x >= 01
Paged requests only: pass it as cursor for the next page. Null on the last page.
null
Paged requests only: the whole agency's numbers by who bills them, whatever q and source are.
