Sign in

v1

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

Replace Phone Number

Replaces (swaps) phone numbers from Inventory with the main, company, direct or company fax numbers. This method is used to replace temporary numbers when the porting process is complete.

post/restapi/v2/accounts/{accountId}/phone-numbers/{phoneNumberId}/replace

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

targetPhoneNumberIdstring

Internal unique identifier of a phone number

Example request

{
  "targetPhoneNumberId": "1162820004"
}

Response

Success

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

usageType'MainCompanyNumber' | 'DirectNumber' | 'Inventory' | 'InventoryPartnerBusinessMobileNumber' | 'PartnerBusinessMobileNumber' | 'AdditionalCompanyNumber' | 'CompanyNumber' | 'PhoneLine' | 'CompanyFaxNumber' | 'ForwardedNumber' | 'ForwardedCompanyNumber' | 'ContactCenterNumber' | 'ConferencingNumber' | 'MeetingsNumber' | 'BusinessMobileNumber' | 'ELIN' required

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"
  }
}