Skip to content Skip to navigation Skip to topbar

On this page

Toll-free verification resource

The Verification resource records your request to verify a toll-free number to comply with US and Canadian federal regulations for SMS messaging. The verification process is called toll-free verification (TFV).

Toll-free phone numbers for the US and Canada use the North American Numbering Plan (NANP). NANP toll-free numbers begin with 800, 888, 877, 866, 855, 844, or 833. To use these numbers to send SMS messages, your organization must comply with federal regulations. For the toll-free number to be compliant, provide data on how you plan to use your phone number to send texts.

To verify that a toll-free number meets these regulations, use this resource. To learn how to use this resource, see Get started with toll-free verification using the API.

Verification Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<HH>

Optional

The unique string to identify Tollfree Verification.

Pattern: ^HH[0-9a-fA-F]{32}$Min length: 34Max length: 34

accountSidSID<AC>

Optional

The SID of the Account that created the Tollfree Verification resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

customerProfileSidSID<BU>

Optional

Customer's Profile Bundle BundleSid.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34

trustProductSidSID<BU>

Optional

Tollfree TrustProduct Bundle BundleSid.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34

dateCreatedstring<date-time>

Optional

The date and time in GMT when the resource was created specified in ISO 8601 format.

dateUpdatedstring<date-time>

Optional

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

regulatedItemSidSID<RA>

Optional

The SID of the Regulated Item.

Pattern: ^RA[0-9a-fA-F]{32}$Min length: 34Max length: 34

businessNamestring

Optional

The name of the business or organization using the Tollfree number.

businessStreetAddressstring

Optional

The address of the business or organization using the Tollfree number.

businessStreetAddress2string

Optional

The address of the business or organization using the Tollfree number.

businessCitystring

Optional

The city of the business or organization using the Tollfree number.

businessStateProvinceRegionstring

Optional

The state/province/region of the business or organization using the Tollfree number.

businessPostalCodestring

Optional

The postal code of the business or organization using the Tollfree number.

businessCountrystring

Optional

The country of the business or organization using the Tollfree number.

businessWebsitestring

Optional

The website of the business or organization using the Tollfree number.

businessContactFirstNamestring

Optional

The first name of the contact for the business or organization using the Tollfree number.

businessContactLastNamestring

Optional

The last name of the contact for the business or organization using the Tollfree number.

businessContactEmailstring

Optional

The email address of the contact for the business or organization using the Tollfree number.

businessContactPhonestring<phone-number>

Optional

The E.164 formatted phone number of the contact for the business or organization using the Tollfree number.

notificationEmailstring

Optional

The email address to receive the notification about the verification result. .

useCaseCategoriesarray[string]

Optional

The category of the use case for the Tollfree Number. List as many are applicable..

useCaseSummarystring

Optional

Use this to further explain how messaging is used by the business or organization.

productionMessageSamplestring

Optional

An example of message content, i.e. a sample message.

optInImageUrlsarray[string]

Optional

Link to an image that shows the opt-in workflow. Multiple images allowed and must be a publicly hosted URL.

optInTypeenum<string>

Optional

Describe how a user opts-in to text messages.

Possible values:

VERBALWEB_FORMPAPER_FORMVIA_TEXTMOBILE_QR_CODEIMPORTIMPORT_PLEASE_REPLACE

messageVolumestring

Optional

Estimate monthly volume of messages from the Tollfree Number.

additionalInformationstring

Optional

Additional information to be provided for verification.

tollfreePhoneNumberSidSID<PN>

Optional

The SID of the Phone Number associated with the Tollfree Verification.

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34

statusenum<string>

Optional

The compliance status of the Tollfree Verification record.

Possible values:

PENDING_REVIEWIN_REVIEWTWILIO_APPROVEDTWILIO_REJECTED

urlstring<uri>

Optional

The absolute URL of the Tollfree Verification resource.

rejectionReasonstring

Optional

The rejection reason given when a Tollfree Verification has been rejected.

errorCodeinteger

Optional

The error code given when a Tollfree Verification has been rejected.

editExpirationstring<date-time>

Optional

The date and time when the ability to edit a rejected verification expires.

editAllowedboolean

Optional

If a rejected verification is allowed to be edited/resubmitted. Some rejection reasons allow editing and some do not.

rejectionReasonsarray

Optional

A list of rejection reasons and codes describing why a Tollfree Verification has been rejected.

resourceLinksobject

Optional

The URLs of the documents associated with the Tollfree Verification resource.

externalReferenceIdstring

Optional

An optional external reference ID supplied by customer and echoed back on status retrieval.

