Get started with toll-free verification using the API

TFV requests with Twilio require your business to have a Trust Hub Primary Customer Profile. A Primary Customer Profile is also known as a Primary Business Profile.

1. Open the Trust Hub in the Twilio Console.
2. Create your Trust Hub Primary Customer Profile.
3. When you reach the Business Information step of the Create Profile workflow, set the value of Select business identity.
   • If you plan to use Twilio in a product you sell to customers, Twilio considers you an ISV. Choose ISV Reseller or Partner.
   • If you plan to use Twilio to communicate directly with customers or staff, Twilio considers you a direct customer. Choose Direct Customer.
4. At the Notification settings step, provide an email address at which Twilio can contact you about the status of your request.
5. After you submit your request to Twilio, Twilio reviews it and sends a notification of approval or rejection to the email address you provided.
6. After you receive notification of your profile status, open the Trust Hub in the Twilio Console. Twilio approved your Primary Customer Profile.
   Your Profile Details page displays a Status of Twilio-Approved.
7. Copy the Business Profile SID value of your parent account. This SID begins with BU followed by 32 hexadecimal digits. To Create a TFV request, you need this Business Profile SID. The Create TFV resource names this parameter CustomerProfileSid. These refer to the same value.

Trust Hub Customer Profiles can link to a parent account or a subaccount. Think of a parent account as the main organization and subaccounts as departments or subsidiaries. To create a parent account, you must use the Twilio Console. You can create subaccounts using the Twilio TrustHub API.

To keep customers separate, production ISV parent accounts should link Trust Hub customer profiles to subaccounts.

To use an NANP toll-free phone number for messaging, submit a verification request for the related business. As you have an approved Primary Customer Profile, your request only needs the parameters for the TFV itself.

1. Make a POST request to the https://messaging.twilio.com/v1/Tollfree/Verifications resource.
   All parameters for this request are request body parameters.

   Click to review the request body parameters
   Submit a TFV Request using your Customer Profile

   Report code block

   Copy code block

   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 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
   
   36
   createTollfreeVerification();

   Twilio reviews TFV requests within three business days.

2. Check the status of your TFV request.

   Check one TFV request

   Report code block

   Copy code block

   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 fetchTollfreeVerification() {
   11
     const tollfreeVerification = await client.messaging.v1
   12
       .tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
   13
       .fetch();
   14
   
   15
     console.log(tollfreeVerification.sid);
   16
   }
   17
   
   18
   fetchTollfreeVerification();

   If you don't have your TFV request SID, use the API to get a list of TFV SIDs for your related toll-free number.

   Click to review the get list of TFV SIDs API request

3. Look for the status property in the response.

   Response to a Check TFV request

   Copy code block

   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
   }

   If Twilio approved your TFV request, status reads as "status": "TWILIO_APPROVED". The verified toll-free number can send Application to Person (A2P) SMS messages with minimal traffic filtering.

If you don't have a Trust Hub Customer Profile, you can create one at the same time as submitting your TFV request. To learn how to perform both tasks at once, see this variation on the Create TFV request.

If Twilio rejected your TFV request, your check request displays "status": "TWILIO_REJECTED". The toll-free number isn't verified and you can't use it to send messages. To review common rejection reasons, see Why Was My Toll-Free Verification Rejected? in the Twilio Help Center.

If the response includes "edit_allowed": true, you can resubmit your TFV request.

1. Check the status of your TFV request.

2. In the response, find two properties:

   • The edit_allowed property
     • If this value is set to true, you can edit the TFV request and resubmit it.
     • You must submit the TFV request before the timestamp provided in the edit_expiration property. Twilio sets this property value to seven days from the initial request. After that date, the TFV request expires and you need to create another.
   • The rejection_reasons property array
     • This array returns the list of reasons why Twilio rejected your TFV as a human-readable reason and a code that links to details on this error.

3. To correct any errors in your TFV request, use the Edit a TFV Request resource.

   Edit a TFV Request

   Report code block

   Copy code block

   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 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
   
   33
   updateTollfreeVerification();

   Response

   Copy 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
   }

4. Check your TFV request status.

If you can't edit your TFV request, delete it. The delete resource requires the SID for the Verification record to delete. This SID starts with HH followed by 32 other hexadecimal digits.

If you don't have your TFV request SID, use the API to get a list of TFV SIDs for your related toll-free number.

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 listTollfreeVerification() {
11
  const tollfreeVerifications =
12
    await client.messaging.v1.tollfreeVerifications.list({
13
      tollfreePhoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
      limit: 20,
15
    });
16

17
  tollfreeVerifications.forEach((t) => console.log(t.sid));
18
}
19

20
listTollfreeVerification();

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 deleteTollfreeVerification() {
11
  await client.messaging.v1
12
    .tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .remove();
14
}
15

16
deleteTollfreeVerification();