Skip to main content

How to disconnect phone numbers

To remove a number from your account, disconnect it using the /disconnects endpoint.

Create a Disconnect Order

To create a disconnect order, you must make a POST request to our /disconnects API endpoint.

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/disconnects

Example

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/disconnects HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<?xml version="1.0"?>
<DisconnectTelephoneNumberOrder>
<CustomerOrderId>My OrderId</CustomerOrderId>
<DisconnectTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5405514342</TelephoneNumber>
<TelephoneNumber>7034343704</TelephoneNumber>
</TelephoneNumberList>
</DisconnectTelephoneNumberOrderType>
</DisconnectTelephoneNumberOrder>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/disconnects/df2gc2e2-653d-466c-945d-8f292f09ce55

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DisconnectTelephoneNumberOrderResponse>
<orderRequest>
<OrderCreateDate>2018-01-23T21:00:23.802Z</OrderCreateDate>
<id>df2gc2e2-653d-466c-945d-8f292f09ce55</id>
<DisconnectTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5405514342</TelephoneNumber>
<TelephoneNumber>7034343704</TelephoneNumber>
</TelephoneNumberList>
<DisconnectMode>normal</DisconnectMode>
</DisconnectTelephoneNumberOrderType>
</orderRequest>
<OrderStatus>RECEIVED</OrderStatus>
</DisconnectTelephoneNumberOrderResponse>

Checking Disconnect Order Status

Disconnects are asynchronous which means the orders are processed and the order status is updated at a later time. As times can vary, Bandwidth recommends configuring your account with a subscription instead of polling the order resource for <OrderStatus>. Please follow the How to setup Notification Webhook guide. If you want to poll, you can still use a GET /disconnects/{disconnectId} request.

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/disconnects/{ disconnectId }

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/disconnects/df2gc2e2-653d-466c-945d-8f292f09ce55 HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DisconnectTelephoneNumberOrderResponse>
<DisconnectedTelephoneNumberList>
<TelephoneNumber>5405514342</TelephoneNumber>
<TelephoneNumber>7034343704</TelephoneNumber>
</DisconnectedTelephoneNumberList>
<ErrorList/>
<orderRequest>
<OrderCreateDate>2015-01-20T21:05:58.026Z</OrderCreateDate>
<id>df2gc2e2-653d-466c-945d-8f292f09ce55</id>
<DisconnectTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>7034343704</TelephoneNumber>
<TelephoneNumber>5405514342</TelephoneNumber>
</TelephoneNumberList>
<DisconnectMode>normal</DisconnectMode>
</DisconnectTelephoneNumberOrderType>
</orderRequest>
<OrderStatus>COMPLETE</OrderStatus>
</DisconnectTelephoneNumberOrderResponse>

Once a number is disconnected, it goes into AGING. The number can be reclaimed/reordered by the same account that disconnected it within the AGING duration. Once the AGING duration expires, the number is no longer reserved for that customer.

