Menu

Expand
Rate this page:

New Sole Proprietor US A2P 10DLC Registration for ISVs: API Walkthrough

This API walkthrough is for ISVs who are registering their customers for new A2P 10DLC Sole Proprietor Brands and Campaigns. If you are an ISV who has existing Legacy Starter Brands for customers and want to convert them to the new Sole Proprietor Brand, see the documentation here.

Sole Proprietor Brands and Campaigns are only intended for customers in the US and Canada who do not have a tax ID. If your customers have a Tax ID, you must register them for a Standard or Low-Volume Standard Brand. If your customers are located outside of the US or Canada, you must register them for a Standard or Low-Volume Standard Brand to enable them to send messages to the US using 10DLC numbers.

Note: For all information entered as part of this registration process, please note that The Campaign Registry (TCR) supports all “utf8mb4” supported characters. Please see the list for all Unicode 15.0 supported scripts and characters here: https://www.unicode.org/charts/

When registering your customers for Sole Proprietor Brands, you need to provide the following information for each customer. You must use your customer's information for registration. Do not use your own (i.e., the ISV's) information:

Field Description
First and last name The customer's first and last name.
Email

This must be a well formatted address with a valid domain and cannot be a disposable address.

This email address can only be used a maximum of 10 times across all A2P Brand registrations with TCR. If your customer is registered for A2P 10DLC with another vendor, that counts towards this limit.

Phone number The customer's business/contact phone number. It must be a well-formatted number and can be a landline, mobile, or other number.
Mobile number

This mobile number is critical in the registration process and is used for sending a One Time Password (OTP) verification request to the customer, which they must respond to. This must be a valid US or Canadian mobile number only where the customer can be reached. This cannot be a number which you've acquired from a CPaaS provider such as Twilio.

This mobile number can only be used a maximum of three times across all A2P Brand registrations with TCR. If your customer is registered for A2P 10DLC with another vendor, that counts towards this limit.

You may use the same number for both the Phone Number field and the Mobile Number field, provided that this number satisfies all of the requirements here

Address

Must be a valid US or Canadian address. It can be a PO Box.

This address can only be used a maximum of 10 times across all A2P Brand registrations with TCR. If your customer is registered for A2P 10DLC with another vendor, that counts towards this limit.

Brand name

If your customer is a Sole Proprietor business, this must be the customer's real business name. For Sole Proprietor businesses, their business name is usually their first name and last name, but you can also provide a DBA name if there is one.

If your customer is not a business entity but instead is a hobbyist / college student, etc., please provide their first name and last name.

This field cannot be a unique identifier such as an account ID or email address.

Vertical (optional field)

You can select from a set of predefined values, which are the same as the vertical field in Primary Customer Profiles and Secondary Customer Profiles. See the list of available values here.

Your customer's mobile phone number, which will be used for One Time Password (OTP) verification of their Brand, can only be used a maximum of three times for registering A2P 10DLC Brands. This is a limit at The Campaign Registry (TCR) level, and not within Twilio. If your customer registers for A2P 10DLC Sole Proprietor Brand with another vendor and uses this mobile number for verification, that will count towards their lifetime three-use limit.

Once you have this information for your customers, you can complete their Sole Proprietor registration via the API. API registration consists of the following steps:

  1. 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)
  2. Create a Sole Proprietor A2P Trust Bundle
  3. Create a Sole Proprietor Brand and complete OTP verification (you should only register 1 Sole Proprietor Brand for each unique customer)
  4. Create a Sole Proprietor Campaign (each Sole Proprietor Brand can only have one Campaign)
  5. Add a Phone Number to the Campaign (each Sole Proprietor Campaign can only use one Phone Number to send messages)

Prerequisite: Create a Primary Customer Profile Bundle in TrustHub

Before registering any of your customers for A2P 10DLC messaging capabilities, you must first register your ISV. This is a one-time step. You will attach all of your customer's Profiles, Brands, and Campaigns to this Primary Customer Profile Bundle.

See the steps here for how to create your Primary Customer Profile Bundle.

You can find the SID for this via the Console.

1. Create Starter Customer Profile(s) and attach required information

This step creates Starter Customer Profiles for your customers using a Trust Hub policy with the identifier RN806dd6cd175f314e1f96a9727ee271f4. Trust Hub supports many types of compliance collections, but this specific policy is for Starter Profiles, which can be used for Sole Proprietor Brands.

1.1 Fetch the Starter Customer Profile Policy

