Write to docs@telesign.com.
Perform Number Deactivation Check
This page shows you how to send a request to find out the activation status of a phone number using the Number Deactivation API. The Number Deactivation API will return basic details about whether the number has been deactivated, when, and by which carrier the phone number was deactivated based on carriers’ phone number data and TeleSign’s proprietary analysis.
The fastest way to try out this API is with TeleSign’s Number Deactivation API Explorer.
Use these instructions with the Number Deactivation API Explorer (above) to perform a number deactivation check and get a code snippet for making the request in the language of your choice.
- Click the Auth [basic] tab and for Username add your Customer ID. For Password add your API key.
- Click the Settings tab and in the complete_phone_number field, enter your phone number with the country code and no special characters or spaces.
- Click Send.
- Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.
- After you send your request, look through the JSON response and save the value for the
reference_id
parameter. You will need this to receive transaction status results, described on the Obtain Transaction Status Results page.
Congratulations! You’ve performed your first number deactivation check using TeleSign’s Number Deactivation API and generated a code snippet!
You can see more about available parameters for requests on the GET /v1/phoneid/number_deactivation page.
The rest of this page provides details about the Number Deactivation API. You can choose from these options:
Number Deactivation API Information
All requests and responses submitted for the Number Deactivation API:
- Can be authenticated with Basic (easiest to implement) and Digest
- Use
https://rest-ww.telesign.com/v1/phoneid/number_deactivation/<complete_phone_number>
as the base endpoint. The complete number includes the country code - Accept only UTF-8 encoded unicode characters as inputs
- Use Content-Type - application/x-www-form-urlencoded in request headers
Examples
This section shows examples of requests to and responses from the Number Deactivation API.
Here is an example request to the Number Deactivation API:
GET https://rest-ww.telesign.com/v1/phoneid/number_deactivation/15555551212?ucid=UNKN HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:51:26 GMT
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"number_deactivation": {
"number": "13101234567",
"tracking_since": "2014-02-25T22:51:02Z",
"last_deactivated": "2015-06-08T12:13:14Z",
"mcc": "310",
"mnc": "150;170;410"
},
"errors": [],
"status": {
"code": 2300,
"description": "Number Deactivation check succeeded",
"updated_on": "2015-06-08T12:13:14.976983Z"
}
}
The following is an example of a response body returned when the request contains a phone number that is not found.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"number_deactivation": {
"number": "13101234567",
"tracking_since": "2014-02-25T22:51:02Z",
"last_deactivated": null
},
"errors": [],
"status": {
"code": 2300,
"description": "Number Deactivation check succeeded",
"updated_on": "2015-06-08T12:13:14.976983Z"
}
}
The following is an example of the response body returned when the request contains an invalid phone number parameter.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"errors": [
{
"code": -10001,
"description": "Invalid Request: PhoneNumber Parameter: <value>"
}
],
"status": {
"code": 500,
"description": "Transaction not attempted",
"updated_on": "2015-06-08T12:13:14.976983Z"
}
}
The following is an example of the response body returned when the request contains a number that has invalid phone coverage.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"errors": [
{
"code": -40010,
"description": "Phone number out of coverage"
}
],
"status": {
"code": 2301,
"description": "Transaction failed",
"updated_on": "2015-06-08T12:13:14.976983Z"
}
}
The following is an example of the response body returned when the customer identifier is invalid.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"errors": [
{
"code": -30000,
"description": "Invalid Customer ID"
}
],
"status": {
"updated_on": "2015-03-17T18:31:15.976983Z",
"code": 501,
"description": "Not authorized"
}
}
The following is an example of the response body returned when the request contains a failed authorization header.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"errors": [
{
"code": -30004,
"description": "Missing required 'Authorization' header"
}
],
"status": {
"updated_on": "2015-03-17T18:31:15.976983Z",
"code": 501,
"description": "Not authorized"
}
}
The following is an example of the response body returned when the request signature is invalid.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"errors": [
{
"code": -30006,
"description": "Invalid Signature"
}
],
"status": {
"updated_on": "2015-03-17T18:31:15.976983Z",
"code": 501,
"description": "Not authorized"
}
"signature_string": "GET\n\n\nx-ts-auth-method:HMAC-SHA256\nx-ts-date:Wed, 17 Mar 2015 18:31:15 GMT\nx-ts-nonce:ab4dd44c-5b3f-46e5-b306-b1ef660c6109\n/v1/phoneid/number_deactivation/123456789"
}
The following is an example of the response body returned when the request contains a missing phone number.
{
"errors": [
{
"code": -40004,
"description": "Resource Not Found"
}
],
}
The following is an example of the response body returned when the system is unavailable.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "number_deactivation",
"errors": [
{
"code": -90001,
"description": "System unavailable; please try again later"
}
],
"status": {
"updated_on": "2015-03-17T18:31:15.976983Z",
"code": 2301,
"description": "Transaction failed"
}
}
Next Steps
This section offers some suggestions for next steps to take.
- Number Deactivation Subscription - take a look at the Number Deactivation Subscription service, which lets you find out the status of phone numbers you provide in a subscription list to TeleSign.
- GET /v1/phoneid/number_deactivation - Review the Number Deactivation API parameters and response.