You can also create subaccounts for your main accounts using the Twilio REST API. Subaccounts are useful for things like segmenting phone numbers and usage data on behalf of your customers, agents, or employees and controlling access to their data. This will allow you to manage the activity and resources of each customer independently.
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 their account with your service, you can deactivate the associated Twilio subaccount.
Subaccounts allow you to use the Twilio REST API just as you would for a single main account. A subaccount can have its phone numbers and caller IDs, applications and SIP Domains. You can manage a subaccount's calls, messages, recordings, and transcriptions without affecting other subaccounts.
Finally, subaccounts also have their separate Account Sid and Auth Token
NOTE:
- A main account can only have up to 1000 subaccounts by default. If you need more subaccounts, please contact support.
- By default, closed subaccounts will be automatically deleted 30 days after closure.
Billing
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 usage. You can iterate over all of the calls and sum up the product of price and duration.
The billing data is usually the costs incurred on outbound calls. Each call and its properties are added in the calls list/array from the response data. Learn more on the Call Resource API Reference page for detailed description of each property in the response.
Twilio bills all subaccount usage directly to your main account. That is, you will have one Twilio balance for all subaccounts. If your main Twilio account is suspended, your subaccounts will also be suspended.
See how to calculate billing for subaccounts >>.
Subaccounts Authentication
You can use your main account credentials - AccountSid and AuthToken to access Twilio's REST API resources with the v2010 version for any of your subaccounts. You may also use a subaccount's AccountSid and AuthToken to access the resources of that subaccount.
However, you cannot 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.
A few things to note!
WARNING
When performing CRUD operations within a subaccount, use the subaccount's SID and auth token. Alternatively, you can generate API Keys at the subaccount level for authentication.
WARNING
Main account API Keys are only available to access main account resources. Therefore, access to subaccount resources will be denied.
WARNING
Resources on subdomains, such as
studio.twilio.comandtaskrouter.twilio.com, must be accessed directly using subaccount credentials (API Keys or subaccount SID + subaccount auth token).There are many ways to determine if a resource lives on its own subdomain or under
v2010. One example method is to find the API Reference page for the resource. For example, the URL for the Workspace resource begins with<https://SOME-SUBDOMAIN.twilio.com>. Therefore, you must access that resource using subaccount credentials.If you do the same for some other resource, such as the Messaging resource, and see that URL begins with
/2010-04-01, this means it can be safely accessed using either your main account or subaccount credentials.
Subaccount Properties
When you create a subaccount, the properties below will be returned in the response:
| Properties | Description | PII status |
|---|---|---|
| auth_token string | The authorization token for this account. This token should be kept a secret, so no sharing. | PII MTL: 30 days |
| date_created string(date-time-rfc-2822) | The date that this account was created, in GMT in RFC 2822 format | NOT PII |
| date_updated string(date-time-rfc-2822) | The date that this account was last updated, in GMT in RFC 2822 format. | NOT PII |
| friendly_name string | A human readable description of this account, up to 64 characters long. By default the FriendlyName is your email address. | PII MTL: 30 days |
| owner_account_sid SID(AC) | The unique 34 character id that represents the parent of this account. Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34 | NOT PII |
| sid SID(AC) | A 34 character string that uniquely identifies this resource. Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34 | NOT PII |
| status enum(string) | The status of this account. Usually active, but can be suspended or closed.Possible values: active suspended closed | NOT PII |
| subresource_uris object(uri-map) | A Map of various subresources available for the given Account Instance | NOT PII |
| type enum(string) | The type of this account. Either Trial or Full if it's been upgraded. Default value is TrialPossible values: Trial Full | NOT PII |
| uri string | The URI for this resource, relative to https://api.twilio.com | NOT PII |
International Calls
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.
Permissions
Subaccounts use the main account's voice and SMS messaging permissions.