PhoneID Number Deactivation API

The PhoneID Number Deactivation API determines whether a phone 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.

General Information

All requests 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

Perform Number Deactivation Check

Read about how to find out the activation status of a phone number on the Perform Number Deactivation Check page.

For a list of available parameters, see the GET /v1/phoneid/number_deactivation page.

Number Deactivation API Examples

This section contains an example of a typical Request-Response transaction for invoking the Number Deactivation web service.

Request

You send a GET request message like this one, to the /v1/phoneid/number_deactivation/<complete_phone_number> subresource, with your user’s complete phone number as the Subresource Identifier, and the use-case code as a Query Parameter.

Example GET Request

GET https://rest-ww.telesign.com/v1/phoneid/number_deactivation/447735111111?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

TeleSign returns the following messages in response to the preceding example request, with a Success Response, HTTP Code 200.

Successful Response

HTTP/1.1 200 OK
Date: Tue, 28 Oct 2014 23:29:08 GMT
Server: Apache
Content-Length: 1043
Allow: GET,HEAD
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
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"
   }
}

Number Not Found, HTTP Code 200

The following is an example of a response returned when the request contains a phone number that is not found.

Example Number 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"
  }
}

Error Responses

Invalid Phone Number, HTTP Code 400

The following is an example of the response body returned when the request contains an invalid phone number parameter.

Invalid Phone Number

{
  "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"
  }
}

Phone Number Out of Coverage, HTTP Code 400

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

{
  "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"
  }
}

Authorization Failed, HTTP Code 401, Invalid

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"
  }
}

Authorization Failed, HTTP Code 401

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"
  }
}

Authorization Failed, HTTP Code 401, Request Signature Invalid

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"
}

### Phone Number Missing, HTTP Code 404
The following is an example of the response body returned when the request contains a missing phone number.

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

System Unavailable, HTTP Code 503

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"
  }
}