v1

latestOpenAPI 3.0.3RingCentral API License Agreement2026-08-064871,2921.5 MB

Phone Numbers

List Account Phone Numbers

Returns the list of phone numbers assigned to RingCentral customer account. Both company-level and extension-level numbers are returned. Conferencing numbers, hot desk and ELIN numbers are not returned.

get/restapi/v2/accounts/{accountId}/phone-numbers

Path parameters

accountIdstring required

Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)

Query parameters

pageinteger

The result set page number (1-indexed) to return

perPageinteger

The number of items per page. If provided value in the request is greater than a maximum, the maximum value is applied

typePhoneNumberType[]

Types of phone numbers to be returned

usageTypePhoneNumberUsageType[]

Usage type(s) of phone numbers to be returned

status'Normal' | 'Pending' | 'PortedIn' | 'Temporary' | 'Unknown'

Status of a phone number. If the value is 'Normal', the phone number is ready to be used. Otherwise, it is an external number not yet ported to RingCentral

Status of the phone number(s) to be returned

tollType'Toll' | 'TollFree'

Indicates if a number is toll or toll-free

Example:Toll

Toll type of phone numbers to return

extensionStatus'Enabled' | 'Disabled' | 'Frozen' | 'NotActivated' | 'Unassigned'

Extension status

Statuses of extensions to return phone numbers for

byocNumberboolean

The parameter reflects whether this number is BYOC or not

phoneNumberstring

Phone number in e.164 format to be searched for. Parameter value can include wildcards (e.g. "+165012345**") or be an exact number "+16501234500" - single number is searched in that case. Make sure you escape the "+" in the URL as "%2B"

Response

Successful response

Example response

{
  "records": [
    {
      "id": "1162820004",
      "phoneNumber": "+16501234567",
      "tollType": "Toll",
      "extension": {
        "id": "1234567",
        "extensionNumber": "205"
      }
    }
  ],
  "paging": {
    "perPage": 50,
    "page": 5,
    "pageEnd": 5,
    "totalPages": 25,
    "totalElements": 25
  }
}