Click here to see the aging periods list based on the country and phone number type.
country_namecountrytn_typeaging_days
ArgentinaARGGEOGRAPHIC60
ArgentinaARGNATIONAL60
ArgentinaARGMOBILE60
ArgentinaARGTOLL_FREE60
ArgentinaARGSHARED_COST60
AustraliaAUSGEOGRAPHIC180
AustraliaAUSNATIONAL180
AustraliaAUSMOBILE180
AustraliaAUSTOLL_FREE180
AustraliaAUSSHARED_COST180
AustriaAUTGEOGRAPHIC90
AustriaAUTNATIONAL90
AustriaAUTMOBILE90
AustriaAUTTOLL_FREE90
AustriaAUTSHARED_COST90
BahrainBHRGEOGRAPHIC60
BahrainBHRNATIONAL60
BahrainBHRMOBILE60
BahrainBHRTOLL_FREE60
BahrainBHRSHARED_COST60
BelgiumBELGEOGRAPHIC90
BelgiumBELNATIONAL90
BelgiumBELMOBILE90
BelgiumBELTOLL_FREE90
BelgiumBELSHARED_COST90
BrazilBRAGEOGRAPHIC60
BrazilBRANATIONAL60
BrazilBRAMOBILE60
BrazilBRATOLL_FREE60
BrazilBRASHARED_COST60
BulgariaBGRGEOGRAPHIC90
BulgariaBGRNATIONAL90
BulgariaBGRMOBILE90
BulgariaBGRTOLL_FREE90
BulgariaBGRSHARED_COST90
CanadaCANGEOGRAPHIC60
CanadaCANNATIONAL60
CanadaCANMOBILE60
CanadaCANTOLL_FREE60
CanadaCANSHARED_COST60
ChileCHLGEOGRAPHIC60
ChileCHLNATIONAL60
ChileCHLMOBILE60
ChileCHLTOLL_FREE60
ChileCHLSHARED_COST60
ColombiaCOLGEOGRAPHIC60
ColombiaCOLNATIONAL60
ColombiaCOLMOBILE60
ColombiaCOLTOLL_FREE60
ColombiaCOLSHARED_COST60
CroatiaHRVGEOGRAPHIC90
CroatiaHRVNATIONAL90
CroatiaHRVMOBILE90
CroatiaHRVTOLL_FREE90
CroatiaHRVSHARED_COST90
CyprusCYPGEOGRAPHIC60
CyprusCYPNATIONAL60
CyprusCYPMOBILE60
CyprusCYPTOLL_FREE60
CyprusCYPSHARED_COST60
Czech RepublicCZEGEOGRAPHIC90
Czech RepublicCZENATIONAL90
Czech RepublicCZEMOBILE90
Czech RepublicCZETOLL_FREE90
Czech RepublicCZESHARED_COST90
DenmarkDNKGEOGRAPHIC90
DenmarkDNKNATIONAL90
DenmarkDNKMOBILE90
DenmarkDNKTOLL_FREE90
DenmarkDNKSHARED_COST90
Dominican RepublicDOMGEOGRAPHIC60
Dominican RepublicDOMNATIONAL60
Dominican RepublicDOMMOBILE60
Dominican RepublicDOMTOLL_FREE60
Dominican RepublicDOMSHARED_COST60
El SalvadorSLVGEOGRAPHIC60
El SalvadorSLVNATIONAL60
El SalvadorSLVMOBILE60
El SalvadorSLVTOLL_FREE60
El SalvadorSLVSHARED_COST60
EstoniaESTGEOGRAPHIC90
EstoniaESTNATIONAL90
EstoniaESTMOBILE90
EstoniaESTTOLL_FREE90
EstoniaESTSHARED_COST90
FinlandFINGEOGRAPHIC60
FinlandFINNATIONAL60
FinlandFINMOBILE60
FinlandFINTOLL_FREE60
FinlandFINSHARED_COST60
FranceFRAGEOGRAPHIC90
FranceFRANATIONAL90
FranceFRAMOBILE90
FranceFRATOLL_FREE90
FranceFRASHARED_COST90
GeorgiaGEOGEOGRAPHIC60
GeorgiaGEONATIONAL60
GeorgiaGEOMOBILE60
GeorgiaGEOTOLL_FREE60
GeorgiaGEOSHARED_COST60
GermanyDEUGEOGRAPHIC180
GermanyDEUNATIONAL180
GermanyDEUMOBILE180
GermanyDEUTOLL_FREE180
GermanyDEUSHARED_COST180
GreeceGRCGEOGRAPHIC90
GreeceGRCNATIONAL90
GreeceGRCMOBILE90
GreeceGRCTOLL_FREE90
GreeceGRCSHARED_COST90
Hong KongHKGGEOGRAPHIC90
Hong KongHKGNATIONAL90
Hong KongHKGMOBILE90
Hong KongHKGTOLL_FREE90
Hong KongHKGSHARED_COST90
HungaryHUNGEOGRAPHIC90
HungaryHUNNATIONAL90
HungaryHUNMOBILE90
HungaryHUNTOLL_FREE90
HungaryHUNSHARED_COST90
IndiaINDGEOGRAPHIC60
IndiaINDNATIONAL60
IndiaINDMOBILE60
IndiaINDTOLL_FREE60
IndiaINDSHARED_COST60
IrelandIRLGEOGRAPHIC90
IrelandIRLNATIONAL90
IrelandIRLMOBILE90
IrelandIRLTOLL_FREE90
IrelandIRLSHARED_COST90
IsraelISRGEOGRAPHIC60
IsraelISRNATIONAL60
IsraelISRMOBILE60
IsraelISRTOLL_FREE60
IsraelISRSHARED_COST60
ItalyITAGEOGRAPHIC90
ItalyITANATIONAL90
ItalyITAMOBILE90
ItalyITATOLL_FREE90
ItalyITASHARED_COST90
JapanJPNGEOGRAPHIC60
JapanJPNNATIONAL60
JapanJPNMOBILE60
JapanJPNTOLL_FREE60
JapanJPNSHARED_COST60
LatviaLVAGEOGRAPHIC90
LatviaLVANATIONAL90
LatviaLVAMOBILE90
LatviaLVATOLL_FREE90
LatviaLVASHARED_COST90
LithuaniaLTUGEOGRAPHIC90
LithuaniaLTUNATIONAL90
LithuaniaLTUMOBILE90
LithuaniaLTUTOLL_FREE90
LithuaniaLTUSHARED_COST90
LuxembourgLUXGEOGRAPHIC90
LuxembourgLUXNATIONAL90
LuxembourgLUXMOBILE90
LuxembourgLUXTOLL_FREE90
LuxembourgLUXSHARED_COST90
MalaysiaMYSGEOGRAPHIC180
MalaysiaMYSNATIONAL180
MalaysiaMYSMOBILE180
MalaysiaMYSTOLL_FREE180
MalaysiaMYSSHARED_COST180
MaltaMLTGEOGRAPHIC60
MaltaMLTNATIONAL60
MaltaMLTMOBILE60
MaltaMLTTOLL_FREE60
MaltaMLTSHARED_COST60
MexicoMEXGEOGRAPHIC60
MexicoMEXNATIONAL60
MexicoMEXMOBILE60
MexicoMEXTOLL_FREE60
MexicoMEXSHARED_COST60
NetherlandsNLDGEOGRAPHIC90
NetherlandsNLDNATIONAL90
NetherlandsNLDMOBILE90
NetherlandsNLDTOLL_FREE90
NetherlandsNLDSHARED_COST90
New ZealandNZLGEOGRAPHIC90
New ZealandNZLNATIONAL90
New ZealandNZLMOBILE90
New ZealandNZLTOLL_FREE90
New ZealandNZLSHARED_COST90
NorwayNORGEOGRAPHIC90
NorwayNORNATIONAL90
NorwayNORMOBILE90
NorwayNORTOLL_FREE90
NorwayNORSHARED_COST90
PanamaPANGEOGRAPHIC60
PanamaPANNATIONAL60
PanamaPANMOBILE60
PanamaPANTOLL_FREE60
PanamaPANSHARED_COST60
PeruPERGEOGRAPHIC60
PeruPERNATIONAL60
PeruPERMOBILE60
PeruPERTOLL_FREE60
PeruPERSHARED_COST60
PhilippinesPHLGEOGRAPHIC60
PhilippinesPHLNATIONAL60
PhilippinesPHLMOBILE60
PhilippinesPHLTOLL_FREE60
PhilippinesPHLSHARED_COST60
PolandPOLGEOGRAPHIC90
PolandPOLNATIONAL90
PolandPOLMOBILE90
PolandPOLTOLL_FREE90
PolandPOLSHARED_COST90
PortugalPRTGEOGRAPHIC90
PortugalPRTNATIONAL90
PortugalPRTMOBILE90
PortugalPRTTOLL_FREE90
PortugalPRTSHARED_COST90
Puerto RicoPRIGEOGRAPHIC60
Puerto RicoPRINATIONAL60
Puerto RicoPRIMOBILE60
Puerto RicoPRITOLL_FREE60
Puerto RicoPRISHARED_COST60
RomaniaROUGEOGRAPHIC60
RomaniaROUNATIONAL60
RomaniaROUMOBILE60
RomaniaROUTOLL_FREE60
RomaniaROUSHARED_COST60
SingaporeSGPGEOGRAPHIC90
SingaporeSGPNATIONAL90
SingaporeSGPMOBILE90
SingaporeSGPTOLL_FREE90
SingaporeSGPSHARED_COST90
SlovakiaSVKGEOGRAPHIC60
SlovakiaSVKNATIONAL60
SlovakiaSVKMOBILE60
SlovakiaSVKTOLL_FREE60
SlovakiaSVKSHARED_COST60
SloveniaSVNGEOGRAPHIC90
SloveniaSVNNATIONAL90
SloveniaSVNMOBILE90
SloveniaSVNTOLL_FREE90
SloveniaSVNSHARED_COST90
South AfricaZAFGEOGRAPHIC60
South AfricaZAFNATIONAL60
South AfricaZAFMOBILE60
South AfricaZAFTOLL_FREE60
South AfricaZAFSHARED_COST60
South KoreaKORGEOGRAPHIC60
South KoreaKORNATIONAL60
South KoreaKORMOBILE60
South KoreaKORTOLL_FREE60
South KoreaKORSHARED_COST60
SpainESPGEOGRAPHIC90
SpainESPNATIONAL90
SpainESPMOBILE90
SpainESPTOLL_FREE90
SpainESPSHARED_COST90
SwedenSWEGEOGRAPHIC90
SwedenSWENATIONAL90
SwedenSWEMOBILE90
SwedenSWETOLL_FREE90
SwedenSWESHARED_COST90
SwitzerlandCHEGEOGRAPHIC90
SwitzerlandCHENATIONAL90
SwitzerlandCHEMOBILE90
SwitzerlandCHETOLL_FREE90
SwitzerlandCHESHARED_COST90
TurkeyTURGEOGRAPHIC90
TurkeyTURNATIONAL90
TurkeyTURMOBILE90
TurkeyTURTOLL_FREE90
TurkeyTURSHARED_COST90
United Arab EmiratesAREGEOGRAPHIC60
United Arab EmiratesARENATIONAL60
United Arab EmiratesAREMOBILE60
United Arab EmiratesARETOLL_FREE60
United Arab EmiratesARESHARED_COST60
United KingdomGBRGEOGRAPHIC90
United KingdomGBRNATIONAL90
United KingdomGBRMOBILE90
United KingdomGBRTOLL_FREE90
United KingdomGBRSHARED_COST90
United StatesUSAGEOGRAPHIC60
United StatesUSANATIONAL60
United StatesUSAMOBILE60
United StatesUSATOLL_FREE60
United StatesUSASHARED_COST60
VenezuelaVENGEOGRAPHIC60
VenezuelaVENNATIONAL60
VenezuelaVENMOBILE60
VenezuelaVENTOLL_FREE60
VenezuelaVENSHARED_COST60
Virgin Islands (u.s.)VIRGEOGRAPHIC60
Virgin Islands (u.s.)VIRNATIONAL60
Virgin Islands (u.s.)VIRMOBILE60
Virgin Islands (u.s.)VIRTOLL_FREE60
Virgin Islands (u.s.)VIRSHARED_COST60

Where to next?

Now that you have learned how to disconnect numbers, check out some of the other available actions in our guides: