Rate this page:

REST API: Subaccounts

Subaccounts in Twilio are just accounts that are "owned" by your account. Using a subaccount, you can segment each of your customers' use of Twilio and keep it separate from all the rest. This will allow you to easily manage the activity and resources of each customer independently.

Important Notes:

  • A main account can only have up to 1000 subaccounts by default. If you need more subaccounts please contact support.
  • Subaccounts will not have access to the API Explorer in their Twilio Console.
  • By default, closed subaccounts get deleted after the parent account is closed. To enable automatic deletion of subaccounts, 30-days after you closed them, please contact support.


Twilio bills all subaccount usage directly to your main account. You'll have one Twilio balance for all subaccounts. If your main Twilio account is ever suspended, your subaccounts will also be suspended.

Skip to calculate billing for subaccounts >>


You can use your main account credentials (AccountSid and AuthToken) to access Twilio's REST API for your main account as well as any of your subaccounts. You may also use a subaccount's AccountSid and AuthToken to access the resources of that subaccount. You can not use a subaccount's credentials to access the resources of your main Twilio account or any other subaccounts.

If you're authenticating the helper libraries, pass in your main Account SID and main Auth Token as the first two credentials, and the appropriate Subaccount SID as the third parameter.

When performing CRUD operations within a subaccount use the subaccount SID and auth token. Alternativley you can generate API Keys at the subaccount level for authentication.


We are currently working on ways to help our customers minimize the risk of fraudulent international calls and provide ways for Twilio subaccounts to dial certain international destinations. If you have any questions, please contact support.


Subaccounts use the main account's voice and SMS messaging permissions.

Creating Subaccounts

To create a new subaccount, make an HTTP POST request to your Accounts list resource URI:


If successful, Twilio responds with a representation of the new Account resource.

POST Parameters

Optional Parameters

Your request to create a subaccount may include the following parameters:

Parameters in REST API format
post string PII MTL: 30 DAYS

A human readable description of the account to create, defaults to SubAccount Created at {YYYY-MM-DD HH:MM meridian}

The FriendlyName property is useful for organizing accounts and linking them back to information in your own system. For example, you may want to create subaccounts where the FriendlyName is the primary key of the customer in your application's database.


        Getting Started with Subaccounts

        Subaccounts are a great way to segment your Twilio usage and act on behalf of your customers, agents or employees.

        If you are running a hosted service that relies on Twilio you can create a Twilio subaccount for each customer that signs up. Then if a customer closes his or her account with your service, you can simply deactivate the associated Twilio subaccount.

        Subaccounts allow you to use the Twilio REST API just as you would for a single account; a subaccount can have its own phone numbers and caller IDs, applications and SIP Domains. You can manage a subaccount's calls, messagess, recordings, and transcriptions without affecting other subaccounts.

        Finding Subaccounts

        You can query any particular subaccount and its related resources via the REST API by AccountSid.


              If you don't know the AccountSid of a subaccount but you know the FriendlyName, you can query your Accounts list resource with a FriendlyName query string filter:


                    Making a phone call with a Subaccount

                    In order to make calls using a subaccount, use the subaccount's Account SID and Auth Token, as shown in lines 7 and 8 of the following code sample:


                          Sending a message from a Subaccount

                          In order to send messages using a subaccount, use the subaccount's Account SID and Auth Token when making your request to Twilio's Programmable Messaging API.


                                Calculate billing for Subaccount usage

                                In many cases you may want to calculate the billing incurred by a subaccount. Let's say you created a subaccount for a customer and you needed to charge them for their monthly usage.

                                You can iterate over all of the calls and sum up the product of price and duration. In this example you can see how to obtain the price.


                                      Suspending a Subaccount

                                      While an account is suspended it cannot make or receive phone calls or send and receive SMS messages. This is useful when your customer does not pay their bill and you want to suspend their account until a successful payment is received. However, you will be charged monthly for any phone numbers the subaccount owns.

                                      To suspend a subaccount, POST the parameter 'Status' with the value 'suspended' to suspend an account.

                                      Note that in-progress calls will not automatically end when a subaccount is subspended. This must be done manually by changing the status of these calls to completed.


                                            To reactivate a suspended subaccount, POST the value active for the Status parameter and we will restore the account to full service.


                                                  Note that you must use your main account's authentication credentials to suspend a subaccount. You cannot suspend your main account.

                                                  Closing a Subaccount

                                                  If your customer closes their account with you, you can permanently close the associated Twilio subaccount by POSTing the parameter Status with the value closed to the subaccount resource URI.


                                                        When you close a subaccount, Twilio will release all phone numbers assigned to it and shut it down completely. You can't ever use a closed account to make and receive phone calls or send and receive SMS messages. It's closed, gone, kaput – you cannot reopen a closed account.

                                                        Your closed subaccount will still appear in your accounts list, and you will still have access to historical data for that subaccount, unless automatic deletion of closed subaccounts is enabled.

                                                        If you have enabled automatic deletion of closed subaccounts through the Subaccounts settings page, we will delete all subaccount data 30 days after closure including previously closed subaccounts and those subaccounts will no longer appear on the Console.

                                                        • Twilio has enabled this setting for all accounts created after July 5, 2018, and for all accounts without subaccounts
                                                        • For all other accounts, account owners can turn this setting on through the Subaccounts settings page.

                                                        Note that you must use your main account's authentication credentials to close a subaccount. You also cannot close your main account.

                                                        Exchanging Phone Numbers Between Accounts

                                                        You can transfer numbers between subaccounts, and between your main account and any one of your subaccounts. You must use your main account's credentials when making the API request to transfer a phone number.

                                                        To transfer a phone number between two accounts that you control, make an HTTP POST request to an IncomingPhoneNumber instance resource URI. In the body of the POST set the parameter 'AccountSid' to the AccountSid of the account you wish to own that number. This will remove the phone number from its original account and make it available under the IncomingPhoneNumbers list resource of the new account while retaining all other properties.

                                                        If any of the phone numbers you would like to transfer have Address Requirements, you will need to create a compliant Address in the new subaccount before transferring the phone number.

                                                        Remember, closing a subaccount as described above will release all of that account's phone numbers, so you might consider transferring all numbers to your main account beforehand if you want to keep them.


                                                        Transfer a phone number from your primary account AC00000000000000000000000000000001 to subaccount AC00000000000000000000000000000002:

                                                              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 Community Forums or browsing the Twilio tag on Stack Overflow.


                                                                    Thank you for your feedback!

                                                                    We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

                                                                    Thanks for your feedback!

                                                                    Refer us and get $10 in 3 simple steps!

                                                                    Step 1

                                                                    Get link

                                                                    Get a free personal referral link here

                                                                    Step 2

                                                                    Give $10

                                                                    Your user signs up and upgrade using link

                                                                    Step 3

                                                                    Get $10

                                                                    1,250 free SMSes
                                                                    OR 1,000 free voice mins
                                                                    OR 12,000 chats
                                                                    OR more