Skip to contentSkip to navigationSkip to topbar
On this page

Reassigned Number


Reassigned Number package allows you to check if the same user who previously owned a phone number is still the owner. Confirming this prior to contacting the person will provide safe harbor against TCPA violation fees resulting from contacting someone who has not given you consent to message them (you may still need to prove you were initially given consent).

Coverage and Limitations: This product is only available when querying US phone numbers. If you are interested in this product for other regions please alert your Twilio Account Manager. This will help our product and engineering teams prioritize future supply additions to this feature.

Release Stage and Access: Generally available (GA). To request access, submit this form(link takes you to an external page).

To make a Reassigned Number request, add reassigned_number to the optional query parameter Fields when making a standard Lookup request and include the mandatory parameter LastVerifiedDate in the format YYYYMMDD. This field is the date you obtained consent to call or text the end-user of the phone number or a date on which you are reasonably certain that the end-user could still be reached at that number (e.g., date of last contact, date end-user last updated their phone number).

Reassigned Number LookupLink to code sample: Reassigned Number Lookup
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();

Output

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
}

Response properties

response-properties page anchor

The following additional properties are returned for a SMS Pumping Risk request.

PropertyDescription
is_number_reassignedAn object that states whether or not a phone number has been reassigned to a new user since the provided LastVerifiedDate.
ErrorCodeThe error code, if any, associated with your request.

Possible values for is_number_reassigned

possible-values-for-is_number_reassigned page anchor

The following are the possible values for the is_number_reassigned parameter.

PropertyDescription
yesThis phone number has been reassigned to a new user and you should not message this number.
nothis phone number still belongs to the same person and is safe to message, this response provides safe harbor from TCPA violations if the customer can show that they collected consent to contact the number, and queried this database using the date when consent was collected.
no_data_availableThis means that we do not have disconnect data for this phone number, and generally means that your LastVerifiedDate is prior to January of 2021. We suggest validating consent to contact.

For this package Twilio uses the official database maintained by the Federal Communications Commission (FCC).


Suggested implementation logic

suggested-implementation-logic page anchor

Standard implementation of this package would be to query the Reassigned Number package prior to sending any marketing materials, or high risk transactions (such as financial transactions, password reset instructions, etc.) to a phone number. If you discover that the phone number no longer belongs to the person you are trying to contact, cancel the message and use another contact method to confirm the users phone number prior to sending the information.

This database updates monthly on the 16th day of each month. For customers who need to validate number reassignment status more than once per month, we suggest they refresh their database starting on the 17th of each month. Data obtained on the 17th of the month will remain valid until the database refreshes 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:

QueriesPrice
0-1,000$0.02
1,000-10,000$0.014
10,000-50,000$0.0125
50,000-200,000$0.0085
200,000-500,000$0.0075
500,000-2,000,000$0.003
2,000,000-6,000,000$0.0025
6,000,000+$0.0015

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.