Submit one TFV Request

POST https://messaging.twilio.com/v1/Tollfree/Verifications

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

businessNamestring

required

The name of the business or organization using the Tollfree number.

businessWebsitestring

required

The website of the business or organization using the Tollfree number.

notificationEmailstring

required

The email address to receive the notification about the verification result. .

useCaseCategoriesarray[string]

required

The category of the use case for the Tollfree Number. List as many are applicable..

useCaseSummarystring

required

Use this to further explain how messaging is used by the business or organization.

productionMessageSamplestring

required

An example of message content, i.e. a sample message.

optInImageUrlsarray[string]

required

Link to an image that shows the opt-in workflow. Multiple images allowed and must be a publicly hosted URL.

optInTypeenum<string>

required

Describe how a user opts-in to text messages.

Possible values:

VERBALWEB_FORMPAPER_FORMVIA_TEXTMOBILE_QR_CODEIMPORTIMPORT_PLEASE_REPLACE

messageVolumestring

required

Estimate monthly volume of messages from the Tollfree Number.

tollfreePhoneNumberSidSID<PN>

required

The SID of the Phone Number associated with the Tollfree Verification.

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34

customerProfileSidSID<BU>

Optional

Customer's Profile Bundle BundleSid.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34

businessStreetAddressstring

Optional

The address of the business or organization using the Tollfree number.

businessStreetAddress2string

Optional

The address of the business or organization using the Tollfree number.

businessCitystring

Optional

The city of the business or organization using the Tollfree number.

businessStateProvinceRegionstring

Optional

The state/province/region of the business or organization using the Tollfree number.

businessPostalCodestring

Optional

The postal code of the business or organization using the Tollfree number.

businessCountrystring

Optional

The country of the business or organization using the Tollfree number.

additionalInformationstring

Optional

Additional information to be provided for verification.

businessContactFirstNamestring

Optional

The first name of the contact for the business or organization using the Tollfree number.

businessContactLastNamestring

Optional

The last name of the contact for the business or organization using the Tollfree number.

businessContactEmailstring

Optional

The email address of the contact for the business or organization using the Tollfree number.

businessContactPhonestring<phone-number>

Optional

The E.164 formatted phone number of the contact for the business or organization using the Tollfree number.

externalReferenceIdstring

Optional

An optional external reference ID supplied by customer and echoed back on status retrieval.

Submitting a TFV request requires a Trust Hub Customer Profile.

Submit with an existing Customer Profile

If you have a Customer Profile, the following API request submits one TFV request associated with your Customer Profile SID.

Submit one TFV Request when you have a Customer Profile

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createTollfreeVerification() {
11  const tollfreeVerification =
12    await client.messaging.v1.tollfreeVerifications.create({
13      additionalInformation:
14        "see our privacy policy here www.example.com/privacypolicy",
15      businessName: "Owl, Inc.",
16      businessWebsite: "http://www.example.com",
17      customerProfileSid: "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18      externalReferenceId: "abc123xyz567",
19      messageVolume: "10",
20      notificationEmail: "support@example.com",
21      optInImageUrls: [
22        "https://example.com/images/image1.jpg",
23        "https://example.com/images/image2.jpg",
24      ],
25      optInType: "VERBAL",
26      productionMessageSample: "lorem ipsum",
27      tollfreePhoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
28      useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],
29      useCaseSummary:
30        "This number is used to send out promotional offers and coupons to the customers of Owl, Inc.",
31    });
32
33  console.log(tollfreeVerification.sid);
34}
35
36createTollfreeVerification();

Response

1{
2  "sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "regulated_item_sid": null,
6  "trust_product_sid": null,
7  "business_name": "Owl, Inc.",
8  "status": "PENDING_REVIEW",
9  "date_created": "2021-01-27T14:18:35Z",
10  "date_updated": "2021-01-27T14:18:36Z",
11  "business_street_address": "123 Main Street",
12  "business_street_address2": "Suite 101",
13  "business_city": "Anytown",
14  "business_state_province_region": "AA",
15  "business_postal_code": "11111",
16  "business_country": "US",
17  "business_website": "http://www.example.com",
18  "business_contact_first_name": "firstname",
19  "business_contact_last_name": "lastname",
20  "business_contact_email": "email@company.com",
21  "business_contact_phone": "+11231231234",
22  "notification_email": "support@example.com",
23  "use_case_categories": [
24    "TWO_FACTOR_AUTHENTICATION",
25    "MARKETING"
26  ],
27  "use_case_summary": "This number is used to send out promotional offers and coupons to the customers of Owl, Inc.",
28  "production_message_sample": "lorem ipsum",
29  "opt_in_image_urls": [
30    "https://testbusiness.com/images/image1.jpg",
31    "https://testbusiness.com/images/image2.jpg"
32  ],
33  "opt_in_type": "VERBAL",
34  "message_volume": "10",
35  "additional_information": "see our privacy policy here www.example.com/privacypolicy",
36  "tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
37  "rejection_reason": null,
38  "error_code": null,
39  "edit_expiration": null,
40  "edit_allowed": null,
41  "rejection_reasons": null,
42  "resource_links": {},
43  "url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44  "external_reference_id": "abc123xyz567"
45}

