churn_tracker

churn_tracker returns the lifecycle events recorded for a phone number: deactivations, number swaps, suspensions and reactivations, each with the operator that recorded it and when.

A number that was recently deactivated and given to someone else is a common source of misdirected one-time codes and account takeovers. The event history tells you whether the number you hold for a customer may now belong to someone else.

Request

Send the number and churn_tracker in commands. No other input is needed.

{
  "number": "+12025550143",
  "commands": ["churn_tracker"]
}

churn_tracker is not available in every country. Where it is not available, see Billing.

Response

The churn_tracker block is a list of events:

{
  "status": 0,
  "status_message": "Response from one supplier",
  "churn_tracker": [
    {
      "operator": "Verizon Wireless",
      "action": "DE",
      "ts": "2026-06-14T09:12:00.000Z",
      "number": 12025550143
    },
    {
      "operator": "Verizon Wireless",
      "action": "SW",
      "ts": "2026-02-03T17:40:00.000Z",
      "number": 12025550143,
      "number2": 12025550178
    }
  ],
  "version": "..."
}

Field	Type	Meaning
`operator`	string	The operator that recorded the event.
`action`	string	The kind of event. See the table below.
`ts`	string	When the event happened, ISO 8601 in UTC, for example `2026-06-14T09:12:00.000Z`.
`number`	integer	The phone number the event refers to, in international format without the `+`.
`number2`	integer	For a number swap, the new number the subscriber moved to. Absent for other events.

action values

Value	Meaning
`DE`	Deactivated.
`SW`	Number swap: the subscriber moved to `number2`.
`SU`	Suspended.
`RE`	Reactivated.

Do not assume the list is sorted: order the events by ts before reading the most recent one.

When there is no churn_tracker block

If no event is recorded for the number, or the source could not be reached, the response has no churn_tracker block. An empty list is never returned. The status is 4, and the status_message names churn_tracker among the commands that returned no data. If the number's country is not covered, the status is 2, or 4 when other commands were served.

Billing

A response with a churn_tracker block is charged. A response without it, including a number with no recorded events, is not charged.