The Starter Customer Profile Policy contains all of the fields you need to complete when creating a Starter Customer Profile. You can refer back to this throughout the registration process to ensure you are completing the necessary fields. When you have completed the Starter Customer Profile for this customer, you will submit it to be evaluated against this Customer Profile Policy (in step 1.7 of this walkthrough) to ensure that it meets all requirements.

The SID for the Starter Customer Profile Policy is RN806dd6cd175f314e1f96a9727ee271f4.

Loading Code Sample...
        
        

        1.1 Fetch the Starter Customer Profile Policy

        1.2 Create a Starter Customer Profile Bundle

        This Starter Customer Profile Bundle contains information about your customer. You will fill out some of the fields now, and will attach more information to this Bundle in later steps. You will submit this Bundle for review in the last step of Section 1 of this walkthrough.

        Parameter Valid Values
        friendly_name A string representing your customer's business name. This is an internal name meant for you to identify this particular customer profile Bundle for your customer.
        email A string representing your customer's email address
        policy_sid

        The static TrustHub policy identifier for Starter profiles. The hard-coded value is RN806dd6cd175f314e1f96a9727ee271f4 and you use this value for every Starter Customer Profile Bundle you create.

        status_callback (optional)

        The URL at which you would like to receive webhook requests about status updates to this Profile Bundle

        Loading Code Sample...
              
              

              1.2 Create an Empty Starter Customer Profile Bundle

              You will use the SID from this new Customer Profile Bundle you created (the SID begins with BU) in a later step.

              1.3 Create an end-user object with the type starter_customer_profile_information

              Parameter Valid Values
              attributes An object containing your customer's first name, last name, email address, and phone number
              friendly_name A string representing the end-user object you create in this step. This is for your internal purposes for identifying the end customer.
              type The end user object type. This will always be starter_customer_profile_information for Starter Profiles.

              The attributes object should contain the following fields:

              {
                 "email": "starter-profile-enduser@example.com",
                 "first_name": "John",
                 "last_name": "Doe",
                 "phone_number": "+11234567890"
              }
              
              Loading Code Sample...
                    
                    

                    1.3 Create an end-user object with the type: starter_customer_profile_information

                    You will use the SID of the new end-user object you created (the SID begins with IT) in a later step.

                    1.4 Create a supporting document: customer_profile_address

                    Here, you create an Address object for the customer, which you then attach to their customer profile. Note that you can only use a valid US or Canadian address if you are creating a Sole Proprietor registration.

                    Provide the following parameters to the API request:

                    Parameter Valid Values
                    Customer Name (optional) String representing your customer's name
                    Street Address 1 Example: 1234 Your Street Name
                    Street Address 2 (optional) Example: Apt B
                    City Example: San Francisco
                    Region Can be a State or Province. For example, California (US State) and British Columbia (Canadian Province).
                    Postal Code Example: 94016
                    IsoCountry See this list of valid IsoCountry codes

                    Loading Code Sample...
                          
                          

                          1.4 Create a supporting document: customer_profile_address

                          1.5 Create a Supporting Document with the Address from Step 1.4

                          Once you have a valid address SID from this Address object you just created (the SID beings with AD), you can create a Supporting Document object. This Supporting Document will later be assigned to the Starter Customer Profile Bundle that you created in step 1.2.

                          The Supporting Document will need the following values:

                          Parameter Valid Values
                          attributes An object containing the Address SID from the previous step.
                          friendly_name A string you use to identify this Supporting Document
                          type The string customer_profile_address

                          The attributes object should look like this:

                          {
                             "address_sids": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                          }
                          
                          Loading Code Sample...
                                
                                

                                1.5 Create a Supporting Document with the Address from Step 1.4

                                You will use the SID from this new Supporting Document (the SID begins with RD) in the next step.

                                1.6 Assign End-User, Supporting Document, and Primary Customer Profile to the Starter Customer Profile that you created

                                Attach the SIDs from all the steps above to the Starter Customer Profile:

                                • End-User Object SID (step 1.3): Begins with IT
                                • Starter Customer Profile SID (step 1.2): Begins with BU
                                • Supporting Document SID (step 1.5): Begins with RD
                                • Primary Customer Profile Bundle SID (from parent account, mentioned in the Prerequisites section): Begins with BU

                                1.6.1 Attach the end-user (from Step 1.3) to the Starter Customer Profile

                                The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the End-User Object SID from step 1.3. See the code sample below as an example.

                                Loading Code Sample...
                                      
                                      

                                      1.6.1 Attach the end-user (from Step 1.3) to the Starter Customer Profile

                                      1.6.2 Attach the Supporting Document (from Step 1.4) to the Starter Customer Profile

                                      The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the Supporting Document SID from step 1.5. See the code sample below as an example.

                                      Loading Code Sample...
                                            
                                            

                                            1.6.2 Attach the Supporting Document (from Step 1.4) to the Starter Customer Profile

                                            1.6.3 Attach the Primary Customer Profile Bundle to the Starter Customer Profile Bundle

                                            This step is applicable only for ISV customers of Twilio. ISV customers should already have Primary Customer Profile setup in their parent/main account from where they can fetch its Bundle SID (the SID starts with BU). See the Prerequisites for more information.

                                            The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the Primary Customer Bundle SID. See the code sample below as an example.

                                            Loading Code Sample...
                                                  
                                                  

                                                  1.6.3 Attach the Primary Customer Profile Bundle to the Starter Customer Profile Bundle

                                                  1.7 Evaluate the Starter Customer Profile

                                                  This step evaluates the Starter Customer Profile against the Starter Customer Profile Policy (which you fetched in step 1.1; the Starter Customer Profile Policy has the SID RN806dd6cd175f314e1f96a9727ee271f4).

                                                  The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called policy_sid, which is the hardcoded Policy SID RN806dd6cd175f314e1f96a9727ee271f4.

                                                  If your Starter Customer Profile is missing any required information, the response to the API request will indicate that those fields are not complete. You should go back and complete the missing fields from the previous steps.

                                                  If your Starter Customer Profile matches the expected Starter Customer Profile Policy, the response will indicate that the profile is compliant and that you can move on to the next step.

                                                  Loading Code Sample...
                                                        
                                                        

                                                        1.7 Evaluate the Starter Customer Profile

                                                        1.8 Submit the Starter Customer Profile for review

                                                        Once you have evaluated the Starter Customer Profile against the Starter Customer Profile Policy and the response says that the profile is compliant, you are ready to submit the profile.

                                                        The Starter Customer Profile status field has the following possible values:

                                                        • draft
                                                        • pending-review
                                                        • in-review
                                                        • twilio-rejected
                                                        • twilio-approved

                                                        When you first create the profile, it will be in the draft state. To submit the profile for review, you update the profile's status to pending-review via API request (the example of this request is below). The result of this API request will update the profile's status to in-review (which you should see in the response to your API request), at which point you should move on to the next step in this walkthrough.

                                                        Proceed to the next step as soon as the Starter Customer Profile is in the in-review state. Do not wait for it to be twilio-approved. The Starter Customer Profile will only reach the twilio-approved status when a Brand is successfully created and OTP-verified in the following section, so you must proceed in order for the Starter Customer Profile to be approved.

                                                        Loading Code Sample...
                                                              
                                                              

                                                              1.8 Submit the Starter Customer Profile for review

                                                              2. Create a new Sole Proprietor A2P Trust Bundle and attach required information

                                                              Once your Starter Customer Profile from the previous step is in_review, you can create a new Sole Proprietor Trust Bundle for your customer, which you will then use to complete a Sole Proprietor Brand. The steps in this section are very similar to the ones you completed in Section 1, but you will provide different information about your customer here.

                                                              2.1 Fetch the Sole Proprietor A2P Trust Policy

                                                              Similar to Step 1.1, fetch the Sole Proprietor A2P Trust Policy to help you determine if you are meeting all the requirements for your Trust Bundle before you submit it.

                                                              The Sole Proprietor A2P Trust Policy contains all of the fields you need to complete when creating a Sole Proprietor Trust Bundle. You can refer back to this throughout the registration process to ensure you are completing the necessary fields. When you have completed the Sole Proprietor Trust Bundle for this customer, you will submit it to be evaluated against this Trust Policy to ensure that it meets all requirements.

                                                              The SID for the Starter Customer Profile Policy is RN670d5d2e282a6130ae063b234b6019c8.

                                                              Loading Code Sample...
                                                                    
                                                                    

                                                                    2.1 Fetch the Sole Proprietor A2P Trust Policy

                                                                    2.2 Create a Sole Proprietor A2P Trust Bundle

                                                                    This Sole Proprietor A2P Trust Bundle contains information about your customer (from the profile you created above) and their Brand. You fill out some of the fields now, and attach more information to this Bundle in later steps. You will submit this Bundle for review in the last step of Section 2 of this walkthrough.

                                                                    These are the parameters for the API request to create a Sole Proprietor A2P Trust Bundle:

                                                                    Parameter Valid Values
                                                                    friendly_name A string representing your customer's business name. This is an internal name for you to identify this Bundle for your customer.
                                                                    email A string representing your customer's email address
                                                                    policy_sid The static A2P Messaging TrustHub Policy identifier. The hard-coded value is RN670d5d2e282a6130ae063b234b6019c8.
                                                                    status_callback The URL at which you would like to receive webhook requests about status updates to this Trust Bundle
                                                                    Loading Code Sample...
                                                                          
                                                                          

                                                                          2.2 Create a Sole Proprietor A2P Trust Bundle

                                                                          You will use the SID from this new Sole Proprietor Trust Bundle you created (the SID begins with BU) in a later step.

                                                                          2.3 Create end-user object with the type sole_proprietor_information

                                                                          In this step, you provide information about your customer's brand name, their mobile number for their Sole Proprietor Brand verification, and optionally their business vertical.

                                                                          In this step, you provide your customer's mobile number, which TCR will use to send a One Time Password (OTP) verification request. This must be a valid US or Canadian mobile number where the customer can be reached. This cannot be a number you've acquired from a CPaaS provider such as Twilio.

                                                                          The customer will receive the OTP message when you submit the Brand for review in step 3. They must respond to the request within 24 hours, or else you will need to retrigger the OTP message using the optional step 3.2. Additionally, the OTP verification must be completed within 30 days of Brand registration. Please see step 3.1 for more details.

                                                                          This mobile number can only be used a maximum of three times for Sole Proprietor A2P Brands. This includes if the customer has registered for a Sole Proprietor Brand with another vendor and has used the same mobile phone number. This limit is managed through TCR and not through Twilio.

                                                                          Include the following parameters in your API request:

                                                                          Parameter Valid Values
                                                                          attributes An object containing your customer's business name (which is usually their first and last name, if they do not have a business name / DBA name), their mobile phone number, and optionally, their business vertical. Please see the note above about the importance of the customer's mobile phone number for verification.
                                                                          friendly_name A string to indentify this end user object for your customer
                                                                          type The string sole_proprietor_information

                                                                          The attributes object should look like this:

                                                                          {
                                                                             "brand_name": "John Doe",
                                                                             "vertical": "COMMUNICATION",
                                                                             "mobile_phone_number": "+11234567890"
                                                                          }
                                                                          

                                                                          The optional vertical field describes the customer's business. It can be one of the following values:

                                                                          • AGRICULTURE

                                                                          • COMMUNICATION

                                                                          • CONSTRUCTION

                                                                          • EDUCATION

                                                                          • ENERGY

                                                                          • ENTERTAINMENT

                                                                          • FINANCIAL

                                                                          • GAMBLING

                                                                          • GOVERNMENT

                                                                          • HEALTHCARE

                                                                          • HOSPITALITY

                                                                          • HUMAN_RESOURCES

                                                                          • INSURANCE

                                                                          • LEGAL

                                                                          • MANUFACTURING

                                                                          • NGO

                                                                          • POLITICAL

                                                                          • POSTAL

                                                                          • PROFESSIONAL

                                                                          • REAL_ESTATE

                                                                          • RETAIL

                                                                          • TECHNOLOGY

                                                                          • TRANSPORTATION

                                                                          Loading Code Sample...
                                                                                
                                                                                

                                                                                2.3 Create an end-user object with the type sole_proprietor_information

                                                                                You will use the SID from this new end-user you created (the SID begins with IT) in the next step.

                                                                                2.4 Assign the end-user and starter customer profile to the Sole Proprietor A2P Trust Bundle

                                                                                Attach the SIDs from the end-user object you created in step 2.3 and the Starter Customer Profile you created in step 1.2 to the Sole Proprietor Trust Bundle you created in step 2.2 (the SID for the Sole Proprietor Trust Bundle begins with BU).

                                                                                • End-User Object SID (step 2.3): SID begins with IT.
                                                                                • Starter Customer Profile SID (step 1.2): SID begins with BU.

                                                                                2.4.1 Attach the end-user (from Step 2.3) to the Sole Proprietor A2P Bundle

                                                                                The Sole Proprietor A2P Bundle SID from step 2.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the End-User Object SID from step 2.3. See the code sample below as an example.

                                                                                Loading Code Sample...
                                                                                      
                                                                                      

                                                                                      2.4.1 Attach the end-user (from Step 2.3) to the Sole Proprietor A2P Bundle

                                                                                      2.4.2 Assign the Starter Customer Profile Bundle to the Sole Proprietor A2P Trust Bundle

                                                                                      The Sole Proprietor A2P Bundle SID from step 2.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the Starter Customer Profile Bundle SID from step 1.3. See the code sample below as an example.

                                                                                      Loading Code Sample...
                                                                                            
                                                                                            

                                                                                            2.4.2 Assign the Starter Customer Profile Bundle to the Sole Proprietor A2P Trust Bundle

                                                                                            2.5 Evaluate the Sole Proprietor A2P Trust Bundle

                                                                                            This step evaluates the Sole Proprietor A2P Trust Bundle against the Sole Proprietor A2P Trust Policy (which you fetched in step 2.1; the Sole Proprietor A2P Trust Policy has the SID RN670d5d2e282a6130ae063b234b6019c8).

                                                                                            The Sole Proprietor Trust Bundle SID from step 2.2 is the path parameter for this request. The body of the request should contain one parameter, called policy_sid, which is the hardcoded Policy SID RN670d5d2e282a6130ae063b234b6019c8.

                                                                                            If your Sole Proprietor Trust Bundle is missing any required information, the response to the API request will indicate that those fields are not complete. You should go back and complete the missing fields from the previous steps.

                                                                                            If your Sole Proprietor Trust Bundle matches the expected Sole Proprietor Trust Policy, the response will indicate that the profile is compliant and that you can move on to the next step.

                                                                                            Loading Code Sample...
                                                                                                  
                                                                                                  

                                                                                                  2.5 Evaluate the Sole Proprietor A2P Trust Bundle

                                                                                                  2.6 Submit the Sole Proprietor A2P Trust Bundle for review

                                                                                                  Once you have evaluated the Sole Proprietor Trust Bundle against the Sole Proprietor Trust Policy and the response says that the profile is compliant, you are ready to submit the profile.

                                                                                                  The Sole Proprietor Trust Bundle status field has the following possible values:

                                                                                                  • draft
                                                                                                  • pending-review
                                                                                                  • in-review
                                                                                                  • twilio-rejected
                                                                                                  • twilio-approved

                                                                                                  When you first create the Trust Bundle, it will be in the draft state. To submit the Trust Bundle for review, update the Bundle's status to pending-review via API request (the example of this request is below). The result of this API request will update the profile's status to in-review (which you should see in the response to your API request), at which point you should move on to the next step in this walkthrough.

                                                                                                  You should proceed to the next step as soon as the Sole Proprietor A2P Trust Bundle is in the in-review state. Do not wait for it to be twilio-approved. The Starter Customer Profile and Sole Proprietor A2P Trust Bundle will only reach the twilio-approved status when a Brand is successfully created and OTP-verified, and you should never wait for this status change.

                                                                                                  Loading Code Sample...
                                                                                                        
                                                                                                        

                                                                                                        2.6 Submit the Sole Proprietor A2P Trust Bundle for review

                                                                                                        3. Create a new Sole Proprietor A2P Brand

                                                                                                        In this step, you will create a Sole Proprietor A2P Brand using the Customer Profile SID from step 1.2 and the Trust Bundle SID from step 2.2. You should have already submitted both of these objects for review in the previous steps, but you shouldn't wait for them to be approved before continuing.

                                                                                                        Loading Code Sample...
                                                                                                              
                                                                                                              

                                                                                                              3. Create a new Sole Proprietor A2P Brand

                                                                                                              3.1 GET the Sole Proprietor Brand registration status

                                                                                                              You can check the status of your customer's Sole Proprietor Brand registration with a GET request. This should update within a few minutes after submitting the Sole Proprietor Brand API request from the step above.

                                                                                                              The API will return the following information about the registration:

                                                                                                              Property Possible Values
                                                                                                              status PENDING, APPROVED or FAILED
                                                                                                              identity_status

                                                                                                              UNVERIFIED or VERIFIED

                                                                                                              UNVERIFIED means that the customer has not verified the OTP request sent to their mobile number.

                                                                                                              This value will change from UNVERIFIED to VERIFIED after your customer successfully verifies the mobile number provided in Step 2.3

                                                                                                              failure_reason

                                                                                                              Only present if the status is FAILED. This describes the reason for the Brand registration failure. Possible reasons for failure and the resolutions are:

                                                                                                              —"Unable to fetch A2P Bundle Details, please check if the correct bundle sid was provided for registration and the bundle is compliant." -> Check Bundle Details and retry

                                                                                                              —"Unable to fetch Customer Profile Bundle details, please check if the correct bundle sid was provided for registration and the bundle is compliant." -> Check Bundle Details and retry

                                                                                                              —"Unable to register Brand with The Campaign Registry" -> review the registration requirements defined at the beginning of this document and ensure that your registration information is complete and meets the requirements (for additional information please see https://support.twilio.com/hc/en-us/articles/14488596590491-Why-did-my-Sole-Proprietor-Brand-Registration-Fail-.) Please verify that the supplied information is accurate and well-formed before contacting Twilio Support

                                                                                                              When the Sole Proprietor Brand first enters the APPROVED state, the identity_status will still be UNVERIFIED. The change to the APPROVED state triggers a new SMS OTP, which is sent to the mobile number registered with the Brand (from step 2.3). The OTP is valid for 24 hours. If your customer does not complete the OTP verification request after 24 hours, you can use this API to trigger a fresh OTP for verification.

                                                                                                              The owner of the mobile number will receive a text message sent from +1(915)-278-2000 with the following text: "Please confirm your registration for US A2P Messaging by replying YES. Msg & data rates may apply."

                                                                                                              The owner of the mobile number must reply "YES" back to the OTP message to complete Brand verification. Once they do that, they should receive another confirmation message on their mobile number that says "Thank you. Your registration has been confirmed." The Brand state will remain as APPROVED, and their identity_status will now change to VERIFIED

                                                                                                              Note that only the first OTP is sent automatically; if your customer does not complete the OTP verification request within 24 hours, you need to send an API request to trigger a new OTP (see step 3.2 for the API request to retrigger this OTP). Additionally, please make every effort to ensure that your customer completes OTP verification within 30 days of Brand registration. At some point going forward, The Campaign Registry (TCR) may begin to enforce a 30-day limit for this OTP completion, after which the Brand registration would be marked as EXPIRED, and would need to be deleted and resubmitted (this documentation will be updated if and when TCR begins to enforce this).

                                                                                                              You will need to wait until the Sole Proprietor Brand is approved and verified before moving on to Step 4.

                                                                                                              Loading Code Sample...
                                                                                                                    
                                                                                                                    

                                                                                                                    3.1 GET the Sole Proprietor Brand registration status

                                                                                                                    3.2 [Optional] Retry OTP Verification for the submitted mobile number

                                                                                                                    The change from a Sole Proprietor's Brand to the APPROVED state automatically triggers an SMS OTP, which is sent to the mobile number registered with the Brand. The OTP is valid for 24 hours. If your customer does not accept the OTP request after 24 hours, you can use this API to trigger a fresh OTP for verification.

                                                                                                                    This endpoint has a rate limit of 10 requests per second per account.

                                                                                                                    Loading Code Sample...
                                                                                                                          
                                                                                                                          

                                                                                                                          3.2 [Optional] Retry OTP Verification for the submitted mobile number

                                                                                                                          You can use the GET API request from 3.1 to check the OTP verification status.

                                                                                                                          4. Create a new Messaging Service

                                                                                                                          You do not need to complete this step if you have already created a Messaging Service for your customer.

                                                                                                                          Please note that for Sole Proprietor A2P 10DLC registrations, you should only have one 10DLC number in the Messaging Service. Sole Proprietor Campaigns can only have one 10DLC phone number attached to them.

                                                                                                                          In this step, you create a new Messaging Service for your customer. You can later add 10DLC numbers to this Messaging Service and attach the Service to a registered A2P Campaign.

                                                                                                                          See the documentation here about how to create a new Messaging Service via the API.

                                                                                                                          5. Create a new Sole Proprietor A2P SMS Campaign

                                                                                                                          In this final step, you will create a new Sole Proprietor A2P SMS Campaign. Here, you describe what type of messages the customer is sending to end-users and how those end-users can opt in and out of these messages.

                                                                                                                          This Campaign use case can then be attached to a Messaging Service, and the A2P 10DLC numbers in that Messaging Service will be able to send verified A2P 10DLC traffic.

                                                                                                                          When you create a Campaign, you will need to indicate how end users opt-in and give consent to receive messages from this Campaign. You will also need to provide details about how end users can opt-out and receive help.

                                                                                                                          Please see A2P 10DLC Campaign Approval Best Practices to ensure your Campaigns meet all requirements.

                                                                                                                          Most Twilio customers use Twilio's default or advanced opt-out features. If you use default or advanced opt-out, Twilio will automatically complete your Campaign's opt-out and help parameters with Twilio's default values or your customized advanced opt-out and help values.

                                                                                                                          For more information about all of the parameters within the Create Campaign API, see the full API documentation.

                                                                                                                          The API request takes the following parameters:

                                                                                                                          Parameter Description
                                                                                                                          brand_registration_sid The A2P Brand Registration SID from Step 3
                                                                                                                          description

                                                                                                                          A short description of what this SMS campaign does. Min length: 40 characters. Max length: 4096 characters.

                                                                                                                          Example: "Send marketing messages about sales and offers"

                                                                                                                          message_samples

                                                                                                                          An array of strings. Samples of the messages your customer will send. Must include at least 2 samples for Sole Proprietor Campaigns, and up to 5 samples. Min length for each sample: 20 chars. Max length for each sample: 1024 chars.

                                                                                                                          Example: ["Book your next OWL FLIGHT for just 1 EUR", "Twilio draw the OWL event is ON"]

                                                                                                                          message_flow

                                                                                                                          Required for all Campaigns. Details around how a consumer opts-in to their campaign, therefore giving consent to receive their messages. If multiple opt-in methods can be used for the same campaign, they must all be listed. 40 character minimum. 2048 character maximum.

                                                                                                                          If a website is used for opting in, provide a link to the website. The website needs to have a privacy policy and terms of service. Privacy policies also need to include a statement of non-sharing for mobile numbers, message frequency, and "message and data rates may apply" disclosure. You need to provide a link to the policy.

                                                                                                                          Example: "End users opt-in by visiting www.example.com and adding their phone number. They then check a box agreeing to receive text messages from Example Brand. Additionally, end users can also opt-in by texting START to (111) 222-3333 to opt in. Term and Conditions at www.example.com/tc. Privacy Policy at www.example.com/privacy"

                                                                                                                          us_app_to_person_usecase SOLE_PROPRIETOR
                                                                                                                          has_embedded_links

                                                                                                                          Boolean. Indicates that this SMS campaign will send messages that contain links.

                                                                                                                          has_embedded_phone Boolean. Indicates that this SMS campaign will send messages that contain phone numbers.
                                                                                                                          opt_in_message (optional)

                                                                                                                          String. If end users can text in a keyword to start receiving messages from this campaign, the auto-reply messages sent to the end users must be provided. The opt-in response should include the Brand name, confirmation of opt-in enrollment to a recurring message campaign, how to get help, and clear description of how to opt-out.

                                                                                                                          This field is required if end users can text in a keyword to start receiving messages from this campaign. Min length: 20 characters. Max length: 320 characters.

                                                                                                                          opt_in_keywords (optional)

                                                                                                                          An array of strings. If end users can text in a keyword to start receiving messages from this campaign, those keywords must be provided.

                                                                                                                          This field is required if end users can text in a keyword to start receiving messages from this campaign. Values must be alphanumeric. Max length: 255 characters.

                                                                                                                          opt_out_message (optional in certain cases, see description)

                                                                                                                          String. The message that an end-user receives when opting out of messages. Upon receiving the opt-out keywords from the end users, Twilio customers are expected to send back an auto-generated response, which must provide acknowledgment of the opt-out request and confirmation that no further messages will be sent. It is also recommended that these opt-out messages include the brand name.

                                                                                                                          This field is required if managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Min length: 20 characters. Max length: 320 characters.

                                                                                                                          opt_out_keywords (optional in certain cases, see description)

                                                                                                                          An array of strings. The keywords that an end user can text to opt out of messaging. End users should be able to text in a keyword to stop receiving messages from this campaign.

                                                                                                                          This field is required if managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. Max length: 255 characters.

                                                                                                                          help_message (optional in certain cases, see description)

                                                                                                                          String. The message that end users receive in response to a help keyword. When customers receive the help keywords from their end users, Twilio customers are expected to send back an auto-generated response; this may include the brand name and additional support contact information.

                                                                                                                          This field is required if managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum.

                                                                                                                          help_keywords (optional in certain cases, see description)

                                                                                                                          An array of strings. The keywords that an end user can text to receive help. End users should be able to text in a keyword to receive help.

                                                                                                                          This field is required if managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. Max length: 255 characters.

                                                                                                                          Loading Code Sample...
                                                                                                                                
                                                                                                                                

                                                                                                                                5. Create a new Sole Proprietor A2P SMS Campaign for default or advanced opt-out users

                                                                                                                                Customers managing their own opt-out will need to provide additional opt-out and help information when registering a Campaign.

                                                                                                                                Loading Code Sample...
                                                                                                                                      
                                                                                                                                      

                                                                                                                                      5. Create a new Sole Proprietor A2P SMS Campaign for customers managing their own opt-out

                                                                                                                                      5.1 GET the Status of an A2P Messaging Campaign

                                                                                                                                      You can GET your messaging Campaign associated with a Messaging Service and monitor its approval status with the following API request.

                                                                                                                                      You can confirm that your Campaign post-approval is in review using the campaign_status parameter that is returned. The statuses for post-approval Campaigns are:

                                                                                                                                      • In review : the campaign_status value is IN_PROGRESS
                                                                                                                                      • Approved: the campaign_status value is VERIFIED
                                                                                                                                      • Rejected: the campaign_status value is FAILED
                                                                                                                                      Loading Code Sample...
                                                                                                                                            
                                                                                                                                            

                                                                                                                                            5.1 GET A2P Messaging Campaign Status

                                                                                                                                            5.2 [Optional] DELETE A2P Messaging Campaign

                                                                                                                                            If you need to unregister or "delete" a Campaign, you can make the following request to the Messaging Service. Again, here you will specify the compliance type QE2c6890da8086d771620e9b13fadeba0b in your request.

                                                                                                                                            After your API request is accepted, please allow a few seconds for deletion to be finalized. If you are programmatically deleting a Campaign and then creating a new Campaign on the same Messaging Service, you should implement at least a 5-second delay between removing the existing Campaign and creating a new one on the same Messaging Service.

                                                                                                                                            Loading Code Sample...
                                                                                                                                                  
                                                                                                                                                  

                                                                                                                                                  5.2 [Optional] DELETE A2P Messaging campaign use case

                                                                                                                                                  6. Ensure that a Twilio 10DLC phone number is associated with your new Campaign

                                                                                                                                                  Once your Sole-Proprietor Business Profile, Brand, and Campaign have been registered and verified, the final step before you can begin using the new Messaging Campaign is to ensure that the Twilio 10DLC phone number you use to send messages to the US is associated with the new Campaign’s Messaging Service as the Sender. Here you’ll need to keep several things in mind:

                                                                                                                                                  1. For Sole Proprietor Campaigns, only a single 10DLC phone number can be used in the Messaging Service associated with your new Campaign. If you associate more than one phone number with this Messaging Service (or reuse a Messaging Service with more than one number attached), Twilio will randomly pick from among these to register one for A2P use.
                                                                                                                                                  2. See this part of the PhoneNumberResource guide for the API call to associate a given phone number (by phone_number_sid) with the new Messaging Service (by messaging_service_sid) you’ve created for the new Sole Proprietor A2P Campaign.
                                                                                                                                                  3. You can subsequently use a GET call on that same phone_numbers endpoint as in (2) above to confirm that the phone number is associated with this Messaging Service (see this part of the same PhoneNumberResource guide).

                                                                                                                                                  If you do not currently have a Twilio 10DLC phone number you’d like to use with the new Messaging Service, you can select and buy one either via the Twilio Console or via API – see this guide for details on both.

                                                                                                                                                  NOTE: Whether or not you choose to reuse existing Twilio phone numbers in the context of these new Sole Proprietor Campaign registrations, please be aware that any Twilio 10DLC numbers you currently have, and that you wish to continue using for SMS messaging within the U.S., must be registered as senders for A2P Messaging Services (ie officially associated with some officially registered A2P Campaign) by the Summer of 2023. Effective July 5, 2023, all 10DLC phone numbers used to send SMS and MMS messages to U.S. phone numbers must be fully registered to an approved campaign under your brand. Messages sent using unregistered phone numbers will be subject to a gradual increase of message blocking by Twilio, beginning on July 5, 2023, ultimately leading to a full block of all unregistered U.S.-bound messages sent after August 31, 2023. For more information, visit our Shutdown of Unregistered 10DLC Messaging FAQ

                                                                                                                                                  Congratulations! 🎉 You now have a registered A2P Sole Proprietor Campaign!

                                                                                                                                                  Rate this page:

                                                                                                                                                  Need some help?

                                                                                                                                                  We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                                                                                                                                  Loading Code Sample...
                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                        

                                                                                                                                                        Thank you for your feedback!

                                                                                                                                                        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                                                                                                                        Sending your feedback...
                                                                                                                                                        🎉 Thank you for your feedback!
                                                                                                                                                        Something went wrong. Please try again.

                                                                                                                                                        Thanks for your feedback!

                                                                                                                                                        thanks-feedback-gif