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 with 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. To learn more, see Required Information for Toll-Free Verification in the Twilio Help Center.

To support changes to toll-free messaging policy when submitting a TFV request, include additional metadata about your business. To avoid rejection and accelerate vetting, provide this information before its required. To learn more, see Toll-Free Verification Policy for Collecting Business Registration Number in the Twilio Help Center.

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
   (information)

   Info

   Note about Campaign Verify parameters: The VettingId and VettingProvider parameters shown in this example are REQUIRED if your organization is a 527 political organization and if you are registering for the POLITICAL_ELECTION_CAMPAIGNS use case. For all other organizations and use cases, these parameters are optional. See the Campaign Verify section for details.

   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: "privacy policy is geo-locked to NAMER region",
   14
         businessName: "Owl, Inc.",
   15
         businessWebsite: "http://www.example.com",
   16
         customerProfileSid: "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   17
         messageVolume: "10",
   18
         notificationEmail: "support@example.com",
   19
         optInImageUrls: [
   20
           "https://example.com/images/image1.jpg",
   21
           "https://example.com/images/image2.jpg",
   22
         ],
   23
         optInType: "VERBAL",
   24
         productionMessageSample: "lorem ipsum",
   25
         tollfreePhoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   26
         useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],
   27
         useCaseSummary:
   28
           "This number is used to send out promotional offers and coupons to the customers of Owl, Inc.",
   29
         vettingId:
   30
           "cv|1.0|mno|tfree|b344a16f-b435-4a39-bf91-df9b8e4e0a0d|E5eh-rOPHCr_lrgHDYEZP45FzuJSHS1fkFTmVPD8GQ4",
   31
         vettingProvider: "CAMPAIGN_VERIFY",
   32
       });
   33
   
   34
     console.log(tollfreeVerification.sid);
   35
   }
   36
   
   37
   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": "privacy policy is geo-locked to NAMER region",
   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
   
   46
       // New response fields for the 2026 update
   47
      "business_registration_number": "123456789",
   48
      "business_registration_authority": "EIN",
   49
      "business_registration_country": "US",
   50
      "doing_business_as": "Other Company",
   51
      "business_type": "PRIVATE_PROFIT",
   52
      "opt_in_confirmation_sample": "Opt in sample message",
   53
      "help_message_sample": "Help sample",
   54
      "privacy_policy_url": "http://www.example.com/privacy",
   55
      "terms_and_condition_url": "http://www.example.com/terms",
   56
      "age_gated_content": false,
   57
      "opt_in_keywords": "STOP",
   58
      
   59
      // New response fields for CV Token update
   60
      "vetting_id": "cv|1.0|mno|tfree|b344a16f-b435-4a39-bf91-df9b8e4e0a0d|E5eh-rOPHCr_lrgHDYEZP45FzuJSHS1fkFTmVPD8GQ4",       
   61
      "vetting_provider": "CAMPAIGN_VERIFY",
   62
      "vetting_id_expiration": "2027-01-31T23:59:59Z"
   63
   
   64
   }

   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://example.com/images/image1.jpg",
   31
       "https://example.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
     "business_registration_number": "123456789",
   46
     "business_registration_authority": "EIN",
   47
     "business_registration_country": "US",
   48
     "business_type": "PRIVATE_PROFIT",
   49
     "business_registration_phone_number": "+13023334444",
   50
     "doing_business_as": "Toms Widgets",
   51
     "age_gated_content": false,
   52
     "help_message_sample": "For help, reply HELP or visit our website.",
   53
     "opt_in_confirmation_message": "Thank you for opting in!",
   54
     "opt_in_keywords": [
   55
       "START"
   56
     ],
   57
     "privacy_policy_url": "https://www.example.com/privacy",
   58
     "terms_and_conditions_url": "https://www.example.com/terms",
   59
     "tollfree_phone_number": "+18003334444",
   60
     "vetting_id": null,
   61
     "vetting_id_expiration": null,
   62
     "vetting_provider": null
   63
   }

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

Campaign Verify is a secure, non-partisan verification solution for US political organizations who wish to engage with voters via toll-free messaging.

All organizations sending political communications on behalf of a federal, state, or local political campaign must be verified by Campaign Verify to complete toll-free verification for political use cases.

A Campaign Verify token is REQUIRED for toll-free verification when:

1. Your organization is a 527 political organization
2. And you select POLITICAL_ELECTION_CAMPAIGNS as a use case category.

Without a valid CV token, your toll-free verification will be rejected if you meet these criterias.

Verification involves submitting information about your political organization to Campaign Verify, as well as verifying your identity as an authorized person associated with the political organization.

1. Visit Campaign Verify to begin the verification process
2. Complete identity verification and provide required organization information
3. After approval, Campaign Verify issues you a CV token
4. Provide this CV token during TFV registration using the VettingId and VettingProvider parameters

A full CV token is composed of 6 pipe (|) delimited fields, for example:

..cv|1.0|mno|tfree|b344a16f-b435-4a39-bf91-df9b8e4e0a0d|E5eh-rOPHCr_lrgHDYEZP45FzuJSHS1fkFTmVPD8GQ4

When submitting your TFV request:

• Set VettingProvider to CAMPAIGN_VERIFY
• Set VettingId to your full CV token (all 6 fields, including the pipes)
• The token is case-sensitive and must match the format provided by Campaign Verify exactly

• CV tokens expire after a period of time (expiration date provided by Campaign Verify)
• The vetting_id_expiration field in the TFV response shows when your token expires
• The CV token must be registered for the organization entity listed on the token. If your TFV request is rejected with an error code related to Campaign Verify, check that the token is valid and registered to the correct organization.
• If you are ISV and multiple customers sending political messaging, each customer needs a separate CV token.
• To update an expired token, edit your existing TFV request with a new CV token