v1

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

Phone Numbers

Assign Phone Number

Assigns or reassigns a phone number as a company or extension number.

Assign scenarios supported:

from Inventory to a company number;
from Inventory to an extension number.

Reassign scenarios supported:

from an extension to another extension;
from an extension to a company number;
from a company number to an extension.

patch/restapi/v2/accounts/{accountId}/phone-numbers/{phoneNumberId}

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)

phoneNumberIdstring required

Internal unique identifier of a phone number

Example:1162820004

Internal identifier of a phone number

Request body

type'VoiceFax' | 'VoiceOnly' | 'FaxOnly' nullable

Type of phone number

usageType'MainCompanyNumber' | 'CompanyNumber' | 'DirectNumber' | 'PhoneLine' required

Target usage type of phone number (only listed values are supported)

costCenterIdstring

Response

Successful response

idstring required

Internal unique identifier of a phone number

phoneNumberstring required

Phone number in e.164 format (with '+' prefix)

type'VoiceFax' | 'VoiceOnly' | 'FaxOnly' nullable

Type of phone number

tollType'Toll' | 'TollFree' required

Indicates if a number is toll or toll-free

Usage type of phone number

byocNumberboolean

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

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

Example response

{
  "id": "1162820004",
  "phoneNumber": "+16501234567",
  "tollType": "Toll",
  "extension": {
    "id": "1234567",
    "extensionNumber": "205"
  }
}