Submit one TFV Request without an existing Customer Profile

If you don't have a Trust Hub Customer Profile, the following API request creates a Customer Profile and submits one TFV request for that profile.

Submit one TFV Request when you don't have a Customer Profile

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createTollfreeVerification() {
11  const tollfreeVerification =
12    await client.messaging.v1.tollfreeVerifications.create({
13      additionalInformation:
14        "see our privacy policy here www.example.com/privacypolicy",
15      businessCity: "Anytown",
16      businessContactEmail: "email@example.com",
17      businessContactFirstName: "firstname",
18      businessContactLastName: "lastname",
19      businessContactPhone: "+1231231234",
20      businessCountry: "US",
21      businessName: "Owl, Inc.",
22      businessPostalCode: "11111",
23      businessStateProvinceRegion: "AA",
24      businessStreetAddress: "123 Main Street",
25      businessStreetAddress2: "Suite 101",
26      businessWebsite: "http://www.example.com",
27      externalReferenceId: "abc123xyz567",
28      messageVolume: "10",
29      notificationEmail: "support@example.com",
30      optInImageUrls: [
31        "https://example.com/images/image1.jpg",
32        "https://example.com/images/image2.jpg",
33      ],
34      optInType: "VERBAL",
35      productionMessageSample: "lorem ipsum",
36      tollfreePhoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
37      useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],
38      useCaseSummary:
39        "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
40    });
41
42  console.log(tollfreeVerification.sid);
43}
44
45createTollfreeVerification();

Response

1{
2  "sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "regulated_item_sid": null,
5  "customer_profile_sid": null,
6  "trust_product_sid": null,
7  "status": "PENDING_REVIEW",
8  "date_created": "2021-01-27T14:18:35Z",
9  "date_updated": "2021-01-27T14:18:36Z",
10  "business_name": "Owl, Inc.",
11  "business_street_address": "123 Main Street",
12  "business_street_address2": "Suite 101",
13  "business_city": "Anytown",
14  "business_state_province_region": "AA",
15  "business_postal_code": "11111",
16  "business_country": "US",
17  "business_website": "http://www.example.com",
18  "business_contact_first_name": "firstname",
19  "business_contact_last_name": "lastname",
20  "business_contact_email": "email@example.com",
21  "business_contact_phone": "+1231231234",
22  "notification_email": "support@example.com",
23  "use_case_categories": [
24    "TWO_FACTOR_AUTHENTICATION",
25    "MARKETING"
26  ],
27  "use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
28  "production_message_sample": "lorem ipsum",
29  "opt_in_image_urls": [
30    "https://testbusiness.com/images/image1.jpg",
31    "https://testbusiness.com/images/image2.jpg"
32  ],
33  "opt_in_type": "VERBAL",
34  "message_volume": "10",
35  "additional_information": "see our privacy policy here www.example.com/privacypolicy",
36  "tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
37  "rejection_reason": null,
38  "error_code": null,
39  "edit_expiration": null,
40  "edit_allowed": null,
41  "rejection_reasons": null,
42  "resource_links": {},
43  "url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44  "external_reference_id": "abc123xyz567"
45}

Check the status of one TFV request

GET https://messaging.twilio.com/v1/Tollfree/Verifications/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<HH>

required

A unique string identifying a Tollfree Verification.

Pattern: ^HH[0-9a-fA-F]{32}$Min length: 34Max length: 34

Check one TFV request

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchTollfreeVerification() {
11  const tollfreeVerification = await client.messaging.v1
12    .tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .fetch();
14
15  console.log(tollfreeVerification.sid);
16}
17
18fetchTollfreeVerification();

Response

1{
2  "sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "regulated_item_sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7  "date_created": "2021-01-27T14:18:35Z",
8  "date_updated": "2021-01-27T14:18:36Z",
9  "business_name": "Owl, Inc.",
10  "business_street_address": "123 Main Street",
11  "business_street_address2": "Suite 101",
12  "business_city": "Anytown",
13  "business_state_province_region": "AA",
14  "business_postal_code": "11111",
15  "business_country": "US",
16  "business_website": "http://www.company.com",
17  "business_contact_first_name": "firstname",
18  "business_contact_last_name": "lastname",
19  "business_contact_email": "email@company.com",
20  "business_contact_phone": "+11231231234",
21  "notification_email": "support@company.com",
22  "use_case_categories": [
23    "TWO_FACTOR_AUTHENTICATION",
24    "MARKETING"
25  ],
26  "use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
27  "production_message_sample": "lorem ipsum",
28  "opt_in_image_urls": [
29    "https://testbusiness.com/images/image1.jpg",
30    "https://testbusiness.com/images/image2.jpg"
31  ],
32  "opt_in_type": "VERBAL",
33  "message_volume": "2000",
34  "additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
35  "tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
36  "status": "TWILIO_APPROVED",
37  "rejection_reason": null,
38  "error_code": null,
39  "edit_expiration": null,
40  "edit_allowed": null,
41  "rejection_reasons": null,
42  "resource_links": {
43    "customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44    "trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
45    "channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
46  },
47  "url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
48  "external_reference_id": "abc123xyz567"
49}

List all TFV requests

GET https://messaging.twilio.com/v1/Tollfree/Verifications

Query parameters

Property nameTypeRequiredPIIDescription

tollfreePhoneNumberSidSID<PN>

Optional

The SID of the Phone Number associated with the Tollfree Verification.

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34

statusenum<string>

Optional

The compliance status of the Tollfree Verification record.

Possible values:

PENDING_REVIEWIN_REVIEWTWILIO_APPROVEDTWILIO_REJECTED

externalReferenceIdstring

Optional

Customer supplied reference id for the Tollfree Verification record.

includeSubAccountsboolean

Optional

Whether to include Tollfree Verifications from sub accounts in list response.

pageSizeinteger<int64>

Optional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

pageinteger

Optional

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

List TFV requests

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchTollfreeVerification() {
11  const tollfreeVerification = await client.messaging.v1
12    .tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .fetch();
14
15  console.log(tollfreeVerification.sid);
16}
17
18fetchTollfreeVerification();

Response

1{
2  "sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "regulated_item_sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7  "date_created": "2021-01-27T14:18:35Z",
8  "date_updated": "2021-01-27T14:18:36Z",
9  "business_name": "Owl, Inc.",
10  "business_street_address": "123 Main Street",
11  "business_street_address2": "Suite 101",
12  "business_city": "Anytown",
13  "business_state_province_region": "AA",
14  "business_postal_code": "11111",
15  "business_country": "US",
16  "business_website": "http://www.company.com",
17  "business_contact_first_name": "firstname",
18  "business_contact_last_name": "lastname",
19  "business_contact_email": "email@company.com",
20  "business_contact_phone": "+11231231234",
21  "notification_email": "support@company.com",
22  "use_case_categories": [
23    "TWO_FACTOR_AUTHENTICATION",
24    "MARKETING"
25  ],
26  "use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
27  "production_message_sample": "lorem ipsum",
28  "opt_in_image_urls": [
29    "https://testbusiness.com/images/image1.jpg",
30    "https://testbusiness.com/images/image2.jpg"
31  ],
32  "opt_in_type": "VERBAL",
33  "message_volume": "2000",
34  "additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
35  "tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
36  "status": "TWILIO_APPROVED",
37  "rejection_reason": null,
38  "error_code": null,
39  "edit_expiration": null,
40  "edit_allowed": null,
41  "rejection_reasons": null,
42  "resource_links": {
43    "customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44    "trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
45    "channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
46  },
47  "url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
48  "external_reference_id": "abc123xyz567"
49}

Edit one TFV request

POST https://messaging.twilio.com/v1/Tollfree/Verifications/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<HH>

required

The unique string to identify Tollfree Verification.

