PhoneID API - Add-ons: Number Deactivation

The Number Deactivation add-on allows you to find out whether a phone number has been deactivated, when it was deactivated, and by which carrier the phone number was deactivated based on carriers' phone number data and TeleSign's proprietary analysis. This information is returned in addition to the standard PhoneID API information.

The Number Deactivation add-on allows you to get information from the Number Deactivation API without having to implement it separately. The information returned includes:

  • Carrier: The name of the carrier which deactivated the phone number most recently.
  • Last Deactivated Timestamp: When the phone number was last deactivated.
  • Tracking Since Timestamp: The date and time when the phone number started being tracked for number deactivation events.
  • Recycled: Whether the number has been recycled since the last verified date you provide. Only returned if you include the last_verified parameter in your request.

Examples

Example 1: Success

Request

POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json
{
    "addons": {
        "number_deactivation": {
            "last_verified": "2018-04-05T00:00:00Z"
        }
    }
}

Response (body only)

{
  "number_deactivation": {
    "carrier_name": "Verizon",
    "last_deactivated": "2018-04-06T00:00:00Z",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    },
    "tracking_since": "2014-10-06T00:00:00Z",
    "recycled_since_last_verification": "recycled"
  }
}

Example 2: Failure

Request

POST https://rest-ww.telesign.com/v1/phoneid/15555551213 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json
{
  "addons": {
    "number_deactivation": {
      "last_verified": "2018-04-05T00:00:00Z"
    }
  }
}

Response (body only)

{
  "number_deactivation": {
    "status": {
      "code": 2603,
      "description": "Phone number out of number_deactivation add-on coverage."
    }
  }
}

## Schema

**Number Deactivation Request Parameters** 


[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Type",
    "h-2": "Description",
    "0-0": "addons",
    "0-1": "object",
    "1-0": "addons.number_deactivation",
    "1-1": "object",
    "0-2": "You must have you Technical Account Manager enable this feature for use. The addons parameter allows you to receive information returned from Contact, Contact Plus, Contact Match, or Number Deactivation, depending on which add-ons you enable. You receive add-on information back along with standard PhoneID information.",
    "1-2": "The last date and time you successfully verified this user's identity. If this parameter is included, the response includes additional sub-properties within the `number_deactivation` package. The value must be formatted according to the ISO-8601 standard.",
    "h-3": "Example",
    "1-3": "",
    "2-0": "addons.number_deactivation.last_verified",
    "2-1": "string",
    "2-2": "The last date and time you successfully verified this user's identity. If this parameter is included, the response includes additional sub-properties within the `number_deactivation` package. The value must be formatted according to the ISO-8601 standard.",
    "2-3": "2018-04-05T00:00:00Z"
  },
  "cols": 4,
  "rows": 3
}
[/block]

**Number Deactivation Response** 


[block:parameters]
{
  "data": {
    "0-0": "reference_id",
    "1-0": "phone_type",
    "2-0": "description",
    "3-0": "number_deactivation",
    "4-0": "number_deactivation.carrier_name",
    "5-0": "number_deactivation.last_deactivated",
    "6-0": "number_deactivation.tracking_since",
    "7-0": "number_deactivation.status",
    "8-0": "number_deactivation.status.code",
    "9-0": "number_deactivation.status.description",
    "8-1": "integer",
    "9-1": "string",
    "10-0": "number_deactivation.recycled_since_last_verification",
    "10-1": "string",
    "0-1": "string",
    "h-0": "Property",
    "h-1": "Type",
    "h-2": "Description",
    "0-2": "A 32-digit hex value used to identify the web service requests. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.",
    "1-2": "One of the [phone type code](https://enterprise.telesign.com/docs/codes-languages-and-time-zones#section-phone-type-codes\\).",
    "1-1": "string",
    "2-2": "Text describing the phone type.",
    "2-1": "string",
    "3-1": "object",
    "3-2": "You will only see this in your response if you used the number deactivation add-on.",
    "4-2": "The name of the current carrier for the phone.",
    "h-3": "Example",
    "4-3": "Verizon",
    "5-2": "When the phone was last deactivated (if it was).",
    "5-3": "2016-04-05T00:00:00Z",
    "4-1": "string",
    "5-1": "string",
    "6-1": "string",
    "7-1": "object",
    "6-2": "When the phone number first started being tracked for deactivation status.",
    "6-3": "2014-10-06T00:00:00Z",
    "7-2": "Contains details about the delivery status of this package.",
    "8-2": "A status or error code describing what happened after your request.",
    "8-3": "2800",
    "9-2": "A brief description of what the error or status code means.",
    "9-3": "Request successfully completed",
    "10-2": "Whether or not the phone number has been recycled since the time and date you provided. Only appears if you included a `last_verified` value in your request.\n\nEnumerated values:\n\n* `recycled`\n* `not_recycled`\n* `cannot_be_determined`",
    "10-3": "recycled"
  },
  "cols": 4,
  "rows": 11
}
[/block]


 

Did this page help you?