API Getting Started: Compliance Information Update

Who is this guide for?

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.

New API Resources

• Copies Resource
• Replace Items Resource

New API Parameter

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.

How do I update compliance information?

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 be 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 requried. 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

API Sequence Diagram

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

Step 0: Twilio will enact new requirements for a current active Regulation

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 the status callback parameters.

{
   "account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "bundle_sid":"BUef3a237936fb63163fd852d77c5ba27b",
   "status":"twilio-approved",
   "valid_until":"2022-02-01T00:00:00Z",
   "failure_reason":""
}

Step 1: Filter for all Bundles

Besides the status callback webhooks and the email, your customers will need to filter all of their Bundles everytime 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.

Step 2: Create a Copy of the Bundle

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 insance 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.

Step 3: Determine why a newly updated Regulation will reject the Bundle Copy

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.

Step 4: Find Supporting Documents and End-Users to Update

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.

Step 5: Update Supporting Document(s)

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 instsance. If there are more Supporting Documents that failed the Evaluation, repeat this step until finished.

Step 6: Update End User

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 instsance.

Step 7: Submit Bundle Copy for Twilio to Review

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.

Step 8: Twilio to Review Reguatory Bundle Copy

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

{
   "account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "bundle_sid":"BU504eddd19f1efa428458f6daed683667",
   "status":"twilio-approved",
   "failure_reason":""
}

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.

Step 9: Replace Item Assignments

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 approvial.

Step 10: Delete Bundle Copy

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 approvial.