Skip to main content
POST
JavaScript
POST /v2/list-phone-numbers is the recommended way to list phone numbers. It takes the same limit, sort_order, and pagination_key query parameters as GET /v2/list-phone-numbers and returns the same response. It also accepts optional filter_criteria in the request body.GET /v2/list-phone-numbers still works, and Retell isn’t removing it soon. Don’t use it for new integrations. In the SDKs, phoneNumber.list() (Python: phone_number.list()) calls the GET, and phoneNumber.search() (Python: phone_number.search()) calls the POST.

Authorizations

Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Query Parameters

limit
integer
default:50

Maximum number of items to return.

Required range: x <= 1000
sort_order
enum<string>
default:descending

Sort order for results.

Available options:
ascending,
descending
pagination_key
string

Pagination key for fetching the next page.

Body

application/json
filter_criteria
object

Filters for listing phone numbers. All provided filters are connected with AND.

Response

Successfully retrieved phone numbers.

has_more
boolean
required

Whether more results are available.

items
object[]
required
pagination_key
string

Pagination key for the next page.