Troubleshooting Sole Proprietor Brand Registration Failures

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.

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:

Expand image

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:

Expand image

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":

Expand image

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:

Expand image

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:

Expand image

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 status parameter of compliant, 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.

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:=

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateEndUser() {
11
  const endUser = await client.trusthub.v1
12
    .endUsers("ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update({
14
      attributes: {
15
        email: "starter-profile-enduser@example.com",
16
        first_name: "John",
17
        last_name: "Doe",
18
        phone_number: "+11234567890",
19
      },
20
      friendlyName: "Starter Profile End User",
21
    });
22

23
  console.log(endUser.sid);
24
}
25

26
updateEndUser();

1
{
2
  "date_updated": "2021-02-16T20:40:57Z",
3
  "sid": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
  "friendly_name": "Starter Profile End User",
5
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "url": "https://trusthub.twilio.com/v1/EndUsers/ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
  "date_created": "2021-02-16T20:40:57Z",
8
  "attributes": {
9
    "phone_number": "+11234567890",
10
    "job_position": "CEO",
11
    "first_name": "rep1",
12
    "last_name": "test",
13
    "business_title": "ceo",
14
    "email": "foobar@test.com"
15
  },
16
  "type": "authorized_representative_1"
17
}

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:

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateAddress() {
11
  const address = await client
12
    .addresses("AD2a0747eba6abf96b7e3c3ff0b4530f6e")
13
    .update({ street: "2 Hasselhoff Lane" });
14

15
  console.log(address.accountSid);
16
}
17

18
updateAddress();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "city": "SF",
4
  "customer_name": "name",
5
  "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
6
  "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
7
  "emergency_enabled": false,
8
  "friendly_name": null,
9
  "iso_country": "US",
10
  "postal_code": "94019",
11
  "region": "CA",
12
  "sid": "AD2a0747eba6abf96b7e3c3ff0b4530f6e",
13
  "street": "2 Hasselhoff Lane",
14
  "street_secondary": null,
15
  "validated": false,
16
  "verified": false,
17
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses/ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
18
}

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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateBrandRegistrations() {
11
  const brandRegistration = await client.messaging.v1
12
    .brandRegistrations("BNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update();
14

15
  console.log(brandRegistration.sid);
16
}
17

18
updateBrandRegistrations();

1
{
2
  "sid": "BNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "customer_profile_bundle_sid": "BU3344409f7e067e279523808d267e2d85",
5
  "a2p_profile_bundle_sid": "BU3344409f7e067e279523808d267e2d85",
6
  "date_created": "2021-01-27T14:18:35Z",
7
  "date_updated": "2021-01-27T14:18:36Z",
8
  "brand_type": "STANDARD",
9
  "status": "PENDING",
10
  "tcr_id": "BXXXXXX",
11
  "failure_reason": "Registration error",
12
  "url": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
  "brand_score": 42,
14
  "brand_feedback": [
15
    "TAX_ID",
16
    "NONPROFIT"
17
  ],
18
  "identity_status": "VERIFIED",
19
  "russell_3000": false,
20
  "government_entity": false,
21
  "tax_exempt_status": "501c3",
22
  "skip_automatic_sec_vet": false,
23
  "errors": [],
24
  "mock": false,
25
  "links": {
26
    "brand_vettings": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Vettings",
27
    "brand_registration_otps": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SmsOtp"
28
  }
29
}

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 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 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:

Expand image

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.