Toll-Free Verification Compliance Embeddable Onboarding Guide

The Compliance Embeddable is a white-label embed offering designed to seamlessly integrate into an Independent Software Vendor's (ISV) existing portal or web application. Your team can use this embed to allow your end customers to submit toll-free verification requests through self-service. Twilio manages the questions in the UI, but there is no Twilio branding visible. Your team can customize the UI to match your design standards, including color palette and typeface.

The TFV Compliance Embeddable supports your end customers to resume incomplete verification submissions, and previously rejected verifications can be edited and resubmitted directly within the embeddable experience. This eliminates the need for manual intervention through the API or Console when handling rejected submissions. Additionally, parameters included in the upcoming Feb 17th program policy changes around Business Registration Number and CampaignVerify Token for Political messaging are supported.

Expand image

The Compliance Embeddable requires two integrations:

1. Server-side integration to invoke the Twilio Initialize ComplianceInquiry APIs to initialize the ComplianceInquiry and get back a session token and inquiry ID.
2. Client-side integration to embed the ComplianceInquiry UI in your existing web application using an iframe, utilizing the returned session token and inquiry ID.

This onboarding guide provides a step-by-step walkthrough on how to integrate the Compliance Embeddable into an ISV's web application, allowing self-service Toll-Free Verification for your end customers.

• Server-side integration
• Client-side integration

If you have questions about this product, check out the Compliance Embeddable FAQ or contact us at via the Twilio Help Center.

To follow these steps, you must have a Trust Hub Primary Customer Profile for a business with the business identity set to ISV/Reseller. See Create a Trust Hub Primary Customer Profile to learn more.

The Compliance Embeddable's data collection process is secured via server-side authentication and is triggered by a server-side API call. This API call initializes a ComplianceInquiry and returns a token, which you can then pass to your web client to authenticate into a submission flow.

To initialize a ComplianceInquiry for a Toll-Free Verification, make an HTTPS request to the following API:

POST https://trusthub.twilio.com/v1/ComplianceInquiries/Tollfree/Initialize

This call must be authenticated using Twilio's REST API credentials where the account SID is either your primary Twilio Account SID or a subaccount SID. All of the parameters except for TollfreePhoneNumber and NotificationEmail are optional. If this data is provided, it will automatically appear pre-filled in the subsequent forms in the user's UI.

The Initialize API supports both new submissions and resumption of existing inquiries. When you call the API for a toll-free number with an existing incomplete or rejected inquiry, the API returns the same inquiry_id with a new inquiry_session_token. Previously entered data is retained and pre-populated in the form.

For rejected verifications eligible for resubmission, calling the Initialize API allows your end customer to edit their submission and correct any issues. The embeddable displays the previous data, enabling targeted corrections rather than requiring complete re-entry.

If a verification is already in progress, approved, or rejected with an error that cannot be resubmitted, the API returns an error response. See the Error responses table for details.

Add the following --data-urlencode parameters to the request body:

Note: Data validations will be performed on these fields. Refer to our Toll-Free Verification Guide for detailed validation rules. Additionally, you may sign up for status change notifications for Toll-Free Verification via Twilio Event Streams.

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 createComplianceTollfreeInquiry() {
11
  const complianceTollfreeInquiry =
12
    await client.trusthub.v1.complianceTollfreeInquiries.create({
13
      businessName: "Twilio",
14
      businessRegistrationAuthority: "EIN",
15
      businessRegistrationCountry: "US",
16
      businessRegistrationNumber: "12-3456789",
17
      businessType: "PRIVATE_PROFIT",
18
      businessWebsite: "https://www.twilio.com",
19
      notificationEmail: "dean@twilio.com",
20
      tollfreePhoneNumber: "+800445566",
21
    });
22

23
  console.log(complianceTollfreeInquiry.inquiryId);
24
}
25

26
createComplianceTollfreeInquiry();

1
{
2
  "inquiry_id": "inq_aaaaaaaaaaaaaaaaaaaaaaaa",
3
  "inquiry_session_token": "new.session.token",
4
  "registration_id": "tri1.us1.trusthub.ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.tollfree.PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "url": "https://trusthub.twilio.com/v1/ComplianceInquiries/Tollfree/Initialize"
6
}

A successful request will return a JSON response body with the following attributes:

API Error Responses and their meaning

Valid values for the UseCaseCategories parameter include:

• TWO_FACTOR_AUTHENTICATION
• ACCOUNT_NOTIFICATIONS
• CUSTOMER_CARE
• DELIVERY_NOTIFICATIONS
• FRAUD_ALERT_MESSAGING
• HIGHER_EDUCATION
• MARKETING
• POLLING_AND_VOTING
• PUBLIC_SERVICE_ANNOUNCEMENT
• SECURITY_ALERT
• POLITICAL_ELECTION_CAMPAIGNS

Multiple categories can be provided if applicable to your use case.

After initializing a ComplianceInquiry, you may embed the ComplianceInquiry UI in your website using the TwilioComplianceEmbed React client.

Install the package in your React project using your preferred package manager.

NPM:

npm install @twilio/twilio-compliance-embed

Yarn:

yarn add @twilio/twilio-compliance-embed

The ComplianceInquiry UI can be embedded into your site with the following code snippet:

1
import * as React from "react";
2
import { TwilioComplianceEmbed } from "@twilio/twilio-compliance-embed";
3

4
const ComplianceInquiry = () => {
5
  return (
6
    <TwilioComplianceEmbed
7
      inquiryId='<your inquiry id from calling the Initialize ComplianceInquiry API>'
8
      inquirySessionToken='<your inquiry session token from calling the Initialize ComplianceInquiry API>'
9
    />
10
  );
11
};

The ComplianceInquiry UI may take a few seconds to load and render.

We currently do not provide native support for integrations with frontend frameworks other than React. However, we are releasing a hosted version of this product soon, so customers using non-React frameworks or older versions of React can also use the Compliance Embeddable. Check back on this page for more details in the coming months.

How long does the session token last? The inquiry_session_token expires 1440 minutes (24 hours) after creation. If the token expires, call the Initialize API again to get a new token. The inquiry_id remains the same for existing inquiries.

What happens if an end customer closes their browser during submission? The data entered up to that point is saved. When they return and you call the Initialize API for the same toll-free number, they can resume from where they left off.

Can I customize the look and feel of the embeddable? Yes. Request a custom theme through the FAQ instructions and use the returned ThemeSetId in your Initialize API calls.

What business registration authority should US businesses use? US businesses should use EIN (Employer Identification Number) as the BusinessRegistrationAuthority. The BusinessRegistrationNumber should be the 9-digit EIN, optionally formatted with a hyphen (for example, 12-3456789 or 123456789).