Legacy Phone ID Number Deactivation

❗️
WARNING
This product is deprecated.

This page shows you how to send a request to find out the activation status of a phone number using the Telesign's legacy Number Deactivation product. This service returns 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 service is with the API Explorer. Use these instructions with the API Explorer to perform a number deactivation check and get a code snippet for making the request in the language of your choice.

Before you begin

Ensure that you have the following:

Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.

Steps

🚧
CAUTION:
Using your account credentials in the API Explorer to make a request results in your account being charged for the transaction.
You are subject to all compliance rules as appropriate for your transaction.

Go to the reference page POST https://rest-ww.telesign.com/v1/phoneid/number_deactivation/{complete_phone_number}.
Under the AUTHENTICATION header in the right panel of the page, put your Customer ID in the Customer ID field and your API key in the API Key field.
Go to the PATH PARAMS section in the middle panel of the page. For complete_phone_number, enter your phone number with the country code and no special characters or spaces.
Select Try It! in the right panel to send your request to Telesign. You will be charged the standard rate for this transaction.
You can also select the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.

Congratulations! You've performed your first number deactivation check using Telesign's legacy Number Deactivation product and generated a code snippet!

You can see more about available parameters for requests on that same reference page.

General requirements

Authentication: Basic (easiest to implement) and Digest
Endpoint: https://rest-ww.telesign.com/v1/phoneid/number_deactivation/{complete_phone_number}
Encoding: Accept only UTF-8 encoded unicode characters as inputs.
Required headers: Content-Type - application/x-www-form-urlencoded

Examples

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

Response (success)

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
  }
}

Response (failure, number not found)

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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.

Response (failure, invalid number)

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
  "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"
  }
}

Response (failure, number out of coverage)

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
  "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"
  }
}

Response (failure, authorization failed)

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
{
  "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"
  }
}