Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Pilot REST API: Number Regulatory Compliance Getting Started

The Number Regulatory Compliance REST APIs are currently in a Public Pilot state. The new Regulatory Compliance APIs are under active development and will be debuted in Public Beta in September.

The Pilot Regulatory Compliance APIs will be deprecated when the new Regulatory Compliance APIs move to Public Beta. Please be mindful when building your application.

For access, please fill out the Regulatory Compliance pilot request form.

Getting Started Tutorial

The tutorial described below will walk through the Twilio REST API sequence of requests to ensure your phone numbers are in compliance. In order to become compliant, you must apply for a Phone Number Type with an Identity of end-user information and supporting Documents that satisfy the phone number type's regulatory requirement (Phone Numbers Regulatory Compliance Guidelines).

Below is a list of concepts that are important to understand before beginning the number compliance workflow.

  • Identity: An Identity is an act of applying for a phone number type with an Identity of the end-user who will be using the phone number(s). An end-user's Identity can be either business or individual.
  • Documents: Documents support the application and provide proof of end-users information.
  • Proof of Address: An application of phone number type with end-user information has supporting Documents, some of which have an address on them. If the phone number type application requires a Proof of Address, then a mapping between an Address object and a supporting Document can be made to satsify the regulatory compliance requiement.

The following Twilio REST API resources will be used in sequence during the Phone Number Regulatory Compliance workflow:

  1. Apply for a Phone Number Type with an Identity detailing the end-user information who will be answering the phone number.
  2. Upload supporting Documents to an Identity.
  3. Create or use an existing Address, if an Address is required.
  4. Create a Proof of Address with a supporting Document and the Address
  5. Link the Phone Numbers using Incoming Phone Numbers to ensure your phone numbers are compliant

Apply for a Phone Number Type with an Identity of End-User Information

If the number you wish to provision to your account or your customer's subaccount for use requires an application with an Identity of end-user information and supporting Documents, the first step is to apply for a phone number type and provide details of the end-users Identity who will be answering the phone number.


        Upload Supporting Documents

        After you have applied for a phone number type with an Identity of end-user information, you can begin to upload supporting Documents to the Documents subresource that hangs off of the Identity.

        The supporting Documents are queued for a Twilio regulatory reviewer to verify the legitimacy of the Documents and will pass or fail the Document based on its veracity. If the number only requires a Document proving Identity, then you can map the phone number using the IncomingPhoneNumbers API resource to ensure that the number is in compliance once the supporting Documents have passed.


              Creating an Address

              If the phone number type application requires both supporting Documents for an end-user's Identity, as well as a Proof of Address, the next step would be to either create a new Addresses object or to use one that has already been validated.


                    Linking a Proof of Address to a Document

                    Once you have the validated Addresses object, the next step will be to link the supporting Document that details the address with the Addresses object that was validated as a real address.


                          Ensure Phone Number's Compliance

                          After the phone number type application has been passed, the next step is to map your out-of-compliance phone number with the Identity SID of the passed application and the Address SID if a Proof of Address is required.

                                Rate this page:

                                Need some help?

                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.