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.
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
- 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:
- Apply for a Phone Number Type with an Identity detailing the end-user information who will be answering the phone number.
- Upload supporting Documents to an Identity.
- Create or use an existing Address, if an Address is required.
- Create a Proof of Address with a supporting Document and the Address
- 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.
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.
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.
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.
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.