Self-Service KYC Example TFN and Shaken/STIR Submission

Self-Service KYC Example: Toll-Free Number Submission

In a previous blog post, Self-Service KYC and User Authentication and Identity with Twilio Trust Hub, we took a closer look at Twilio Trust Hub and what advanced communications products it enables – such as US A2P 10DLC for messaging and SHAKEN/STIR for voice, to name a couple. We also looked at ways that user onboarding can be enhanced with Twilio’s Verify and Lookup APIs.

While that post was meant to be a high-level overview of the various KYC endpoints and their capabilities, in part 2 we’ll take a look at a practical demonstration. In this post, we will build a functional Next.js application that collects the necessary user and business information needed for verifying a US Toll-Free number for SMS messaging.

Prerequisites

Before you can build this KYC verification app, you’ll need a few things:

• A Twilio Account (if you don’t have one yet, you can sign up for free here)
• Have at least 1 unverified Toll Free number in your account (we’ll show you how to buy one in a second, if you haven’t yet)

Resources

You can find and view the source code for this example on GitHub. Here’s the architecture of the app we’ll build together:

A user will be able to submit their Toll-free information to your app, and your backend will handle all of the API calls to verify it.

Get started with the KYC Node.js application

Step 1: Clone Project

Clone the project from Github using the following command gh repo clone mmenschig/twilio-kyc , or download it directly from the project page.

Step 2: Add your Twilio account credentials

Edit the sample.env file and add your Account SID and Auth Token as parameters. You can find them in your Console.

Now, rename the file to .env(removing the sample prefix) using cp .sample.env .env

Step 3: Buy a US Toll-Free phone number

Next, we will need to purchase a US Toll-Free phone number that we will use to verify and send SMS messages with.

Log in to your Twilio Console. Head to Phone Numbers > Manage > Buy a Number.

Make sure Country is set to +1 United States and under the Advanced Search dropdown, under Number Type make sure Toll-Free is the only option selected.

Click the blue Search button when ready.

You will be presented with a list of available toll-free numbers. Click Buy on the one you wish to purchase.

Next, you will see a confirmation pop-up, where you can review your selection before purchasing.

You will also see information regarding Toll-free messaging verification. Specifically, ‘ This phone number will not be able to send messages until the verification has been approved. Learn more about toll free verification. ’

Normally, verification is done via the Console or API. As we will explore further in this post, our Next.js app will demonstrate how to verify your toll-free number via our API!

Click the blue Buy phone number button when you are ready.

Before we move on, in your Console, head to Phone Numbers > Manage > Active Numbers to see your recently purchased toll-free number. You can use the filter to search for the country and prefix (e.g., +1844) to display the number.

Under the phone numbers’ Active Configuration you should see Toll free verification required next to Messaging. This indicates your Toll-free number is unverified.

Step 4: Run the Twilio-KYC app locally

Using your terminal, navigate to thetwilio-kyc project directory and launch the app using npm run dev.

Confirm the server has started, then head to your browser and navigate to localhost:3000. Here you should see our app’s main page, a web form we will use to input all the necessary information required to verify our toll-free number from Step 3, above.

Step 5: Complete all fields on Twilio-KYC’s web form

This webform’s fields are mapped to specific parameters that are included in the toll-free verification api request. Let’s review each section:

• Business Information - Here the Legal Business Name (e.g., Twilio, Inc.) and valid business URL (e.g., www.twilio.com) are required.
• Business Address - The Legal Business address (Valid US address, no P.O. box)
• Business Contact - Contact information of authorized representative of the business. (Note: Phone number may not be a Twilio number)
• Use Case - Information about the planned use case of the Toll-Free number. Including the category, opt-in information, sample message, etc. (all are required).
• Select Phone Number to Register - The app will query your Twilio account’s available toll-free phone numbers. Select the one you wish to verify with the above information, here you will select the phone number you purchased in Step 3.
• Notifications - enter an email address to receive notifications about updates to the status of your toll-free verification request.

Step 6. Submit for verification

Once you have completed all of the fields you are now ready to submit! The application will pass all the required information to Twilio’s Toll-Free verification API endpoint.

We can confirm the submission was successful and the Toll-Free number verification is now Pending in the Console under the Phone Numbers > Manage > Active Numbers screen. The Active Configuration should now show Pending instead of Toll free verification required.

Success - you have just submitted your Toll-Free verification via API!

Conclusion.

You’ve now seen how our demo twilio-kyc app is able to verify a toll-free number by using Twilio’s Trusthub APIs to submit all necessary KYC information. Now, when building toll-free phone number verification into your own app’s flow, you’ll have a better idea of the sequence of api calls and necessary parameters to pass to Twilio. Give it a shot and let us know what you think. We can’t wait to see what you build!

Additional resources

• Self-Service KYC and User Authentication and Identity with Twilio Trust Hub
• Developer Guide to Toll-Free Verification
• Toll-Free Verification API Onboarding Guide
• Toll-Free Message Verification for US/Canada

Casey Runnells is a Senior Solutions Engineer at Twilio and is passionate about helping businesses grow and redefine their strategies around enhanced customer communication and data. You can reach Casey at crunnells [at] twilio.com

Marian Menschig is a Senior Solutions Engineer at Twilio and enjoys finding new ways to help customers explore and unlock previously hidden use cases using the latest technologies available. You can reach Marian at mmenschig [at] twilio.com