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. There is a limit of 5000 numbers per disconnect order.

Request URL

POSThttps://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.

GEThttps://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_name	country	tn_type	aging_days
Argentina	ARG	GEOGRAPHIC	60
Argentina	ARG	NATIONAL	60
Argentina	ARG	MOBILE	60
Argentina	ARG	TOLL_FREE	60
Argentina	ARG	SHARED_COST	60
Australia	AUS	GEOGRAPHIC	180
Australia	AUS	NATIONAL	180
Australia	AUS	MOBILE	180
Australia	AUS	TOLL_FREE	180
Australia	AUS	SHARED_COST	180
Austria	AUT	GEOGRAPHIC	90
Austria	AUT	NATIONAL	90
Austria	AUT	MOBILE	90
Austria	AUT	TOLL_FREE	90
Austria	AUT	SHARED_COST	90
Bahrain	BHR	GEOGRAPHIC	60
Bahrain	BHR	NATIONAL	60
Bahrain	BHR	MOBILE	60
Bahrain	BHR	TOLL_FREE	60
Bahrain	BHR	SHARED_COST	60
Belgium	BEL	GEOGRAPHIC	90
Belgium	BEL	NATIONAL	90
Belgium	BEL	MOBILE	90
Belgium	BEL	TOLL_FREE	90
Belgium	BEL	SHARED_COST	90
Brazil	BRA	GEOGRAPHIC	60
Brazil	BRA	NATIONAL	60
Brazil	BRA	MOBILE	60
Brazil	BRA	TOLL_FREE	60
Brazil	BRA	SHARED_COST	60
Bulgaria	BGR	GEOGRAPHIC	90
Bulgaria	BGR	NATIONAL	90
Bulgaria	BGR	MOBILE	90
Bulgaria	BGR	TOLL_FREE	90
Bulgaria	BGR	SHARED_COST	90
Canada	CAN	GEOGRAPHIC	60
Canada	CAN	NATIONAL	60
Canada	CAN	MOBILE	60
Canada	CAN	TOLL_FREE	60
Canada	CAN	SHARED_COST	60
Chile	CHL	GEOGRAPHIC	60
Chile	CHL	NATIONAL	60
Chile	CHL	MOBILE	60
Chile	CHL	TOLL_FREE	60
Chile	CHL	SHARED_COST	60
Colombia	COL	GEOGRAPHIC	60
Colombia	COL	NATIONAL	60
Colombia	COL	MOBILE	60
Colombia	COL	TOLL_FREE	60
Colombia	COL	SHARED_COST	60
Croatia	HRV	GEOGRAPHIC	90
Croatia	HRV	NATIONAL	90
Croatia	HRV	MOBILE	90
Croatia	HRV	TOLL_FREE	90
Croatia	HRV	SHARED_COST	90
Cyprus	CYP	GEOGRAPHIC	60
Cyprus	CYP	NATIONAL	60
Cyprus	CYP	MOBILE	60
Cyprus	CYP	TOLL_FREE	60
Cyprus	CYP	SHARED_COST	60
Czech Republic	CZE	GEOGRAPHIC	90
Czech Republic	CZE	NATIONAL	90
Czech Republic	CZE	MOBILE	90
Czech Republic	CZE	TOLL_FREE	90
Czech Republic	CZE	SHARED_COST	90
Denmark	DNK	GEOGRAPHIC	90
Denmark	DNK	NATIONAL	90
Denmark	DNK	MOBILE	90
Denmark	DNK	TOLL_FREE	90
Denmark	DNK	SHARED_COST	90
Dominican Republic	DOM	GEOGRAPHIC	60
Dominican Republic	DOM	NATIONAL	60
Dominican Republic	DOM	MOBILE	60
Dominican Republic	DOM	TOLL_FREE	60
Dominican Republic	DOM	SHARED_COST	60
El Salvador	SLV	GEOGRAPHIC	60
El Salvador	SLV	NATIONAL	60
El Salvador	SLV	MOBILE	60
El Salvador	SLV	TOLL_FREE	60
El Salvador	SLV	SHARED_COST	60
Estonia	EST	GEOGRAPHIC	90
Estonia	EST	NATIONAL	90
Estonia	EST	MOBILE	90
Estonia	EST	TOLL_FREE	90
Estonia	EST	SHARED_COST	90
Finland	FIN	GEOGRAPHIC	60
Finland	FIN	NATIONAL	60
Finland	FIN	MOBILE	60
Finland	FIN	TOLL_FREE	60
Finland	FIN	SHARED_COST	60
France	FRA	GEOGRAPHIC	90
France	FRA	NATIONAL	90
France	FRA	MOBILE	90
France	FRA	TOLL_FREE	90
France	FRA	SHARED_COST	90
Georgia	GEO	GEOGRAPHIC	60
Georgia	GEO	NATIONAL	60
Georgia	GEO	MOBILE	60
Georgia	GEO	TOLL_FREE	60
Georgia	GEO	SHARED_COST	60
Germany	DEU	GEOGRAPHIC	180
Germany	DEU	NATIONAL	180
Germany	DEU	MOBILE	180
Germany	DEU	TOLL_FREE	180
Germany	DEU	SHARED_COST	180
Greece	GRC	GEOGRAPHIC	90
Greece	GRC	NATIONAL	90
Greece	GRC	MOBILE	90
Greece	GRC	TOLL_FREE	90
Greece	GRC	SHARED_COST	90
Hong Kong	HKG	GEOGRAPHIC	90
Hong Kong	HKG	NATIONAL	90
Hong Kong	HKG	MOBILE	90
Hong Kong	HKG	TOLL_FREE	90
Hong Kong	HKG	SHARED_COST	90
Hungary	HUN	GEOGRAPHIC	90
Hungary	HUN	NATIONAL	90
Hungary	HUN	MOBILE	90
Hungary	HUN	TOLL_FREE	90
Hungary	HUN	SHARED_COST	90
India	IND	GEOGRAPHIC	60
India	IND	NATIONAL	60
India	IND	MOBILE	60
India	IND	TOLL_FREE	60
India	IND	SHARED_COST	60
Ireland	IRL	GEOGRAPHIC	90
Ireland	IRL	NATIONAL	90
Ireland	IRL	MOBILE	90
Ireland	IRL	TOLL_FREE	90
Ireland	IRL	SHARED_COST	90
Israel	ISR	GEOGRAPHIC	60
Israel	ISR	NATIONAL	60
Israel	ISR	MOBILE	60
Israel	ISR	TOLL_FREE	60
Israel	ISR	SHARED_COST	60
Italy	ITA	GEOGRAPHIC	90
Italy	ITA	NATIONAL	90
Italy	ITA	MOBILE	90
Italy	ITA	TOLL_FREE	90
Italy	ITA	SHARED_COST	90
Japan	JPN	GEOGRAPHIC	60
Japan	JPN	NATIONAL	60
Japan	JPN	MOBILE	60
Japan	JPN	TOLL_FREE	60
Japan	JPN	SHARED_COST	60
Latvia	LVA	GEOGRAPHIC	90
Latvia	LVA	NATIONAL	90
Latvia	LVA	MOBILE	90
Latvia	LVA	TOLL_FREE	90
Latvia	LVA	SHARED_COST	90
Lithuania	LTU	GEOGRAPHIC	90
Lithuania	LTU	NATIONAL	90
Lithuania	LTU	MOBILE	90
Lithuania	LTU	TOLL_FREE	90
Lithuania	LTU	SHARED_COST	90
Luxembourg	LUX	GEOGRAPHIC	90
Luxembourg	LUX	NATIONAL	90
Luxembourg	LUX	MOBILE	90
Luxembourg	LUX	TOLL_FREE	90
Luxembourg	LUX	SHARED_COST	90
Malaysia	MYS	GEOGRAPHIC	180
Malaysia	MYS	NATIONAL	180
Malaysia	MYS	MOBILE	180
Malaysia	MYS	TOLL_FREE	180
Malaysia	MYS	SHARED_COST	180
Malta	MLT	GEOGRAPHIC	60
Malta	MLT	NATIONAL	60
Malta	MLT	MOBILE	60
Malta	MLT	TOLL_FREE	60
Malta	MLT	SHARED_COST	60
Mexico	MEX	GEOGRAPHIC	60
Mexico	MEX	NATIONAL	60
Mexico	MEX	MOBILE	60
Mexico	MEX	TOLL_FREE	60
Mexico	MEX	SHARED_COST	60
Netherlands	NLD	GEOGRAPHIC	90
Netherlands	NLD	NATIONAL	90
Netherlands	NLD	MOBILE	90
Netherlands	NLD	TOLL_FREE	90
Netherlands	NLD	SHARED_COST	90
New Zealand	NZL	GEOGRAPHIC	90
New Zealand	NZL	NATIONAL	90
New Zealand	NZL	MOBILE	90
New Zealand	NZL	TOLL_FREE	90
New Zealand	NZL	SHARED_COST	90
Norway	NOR	GEOGRAPHIC	90
Norway	NOR	NATIONAL	90
Norway	NOR	MOBILE	90
Norway	NOR	TOLL_FREE	90
Norway	NOR	SHARED_COST	90
Panama	PAN	GEOGRAPHIC	60
Panama	PAN	NATIONAL	60
Panama	PAN	MOBILE	60
Panama	PAN	TOLL_FREE	60
Panama	PAN	SHARED_COST	60
Peru	PER	GEOGRAPHIC	60
Peru	PER	NATIONAL	60
Peru	PER	MOBILE	60
Peru	PER	TOLL_FREE	60
Peru	PER	SHARED_COST	60
Philippines	PHL	GEOGRAPHIC	60
Philippines	PHL	NATIONAL	60
Philippines	PHL	MOBILE	60
Philippines	PHL	TOLL_FREE	60
Philippines	PHL	SHARED_COST	60
Poland	POL	GEOGRAPHIC	90
Poland	POL	NATIONAL	90
Poland	POL	MOBILE	90
Poland	POL	TOLL_FREE	90
Poland	POL	SHARED_COST	90
Portugal	PRT	GEOGRAPHIC	90
Portugal	PRT	NATIONAL	90
Portugal	PRT	MOBILE	90
Portugal	PRT	TOLL_FREE	90
Portugal	PRT	SHARED_COST	90
Puerto Rico	PRI	GEOGRAPHIC	60
Puerto Rico	PRI	NATIONAL	60
Puerto Rico	PRI	MOBILE	60
Puerto Rico	PRI	TOLL_FREE	60
Puerto Rico	PRI	SHARED_COST	60
Romania	ROU	GEOGRAPHIC	60
Romania	ROU	NATIONAL	60
Romania	ROU	MOBILE	60
Romania	ROU	TOLL_FREE	60
Romania	ROU	SHARED_COST	60
Singapore	SGP	GEOGRAPHIC	90
Singapore	SGP	NATIONAL	90
Singapore	SGP	MOBILE	90
Singapore	SGP	TOLL_FREE	90
Singapore	SGP	SHARED_COST	90
Slovakia	SVK	GEOGRAPHIC	60
Slovakia	SVK	NATIONAL	60
Slovakia	SVK	MOBILE	60
Slovakia	SVK	TOLL_FREE	60
Slovakia	SVK	SHARED_COST	60
Slovenia	SVN	GEOGRAPHIC	90
Slovenia	SVN	NATIONAL	90
Slovenia	SVN	MOBILE	90
Slovenia	SVN	TOLL_FREE	90
Slovenia	SVN	SHARED_COST	90
South Africa	ZAF	GEOGRAPHIC	60
South Africa	ZAF	NATIONAL	60
South Africa	ZAF	MOBILE	60
South Africa	ZAF	TOLL_FREE	60
South Africa	ZAF	SHARED_COST	60
South Korea	KOR	GEOGRAPHIC	60
South Korea	KOR	NATIONAL	60
South Korea	KOR	MOBILE	60
South Korea	KOR	TOLL_FREE	60
South Korea	KOR	SHARED_COST	60
Spain	ESP	GEOGRAPHIC	90
Spain	ESP	NATIONAL	90
Spain	ESP	MOBILE	90
Spain	ESP	TOLL_FREE	90
Spain	ESP	SHARED_COST	90
Sweden	SWE	GEOGRAPHIC	90
Sweden	SWE	NATIONAL	90
Sweden	SWE	MOBILE	90
Sweden	SWE	TOLL_FREE	90
Sweden	SWE	SHARED_COST	90
Switzerland	CHE	GEOGRAPHIC	90
Switzerland	CHE	NATIONAL	90
Switzerland	CHE	MOBILE	90
Switzerland	CHE	TOLL_FREE	90
Switzerland	CHE	SHARED_COST	90
Turkey	TUR	GEOGRAPHIC	90
Turkey	TUR	NATIONAL	90
Turkey	TUR	MOBILE	90
Turkey	TUR	TOLL_FREE	90
Turkey	TUR	SHARED_COST	90
United Arab Emirates	ARE	GEOGRAPHIC	60
United Arab Emirates	ARE	NATIONAL	60
United Arab Emirates	ARE	MOBILE	60
United Arab Emirates	ARE	TOLL_FREE	60
United Arab Emirates	ARE	SHARED_COST	60
United Kingdom	GBR	GEOGRAPHIC	90
United Kingdom	GBR	NATIONAL	90
United Kingdom	GBR	MOBILE	90
United Kingdom	GBR	TOLL_FREE	90
United Kingdom	GBR	SHARED_COST	90
United States	USA	GEOGRAPHIC	60
United States	USA	NATIONAL	60
United States	USA	MOBILE	60
United States	USA	TOLL_FREE	60
United States	USA	SHARED_COST	60
Venezuela	VEN	GEOGRAPHIC	60
Venezuela	VEN	NATIONAL	60
Venezuela	VEN	MOBILE	60
Venezuela	VEN	TOLL_FREE	60
Venezuela	VEN	SHARED_COST	60
Virgin Islands (u.s.)	VIR	GEOGRAPHIC	60
Virgin Islands (u.s.)	VIR	NATIONAL	60
Virgin Islands (u.s.)	VIR	MOBILE	60
Virgin Islands (u.s.)	VIR	TOLL_FREE	60
Virgin Islands (u.s.)	VIR	SHARED_COST	60

Where to next?

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

• How to search and order a number