logo
API Reference
Tutorials
SDKs
Legacy
Legal & Compliance
Support
No results found.
Voice API (Legacy)
Get Started
Number Deactivation API
Get Started
GET v1/phoneid/number_deactivation
Number Deactivation Subscription
PhoneID Contact API
Get Started
POST /verify/smart
App Verify Android SDK
Legacy Tutorials
App Verify
App Verify (SDK)
Voice (Legacy)
Want to provide feedback?

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.

Number Deactivation API Explorer
NOTE: When using the Number Deactivation API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms is not indicative of regular transmission rates, and only applies to the Number Deactivation API Explorer.
SettingsHeaders [1]Auth[basic]Code Generation
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
complete_phone_number
$$.env
No $$.env variables are being used in this request.

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.

  1. Click the Auth [basic] tab and for Username add your customer ID. For Password add your API key.
  2. 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.
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.
  5. 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:

Example GET Request
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
Successful Response Body
{
  "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.

Number Not Found, HTTP Code 200
{
  "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.

Invalid Phone Number HTTP Code 400
{
  "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.

Phone Number Out of Coverage, HTTP Code 400
{
  "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.

Authorization Failed 
{
  "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.

Authorization Failed, HTTP Code 401
{
  "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.

Request Signature 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.

Phone Number Missing
{
   "errors": [
       {
            "code": -40004,
            "description": "Resource Not Found"
       }
   ],
}

The following is an example of the response body returned when the system is unavailable.

System 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.