Troubleshooting Sole Proprietor Brand Registration Failures
As noted at the start of our A2P Sole Proprietor Brand API registration guide, Sole Proprietor registration via the API consists of the following steps:
- Create a Starter Profile (a Starter Profile is used for later creating a Sole Proprietor Brand and Campaign, and can also be used for registering other products within TrustHub)
- Create a Sole Proprietor A2P Trust Bundle
- Create a Sole Proprietor Brand and complete OTP verification (you can only register 1 Sole Proprietor Brand for each unique customer)
- Create a Sole Proprietor Campaign (each Sole Proprietor Brand can only have one Campaign)
- Add a Phone Number to the Campaign (each Sole Proprietor Campaign can only use one Phone Number to send messages)
The present document addresses failures that can happen at Steps 1 and 3 (and involve remediations involving API calls at Steps 1, 2 and 3). Step 4, creation of the Sole Proprietor Campaign, can also fail; troubleshooting these failures is addressed in a separate document. Finally, Phone Numbers added to successfully-created Campaigns (Step 5) can themselves fail to be successfully registered, or their successful registration can take longer than expected. Troubleshooting these phone number issues is addressed in this guide.
A2P Brands and Campaigns can be registered either through our APIs or through our Console (Messaging > Regulatory Compliance > A2P Onboarding). Typically, direct customers registering their own Sole Proprietor Brands & Campaigns would do so through the Console, following this guide, while ISVs registering large numbers of secondary customers for Sole Proprietor Brands would most commonly do so through the API, using the Sole Proprietor API guide linked above and following the 5 steps mentioned there. As with any complex, multi-step process, our Console and API tools each offer pros and cons. The Console tool offers a user experience with a clearly-defined and constrained workflow, and this includes surfacing failure messages at different points and directing users on how to rectify these failures; but with this tool users can only process one Brand at a time. By contrast, our API tools offer ISVs the possibility of batch-creating dozens, hundreds or thousands of secondary Brands at a time, but while these API tools will also surface failures at various points, considerably greater care must be taken in troubleshooting and (especially) remediating these failures.
In fact, once you've been notified of failures related to Brand registration via the API, it might well make sense to proceed further via the Console in troubleshooting and rectifying these failures. Here you would log into the Twilio Console and choose the account (or subaccount) in which you have created the Brand you need to troubleshoot. Going to Messaging > Regulatory Compliance > Brands will show you a list of all Brands you've submitted in that account, along with a current status for each: registered, failed, or in review. Click on the name of the failed Brand you'd like to troubleshoot, and you'll be taken to a Brand summary page including failure details and directions for proceeding. In the first section below, we will consider one particular case of failure -- a failure in the validation of the email and/or address submitted with the Starter Business Profile associated with a Sole Proprietor Brand. Whatever the nature of a Brand failure, it's very possible that even if that Brand's registration was done (or attempted) in a batch process via the API, the particular nature of that failure may very well be unique to that particular Brand, meaning that there is likely no downside and considerable upside to troubleshooting and remediating this Brand failure via the Console.
However, it is also important to be aware of the ways that various failures in the Brand registration process will be surfaced via the API tools, and what troubleshooting and remediation can be accomplished using these tools. This is detailed in Section Two below.
Info
NOTE: Twilio now performs a data validation check on the email field and the address field in the above Profile submission. The validations and rejection reasons for email are as follows:
| Description | Rejection reason |
|---|---|
| Email domain should have correct syntax | Email domain has an invalid address syntax. |
| Email domain is unknown | Unknown email domain. |
| Temporary email which can be disposable | Email is a suspected disposable address. |
| If email check have passed all above validations and still is invalid from sendgrid API | Email is invalid. |
The validations and rejection reasons for address are as follows:
| If given address is not present | Address not found with sid ADXXXXXXXXXXXXXXXXXXXXXXXX |
|---|---|
| If given address is not a valid US/CA address | The provided address is not a valid US or Canada address |
| If given address has invalid postal code | [address_sids] - Invalid Postal Code. Address suggestion -> Street: 1 Jersey St. Secondary Street: Boston, MA 02215-4147. Locality: Boston. Region: MA. Postal Code: 02215-4147. Country: US; |
| If given address has invalid street name("street": "1 Jersey Str") | [address_sids] - Invalid Street. Address suggestion -> Street: 1 Jersey St. Secondary Street: Boston, MA 02215-4147. Locality: Boston. Region: MA. Postal Code: 02215-4147. Country: US |
| If given address has invalid locality("locality": "Bostun") | [address_sids] - Invalid Locality. Address suggestion -> Street: 1 Jersey St. Secondary Street: Boston, MA 02215-4147. Locality: Boston. Region: MA. Postal Code: 02215-4147. Country: US; |
| If given address has invalid region("region": "MAA") | [address_sids] - Invalid Region. Address suggestion -> Street: 1 Jersey St. Secondary Street: Boston, MA 02215-4147. Locality: Boston. Region: MA. Postal Code: 02215-4147. Country: US; |
| If given address has Invalid house number("street": "10000 Jersey St") | [address_sids] - Invalid House Number |
If either the email or address you've provided fails this validation check when creating a Sole Proprietor profile in the Console, you will be presented with an error message after you've submitted your Profile. As an example, the following screenshot shows validation errors for both email and address:
In this case, email has been flagged because "blah@blah.com" is not a valid email address. Business address has been flagged because "123 Blah Street" is not a real street address in New York City (we validate addresses against the USPS database, so all address details need to be real and accurate per the USPS).
Whatever the nature of the error, you will press the "Fix issues" link shown above. Because in this example there was an issue with email validation, to start you'd be taken back to the first Business Details screen, with the faulty Business email flagged:
Once the faulty email has been replaced with a functional one (in this case "messaging@twilio.com"), and you click the "Save and continue" button, you'll be taken to the Business Address screen if, as in this case, some remediation of the address is necessary. The relevant validation issue or issues will be displayed at the top of the screen; here we see that the issue is "Invalid Street":
Once "123 Blah Street" has been replaced with a real street address in New York City (and one that conforms to the indicated zip code, in this case "200 W 40th St"), you would again press Save and continue; this will return you to the Business Profile review screen:
NOTE: although this new Profile details screen now shows the corrected email and street address, the red "validation issues" banner still appears at the top. This is due to a current limitation in this Console workflow: the email and address validations are only applied after the full profile (that is to say, this screen) has been submitted; since it hasn't been resubmitted yet, from the standpoint of the application this Profile is still in a REJECTED state and doesn't know to take down the error banner. However, as long as the rectified information looks correct here, go ahead and press the blue Submit for review button at the bottom right. The new information will be re-submitted and will once again undergo email and address validation. At this point, as long as you pass these validations, you will see a screen like the following:
As the new banner at the top reminds you, the full review of this Profile can take up to 24 hours; it could still be rejected for other reasons. However, once you see this screen you can be reassured that you've rectified the email and/or address validation issues.
Note that any further issues with the review of your Profile will typically only surface if the Brand as a whole is rejected, which will only happen once the Brand has been submitted. If your Sole Proprietor Brand ends up REJECTED, and the reason relates to some aspect of the associated Profile, you will be directed to Edit the Profile to make any changes necessary.
Because our A2P API tools are often used by ISVs seeking to register large numbers of secondary customers' A2P Brands (and Campaigns) using batch/scripted processes, the temptation is to run through the entire sequence of API calls detailed in the Sole Proprietor API guide---that is, Business Profile creation in Section 1, Trust Bundle creation in Section 2, Brand creation in Section 3 and Campaign creation in Section 4--in a single, uninterrupted succession of calls for a given client's Brand, before moving on to the next client. And it is programmatically possible to do this, and do it successfully, provided there are no failures in individual steps along the way.
What's important to understand, however, is that the validation and review of data in Brand submissions (and Campaign submissions, but we detail these in a separate document) takes place in different layers and at different time intervals. Some of them involve instantaneous review of data conformity, such that an API call with non-conforming input data will instantly return a failure. Others, such as the newly-added validations for Business Profile email and address, are also programmatic but asynchronous, involving a latency of up to 10 or 20 seconds depending on load. Still other validations of the Profile and Brand submission involve manual review, and can take up to 24 hours or longer in the case of the Profile, and multiple business days in the case of the overall Brand submission. Ultimately, however, no Campaign will be approved if its associated Brand has failed, for any reason, and no Brand will be accepted if its associated Profile has failed, for any reason.
What is the best way to manage this situation, especially when you have large numbers of Brands to register? It is generally not practical to wait for a manual review of one piece to conclude before moving on to the next (for example, Business Profile > Brand > Campaign), and we do not advise that you do so. However, we do advise that, after submitting the complete Business Profile bundle in Step 1.8, you wait 30 seconds to see if any programmatic error surfaces before proceeding to the Trust Bundle creation in Step 2; that after the Trust Bundle is submitted in Step 2.6 you wait another 30 seconds before proceeding to Brand submission in Step 3; and that after Brand submission in Step 3 you wait 30 seconds before proceeding with Campaign creation in Step 4. Catching synchronous or near-synchronous upstream errors this way can dramatically reduce the amount of cleanup you have to do downstream, for examples deleting Campaigns whose Brands have failed, or deleting Brands (and Campaigns) whose Profiles have failed.
With all of that said, let's consider the kinds of failures that can occur at different stages of the API process through Brand creation (with Campaigns treated in a separate document).
At present, the only errors in Business Profile submission (Step 1.8) that are surfaced synchronously or near-synchronously, and can be remediated by customers themselves, are the following:
-
non-compliant Starter Customer Profile
. In Step 1.7 you are asked to submit your assembled Profile bundle to a compliance check against a template for this type of Profile. If this returns a
statusparameter ofcompliant, your bundle has passed this basic template and is ready to be submitted for review in Step 1.8 . If the Profile bundle is NOT compliant, the json return will indicate which fields have been found non-compliant or are missing. If you have skipped this check or ignored the results, the Profile bundle you submit in Step 1.8 may be non-compliant and if so, would immediately fail for this reason. The remediation in this case would be to submit this same bundle (identifiable by its profile bundle SID) for compliance assessment (Step 1.7) and note what is flagged in the json return - email and address validations . In Step 1.2, you created the basic Customer Profile resource that will be associated with your Sole Proprietor Brand. In Step 1.4, you created the Address resource to associate with that Profile. Twilio will programmatically validate both of these (for example, the address must be valid per the USPS). However, these validations are not applied until after the full Profile bundle has been submitted for review in Step 1.8; and at that point these validations are not synchronous but can have a latency of up to 20 seconds. There are two ways that you can be immediately informed if your submitted email and/or address has failed to pass validation (or three ways, including a failure_reason message for the Brand itself, covered below, if you don't rectify the issue before submitting the Brand):
The first method of validation error notification is email notification: If your Profile fails one of these validations, an email stating this change of Profile status to FAILED will be sent to the contact email address of the ISV (not that of the secondary Brand you are creating here). However, this email will only indicate that the profile is FAILED, not the reason(s) for it.
The second method of validation error notification is status_callback webhook: IF you have specified a status_callback webhook url when you created your Profile in Step 1.2, a validation failure of this kind will trigger a message to that webhook, and this message WILL detail the failure_reason in terms that relate directly to the validation reasons detailed at the top of Section One above. Using a status_callback webhook is the ONLY way, at present, that you can obtain this granular detail that would allow you to remediate an email or address validation issue. This remediation will involve UPDATE calls to the Customer Profile resource and/or Address resource you have created, and then a resubmission of the Customer Profile bundle as in Step 1.8.
Samples of these two resource update calls follow immediately below. After one or both of these are done, as necessary, the resubmission of the full Customer Profile is identical to the original submission call in Step 1.8.
Info
If you haven't set up the status_callback webhook but want to get the detailed failure_reason you may use our Console to check for errors.
Note that the email field is contained with the attributes object parameter, so while this email field is all we need to update in this case, we need to include all of the other extant fields and values in the attributes parameter as well:=
The full list of required and optional input parameters for the Address resource CREATE call are listed in Section 1.4 of the Sole Proprietor API guide. You will almost certainly not need to update all of these fields, but only those that caused the address validation error. In the example below, we are updating only the customer's street (street address), assuming that this is what failed address validation as in our Console example above. Our new street address value in this case will be "2 Hasselhoff Lane". As we have not specified any other fields in our call, the remainder of the fields in the original Address resource will remain unchanged. Note, however, that we must also supply the Account SID as well as the sid (understood here as the AddressSID) so as to properly identify the Address resource to update:
Remember that following your updates to the profile email and/or address resources, you will need to call the Profile bundle submit again, exactly as you did in Step 1.8 of the API doc. This is all the remediation required for such validation errors IF you've caught them before submitting your A2P Trust bundle (Step 2) or the Brand itself (Step 3). More below, if you've caught the validation error(s) further downstream.
At present, there are no separate issues with the Trust Bundle (created in Section 2 of the Sole Prop API guide) that would be surfaced to the user. However, IF you have already completed the steps in Section 2 to create and submit a Trust Bundle to associate with your Profile, and only then become aware of a defect in the Profile (such as a validation failure, or a rejection of any other kind), the Trust Bundle will itself need to be resubmitted for review. Fortunately this resubmission call will look exactly like the original Trust Bundle submission call in Step 2.6 of the Sole Prop API guide. As with the original call, what you are actually doing here is updating the status field of this Trust Bundle (created previously in Section 2) from "draft" to "pending-review".
In Section 3 of the Sole Proprietor API guide, you perform the actual A2P Brand submission call. This call's immediate return will most likely show a status of 'PENDING'. However, if you make a GET call to the same endpoint (as shown in Step 3.1) within a minute or two of the submission, you will be able to determine if this status has changed to "FAILED". Aside from this GET call on the Brand Registrations endpoint, you can also learn of a change in Brand status by setting up and subscribing to Brand status Event Streams, as also described in Step 3.1. Event Streams are a formalized way of creating (in this case) a webhook to which a status update message would be sent, roughly similar to the status_callback webhook you (hopefully) set up for the Profile itself. As with the generic webhook, the advantage of an Event Streams subscription is that it creates a "push" notification of status change, rather than you having to repeatedly poll the Brand endpoint itself with GET calls.
Either way, however, IF your Brand's status has been updated to "FAILED", you will be furnished with a list of errors in the json return (or the Event Streams payload). These error code items will be discrete and standardized to an entry in the Twilio Error Code Dictionary that offer discrete solutions to remediate the issue:
Data Validation - Error Code 30701
Error Message text:
"Brand Registration Failure: Invalid input parameters.” Exact parameters of issues will be provided in the Description, for example “Invalid email address, please check the input field value and retry.”
What this means: at present, this error means that your Profile failed the email and/or address validations--see Section 2.1 above--but you did not catch this before moving on to Trust Bundle creation and Brand submission. With that more granular information you will be able to follow the remediation steps detailed in Section 2.1 above. With the Profile itself rectified, you will then need to resubmit the Trust Bundle (see Section 2.2 above), and finally, you will need to edit the Brand itself.
Incorrect Profile SID provided - Error Code 30793
Error message text: "Brand Registration Failure: Validation problems with connected bundles.”
Error description text: “Validation failures with connected a2p or customer profile bundle.”
What this means: A Brand creation call simply associates a Profile SID (typically one you've just created) with a Trust Bundle SID (which you've also typically just created). This error text states that we cannot find the specified Profile based on the input SID. This might mean that you've simply copy/pasted the SID incorrectly from Step 1.8, when it was created. Sometimes the Profile and Trust Bundle SIDs are transposed in the Brand creation call.
Remediation: Make sure the Profile SID you are entering is accurate (i.e. is the one returned from Step 1.8), hasn't been transposed with the Trust Bundle SID, etc. You will then need to delete the failed Brand and submit again with the rectified SID.
NOTE that at this time, Brand deletion can only be done via the Twilio Console. Go to Messaging > Regulatory Compliance > Brands and find the Brand you wish to delete. Clicking on the name of this Brand will bring up a Brand details screen, which will likely have some details of the failure_reason and will definitely have a red Delete button on the far right, as shown below:
After the Brand has been deleted, you can repeat the identical Brand CREATE call shown in Section 3 of the Sole Prop API guide to recreate it (using the same Profile and Trust Bundle SIDs as before).
Incorrect Trust Bundle SID provided - Error Code 30793
Error message text: "Unable to fetch A2P Bundle Details, please check if the correct bundle sid was provided for registration."
What this means: Very much like the previous error, except in this case the Trust Bundle SID isn't accurate. Note that in the case of transposing the Profile and Trust Bundle SIDS, both of these errors are likely to be present as neither SID will be accurate.
Remediation: As with the previous error, make sure the Trust Bundle SID is accurate, i.e. is the one returned (as sid) from Step 2.6 of the Sole Prop API guide. Delete the failed Brand via Console and submit again with the rectified SID.
Can't register Brand with TCR - Error Code 30791
Error Message text: "Brand Registration Failure: Temporary system error"
What this means: This is a generic error message indicating that The Campaign Registry, the 3rd-party entity that handles all A2P registrations, cannot process you Brand submission. Please try again before reaching out to Support, and verify that the supplied information is accurate and well-formed before contacting Support.