Understanding Your Regulatory Bundles’ Compliance Status: The Evaluations API
Time to read: 4 minutes
Today we are excited to announce that the Phone Numbers Evaluations API resource has moved to public beta.
As you may know, Phone Numbers with compliance requirements for documentation require Regulatory Bundles. With the Evaluations API, Twilio makes it possible to understand whether a Regulatory Bundle Evaluation passed or failed and provide the specific field-level failure reasons. The granular failure reasons provide specific call-to-actions for you or your customers to fix before a submission can be accepted, making it faster and easier for you to create and manage bundles.
To provision a phone number with regulatory compliance requirements, you must follow local requirements of the country or territory, providing End-User information and Supporting Documents. To do this you must create a Regulatory Bundle and bundle together all of the End-User information, Supporting Document(s), and Address(es).
Once a Regulatory Bundle has been built, submit it for Evaluation to ensure you’ve satisfied a Regulation. Twilio’s team reviews the bundle within 48 business hours, and you will receive an email when the status of the Regulatory Bundle changes.
Using the Evaluations Public API resource, you will be able to:
- For a given
Bundle SID, get a historical list of evaluations for the Regulatory Bundle, including the current Bundle status (compliant or noncompliant). If the Bundle is not compliant, you will get a list of the reason(s) it was deemed not compliant (e.g., “The Last Name on the Government-issued ID must match the Last Name entered. Please double check the Last Name on the Government-issued ID matches the Last Name typed in.”)
- Trigger new evaluations for a specified Regulatory Bundle and its related phone numbers. Similarly, you will receive a list of failure reasons.
Frequently asked questions about the Evaluations API
Here’s a summary of why we’re introducing the Evaluations API and how this can benefit you.
Regulatory compliance is about Knowing Your Customer (KYC) – many countries' and territories’ telecom regulators want to know the end-user who is answering voice calls or receiving messages.
Regulators want to know who the end-users are due to potential national threats, to prevent spam and fraud, and to generally protect the phone number as a natural resource used as an identifier of an end-user. If you have not provided the necessary regulatory information and supporting documentation for your numbers in regulated geographies, your numbers are at risk of being disconnected.
The diagram below demonstrates the process of bringing a Twilio phone number into compliance. Essentially, you:
- Understand what’s required by local regulators
- Collect documentation from the End-User, then create a Regulatory Bundle and submit it for review
- Wait for the Bundle to be reviewed (Evaluation)
- Once the Regulatory Bundle has been Approved, assign the Bundle to phone number(s)
Regulatory Bundles are constructed with Item Assignments of End-Users and Supporting Documents with Addresses for regulatory compliance.
The Evaluations resource is aimed to help our developer customers build their own web portal experience that can serve their customers in an automated way. This resource will allow you to onboard numbers and end-users faster and to have more control over the data flow.
In February, we incorporated a change to the IncomingPhoneNumbers API to require a BundleSID (identification for your Regulatory Bundle) when provisioning a Phone Number in a country that requires regulatory information and documentation. The Evaluations API resource will now make it easier to understand the status of the Regulatory Bundle, particularly in light of that change.
We’re excited to introduce you to the Evaluations API resource! We anticipate that our customers who use it will see:
- A decrease in the time it takes to diagnose an issue with the Regulatory Bundle evaluated against a Regulation
- Reduced time from Regulatory Bundle submission to approval due to the ability to address issues more quickly
- A decrease in the percentage of Regulatory Bundles that are not approved
- Fewer support tickets from their end users
It’s important to know whether your existing phone numbers are compliant with regulatory requirements so they stay connected and you can utilize them going forward. After using the Evaluations resource, if you discover any of your numbers are noncompliant, update your Bundle and submit it again for review. Once your Bundle is approved, you can assign it to the phone number(s).
For more information, here are some links to documentation and other helpful resources:
REST API Documentation
Getting Started Pages
- Create a new Regulatory Bundle with v2 RC APIs
- Create a new Regulatory Bundle with Twilio’s web Console
We know phone number regulatory compliance can be a challenge. We’re here to partner with you and to provide solutions that will make it easier for you to work with your customers on their compliance status.
Patrick Loomis is a Product Manager on the Phone Numbers team. He loves mining for data, optimizing workflows, and building overly complex spreadsheets, even for vacations. He can be reached at ploomis [at] twilio.com.
From APIs to SDKs to sample apps
API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
The latest ebooks, industry reports, and webinars
Learn from customer engagement experts to improve your own communication.
Twilio's developer community hub
Best practices, code samples, and inspiration to build communications and digital engagement experiences.