Pattern: ^HH[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

businessNamestring

Optional

The name of the business or organization using the Tollfree number.

businessWebsitestring

Optional

The website of the business or organization using the Tollfree number.

notificationEmailstring

Optional

The email address to receive the notification about the verification result. .

useCaseCategoriesarray[string]

Optional

The category of the use case for the Tollfree Number. List as many are applicable..

useCaseSummarystring

Optional

Use this to further explain how messaging is used by the business or organization.

productionMessageSamplestring

Optional

An example of message content, i.e. a sample message.

optInImageUrlsarray[string]

Optional

Link to an image that shows the opt-in workflow. Multiple images allowed and must be a publicly hosted URL.

optInTypeenum<string>

Optional

Describe how a user opts-in to text messages.

Possible values:

VERBALWEB_FORMPAPER_FORMVIA_TEXTMOBILE_QR_CODEIMPORTIMPORT_PLEASE_REPLACE

messageVolumestring

Optional

Estimate monthly volume of messages from the Tollfree Number.

businessStreetAddressstring

Optional

The address of the business or organization using the Tollfree number.

businessStreetAddress2string

Optional

The address of the business or organization using the Tollfree number.

businessCitystring

Optional

The city of the business or organization using the Tollfree number.

businessStateProvinceRegionstring

Optional

The state/province/region of the business or organization using the Tollfree number.

businessPostalCodestring

Optional

The postal code of the business or organization using the Tollfree number.

businessCountrystring

Optional

The country of the business or organization using the Tollfree number.

additionalInformationstring

Optional

Additional information to be provided for verification.

businessContactFirstNamestring

Optional

The first name of the contact for the business or organization using the Tollfree number.

businessContactLastNamestring

Optional

The last name of the contact for the business or organization using the Tollfree number.

businessContactEmailstring

Optional

The email address of the contact for the business or organization using the Tollfree number.

businessContactPhonestring<phone-number>

Optional

The E.164 formatted phone number of the contact for the business or organization using the Tollfree number.

editReasonstring

Optional

Describe why the verification is being edited. If the verification was rejected because of a technical issue, such as the website being down, and the issue has been resolved this parameter should be set to something similar to 'Website fixed'.

Edit a TFV Request

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateTollfreeVerification() {
11  const tollfreeVerification = await client.messaging.v1
12    .tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({
14      additionalInformation:
15        "See our privacy policy at www.example.com/privacypolicy",
16      editReason: "Updated the ProductionMessageSample",
17      messageVolume: "1,000",
18      optInImageUrls: [
19        "https://example.com/images/image1.jpg",
20        "https://example.com/images/image2.jpg",
21      ],
22      optInType: "VERBAL",
23      productionMessageSample:
24        "Get 10% off when you save this coupon: https://bit.ly/owlcoupon",
25      useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],
26      useCaseSummary:
27        "This number is used to send out promotional offers and coupons to the customers of Owl, Inc.",
28    });
29
30  console.log(tollfreeVerification.sid);
31}
32
33updateTollfreeVerification();

Response

1{
2  "sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "regulated_item_sid": null,
5  "customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "trust_product_sid": null,
7  "status": "PENDING_REVIEW",
8  "date_created": "2021-01-27T14:18:35Z",
9  "date_updated": "2021-01-27T14:18:36Z",
10  "business_name": "Owl, Inc.",
11  "business_street_address": "123 Main Street",
12  "business_street_address2": "Suite 101",
13  "business_city": "Anytown",
14  "business_state_province_region": "AA",
15  "business_postal_code": "11111",
16  "business_country": "US",
17  "business_website": "http://www.company.com",
18  "business_contact_first_name": "firstname",
19  "business_contact_last_name": "lastname",
20  "business_contact_email": "email@company.com",
21  "business_contact_phone": "+11231231234",
22  "notification_email": "support@company.com",
23  "use_case_categories": [
24    "TWO_FACTOR_AUTHENTICATION",
25    "MARKETING"
26  ],
27  "use_case_summary": "This number is used to send out promotional offers and coupons to the customers of Owl, Inc.",
28  "production_message_sample": "Get 10% off when you save this coupon: https://bit.ly/owlcoupon",
29  "opt_in_image_urls": [
30    "https://testbusiness.com/images/image1.jpg",
31    "https://testbusiness.com/images/image2.jpg"
32  ],
33  "opt_in_type": "VERBAL",
34  "message_volume": "1,000",
35  "additional_information": "See our privacy policy at www.example.com/privacypolicy",
36  "tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
37  "rejection_reason": null,
38  "error_code": null,
39  "edit_expiration": null,
40  "edit_allowed": null,
41  "rejection_reasons": null,
42  "resource_links": {},
43  "url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44  "external_reference_id": null
45}

Delete record of one TFV request

DELETE https://messaging.twilio.com/v1/Tollfree/Verifications/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<HH>

required

The unique string to identify Tollfree Verification.

Pattern: ^HH[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete one TFV request record

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteTollfreeVerification() {
11  await client.messaging.v1
12    .tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .remove();
14}
15
16deleteTollfreeVerification();