Reassigned Number

Reassigned Number is only available for US phone numbers.

Make a GET /v2/PhoneNumbers/{PhoneNumber} request with the following query parameters:

• Fields=reassigned_number
• LastVerifiedDate: The date you obtained consent to call or text the phone number, or the date when you last verified the phone number (for example, the date of last contact or the date they last updated their phone number). This must be in the format YYYYMMDD.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchPhoneNumber() {
11
  const phoneNumber = await client.lookups.v2.phoneNumbers("2345678904").fetch({
12
    fields: "reassigned_number",
13
    lastVerifiedDate: "20211015",
14
  });
15

16
  console.log(phoneNumber.reassignedNumber);
17
}
18

19
fetchPhoneNumber();

1
{
2
  "calling_country_code": "1",
3
  "country_code": "US",
4
  "phone_number": "2345678904",
5
  "national_format": "(415) 992-9960",
6
  "valid": true,
7
  "validation_errors": [],
8
  "caller_name": null,
9
  "sim_swap": null,
10
  "call_forwarding": null,
11
  "line_status": null,
12
  "line_type_intelligence": null,
13
  "identity_match": null,
14
  "reassigned_number": {
15
    "last_verified_date": "2019-09-24",
16
    "is_number_reassigned": "no",
17
    "error_code": null
18
  },
19
  "sms_pumping_risk": null,
20
  "phone_number_quality_score": null,
21
  "pre_fill": null,
22
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
23
}

A Reassigned Number request returns the following properties.

The is_number_reassigned property can have the following values.

Note: Twilio uses the official database maintained by the Federal Communications Commission (FCC) to indicate whether a number has been reassigned.

Twilio recommends querying the Reassigned Number package prior to sending any marketing materials or high risk transactions (such as financial transactions or password reset instructions) to a phone number. If the phone number no longer belongs to the person you're trying to contact, cancel the message and use another contact method to verify the user's phone number before sending any sensitive information.

The Reassigned Number database is updated monthly on the 16th of each month. If you need to verify a phone number's reassignment status more than once per month, Twilio suggests that you update your database starting on the 17th of each month. Data obtained on the 17th of the month will remain valid until the database is updated again on the 16th of the following month.

The Reassigned Number feature follows a tiered pricing model where the more queries you make in a month, the less expensive each subsequent query becomes. This resets at the beginning of each billing cycle and scales using the following volumes: