API Getting Started: Compliance Information Update

This guide is meant to serve developers who use Twilio's Regulatory Compliance APIs to build their own application that serves. By following this Getting Started guide, you as a developer can implement a self-service mechanism for your customers to update their compliance information without you manually having to communicate with them.

• Copies Resource
• Replace Items Resource

A new parameter, ValidUntil, is being added to the Bundles resource. This new parameter is applied to a Bundle in the twilio-approved state but will be transitioned to a twilio-rejected state unless the compliance information is updated.

The first step is to know when a Regulation is updated that will create a call-to-action for you to update the compliance information of your affected Bundles. To do this, you should have a status callback webhook enabled for all of your Bundles. An email alias is required, so all information will always be sent to the email assigned to any affected Bundle. Once the Bundles have been identified, you will create a copy to begin updating all compliance information required. After updating the compliance information, submit the Bundle to Twilio for review. Once Twilio reviews and approves the newly updated compliance information, you will then replace all of the newly updated items to the original Bundle. This prevents you from having to reassign any dependencies such as Phone Numbers to a new Bundle. After the items have been replaced, delete the Bundle Copy to ensure you have a clean reference moving forward. Once completed, the Bundle will no longer have a ValidUntil date and everything is up to current compliance.

1. Find all Bundles that require information to be updated/added
2. Create a Bundle Copy to begin updating/adding information
3. Run an Evaluation to find the exact incorrect or missing piece of information
4. Retrieve list of Supporting Document(s) and End-User assigned to the Bundle
5. Present and update Supporting Document(s) - [optional, if needs updating]
6. Present and update End-User - [optional, if needs updating]
7. Submit Bundle Copy for review
8. Twilio reviews & approves Bundle
9. After approval, replace Item Assignments from Bundle Copy to original Bundle
10. Delete Bundle Copy

Below is an API sequence diagram illustrating the sequence of requests that will be performed within this Getting Started page of updating compliance information. The domain objects are abbreviated for brevity purposes.

Expand image

If you have configured the status callback webhook parameter on the Bundle, you will receive the following webhook request. Notice that there is a new field in the response; ValidUntil that acts as a date parameter when the Bundle will be moved to a twilio-rejected status unless the compliance information is updated. If you do not remember how to configure your status callback webhook, please refer to the Bundles Public API resource page. There is a table within the page that details the status callback parameters.

Besides the status callback webhooks and the email, your customers will need to filter all of their Bundles every time their job is to update compliance information. To find all of the Bundles that need their compliance information updated, Query the list of Bundles and apply the ValidUntil filter along with order by date descending.

After receiving the initial status callback webhook request, the next step is to take the Bundle SID from webhook request which included the valid_until parameter and create a new Copy of the Bundle. The new Bundle Copy will make a new instance of the Bundle and all of the Item Assignments consisting of an End-User and Supporting Document(s). These instances will allow you to update information while the original Bundle continues to stay in a twilio-approved compliance state that allows you to continue provisioning new Phone Numbers.

Note: By performing this operation via Public API, you are opting in to the full API lifecycle after the Bundle Copy has been approved. If the Bundle Copy operation is performed via Twilio's Console, the Bundle will opt-in to automated lifecycle transitioning after Twilio has reviewed and approved the Bundle Copy. For API operation, it is up to you to coordinate that lifecycle transition and management.

After understanding that a given Bundle will be valid until an expiration date and then creating a Bundle Copy, the next step is to understand what exactly is missing from the Bundle Copy. To retrieve the exact requirements of what information passed versus not, send a new create request to the Evaluations subresource of the Bundle instance. The response will provide the necessary information to add/remove any compliance information enforced by the new requirements of the Regulation.

Go through the necessary steps to update the newly created Bundle Copy by either adding/removing information to the End-User and/or Supporting Document(s) assigned. Firstly, Retrieve a list of all Item Assignments from the Bundle Copy. Next step is to fetch the End-User instance (IT prefix) and the Supporting Document instance(s) (RD prefix). Analyzing the difference between the previously ran Evaluation against the End-User and Supporting Document(s) instances will allow you to see the exact parameters that need to be updated.

If the Evaluation that you previously requested determines that one or many Supporting Documents are missing information given the new requirements, you must update that information. First, show the user the Supporting Document instance and inform them exactly what is missing per the Evaluation. Allow the user to enter the information required and send an update operation for that instance. If there are more Supporting Documents that failed the Evaluation, repeat this step until finished.

If the Evaluation that you previously requested determines that the End User is missing information given the new requirements, you must update that information. First, show the user the End-User instance and inform them exactly what is missing per the Evaluation. Allow the user to enter the information required and send an update operation for that instance.

After finishing the necessary updates, repeat Step 2 to create a new Evaluation instance with all of the updated information. By performing this check before submitting the Bundle Copy for Twilio to review, you can ensure that the request will be accepted.

After receipt, Twilio will review the Bundle Copy within 24 hours business SLA. If approved, you will

Note: If your Regulatory Bundle was rejected to one or more Supporting Document issues, you will be allowed to self-service fix your Supporting Documents by leveraging the FailureReason on the Supporting Document instances. By first referencing the Bundle Copy Item Assignments resource and then traversing to the Supporting Document instances for more detailed FailureReason information.

After the Bundle Copy has been reviewed and approved, it is up to you to replace the newly approved End-User Supporting Document(s) to the original Bundle. Once replaced, the valid until date parameter on the Bundle will be nulled out. By replacing only the Item Assignments, no Phone Numbers nor any other dependencies will have to be replacing and the history of the Bundle can continue.

Note: as explained in Step 1, by creating the Bundle Copy via Public API, you are responsible for replacing the Item Assignments and deleting the Bundle Copy after approval.

To clean up any leftover data that no longer has a purpose to you or Twilio, you should now the Bundle Copy. The Bundle Copy no longer has any Item Assignments and thus is no longer usable.

Note: as explained in Step 1, by creating the Bundle Copy via Public API, you are responsible for replacing the Item Assignments and deleting the Bundle Copy after approval.