Get Started

REST API: Subaccounts

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

For instance, 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, SMSs, recordings, and transcriptions without affecting other subaccounts.

Note: A master account can only have 1000 subaccounts by default. If you need more please email us at help@twilio.com

Billing

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

Authentication

You can use your master Twilio Account credentials (AccountSid and AuthToken) to access Twilio's REST API for your master 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 master Twilio account or any other subaccounts.

International

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 questions, contact help@twilio.com.

Permissions

Subaccounts use the master 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:

/2010-04-01/Accounts

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:

Parameter Description
FriendlyName A human readable description of the new subaccount, up to 64 characters. 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.

Example

Finding Subaccounts

You can query any particular subaccount and its related resources via the REST API by using that its AccountSid in your URLs. For example:

Example 1: Return a subaccount resource by its AccountSid
Example 2: Find an account by its FriendlyName

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

Suspending a Subaccount

You can suspend a subaccount if you don't want it to incur any usage charges, however, you will be charged the monthly fee for every Twilio phone number owned by your subaccounts, even when they are suspended. 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.

Simply POST the parameter 'Status' with the value 'suspended' to suspend an account. While suspended, the subaccount will not be able to make or receive phone calls, send or receive SMS messages, etc.

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

For details and an example, see the Account instance resource POST section.

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

Closing a Subaccount

If your customer closes his or her 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. It will still appear in your accounts list, and you will still have access to historical data for that subaccount, but you cannot reopen a closed account.

For details and an example, see the Account instance resource POST section.

Note that you must use your master account's authentication credentials to close a subaccount. Also you cannot close your master account.

Exchanging Phone Numbers Between Accounts

You can transfer numbers between subaccounts, and between your master account and any one of your subaccounts. You must use your master 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.

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 master account beforehand if you want to keep them.

Example

Transfer a phone number from account AC00000000000000000000000000000001 to AC00000000000000000000000000000002: