Twilio Subaccounts: Build Multi-Tenant Apps with Twilio

February 02, 2011
Written by

Twilio Bug Logo

Today we’re excited to release Twilio Subaccounts, a powerful developer productivity tool that is perfect for Twilio customers who are building multi-tenant web services and need the ability to track usage of each user independently from one another. Subaccounts also help those of you who are powering several projects under one account and want to divide up usage of phone calls and text messages.

Subaccounts are controlled by your original main account. All usage by a subaccount is billed up to the main account.  Ready to jump in now?  Go for it:

Managing Multi-Tenant Apps with Twilio

Subaccounts are useful if you intend to build a web based service where users sign up and you then resell Twilio services, such as OpenVBX. By segmenting your users into subaccounts, you can use Twilio to track the usage of individual customers. This can help you when it comes time to perform user specific reporting or generate invoices.

With subaccounts, you can use the Twilio REST API just as you would for a single main account. Subaccounts can have their own account sids, phone numbers and caller IDs, etc. You can manage a subaccount’s calls, SMS, recordings, and transcriptions without affecting other subaccounts.  You can also make outbound calls and send SMS messages using the account sid and credentials of a specific subaccount.

Twilio Subaccount Features

There are a several other useful features unique to subaccounts that can help you to manage your Twilio empire.

Transferring Numbers Between Subaccounts

You can transfer numbers between subaccounts or your main account by making an HTTP POST request to an IncomingPhoneNumber instance resource URI. Check out the documentation of how to transfer numbers between subaccounts for more details and examples.

Suspending Subaccounts

With Twilio subaccounts you have the ability to suspend usage for a particular subaccount, which is useful in cases where you’re waiting for a customer to make payment. If you suspend a subaccount, it won’t incur any more usage charges because calls and text messages will be disabled. When you’re ready to resume operations for the subaccount, you may set it back to an active state.

Closing Subaccounts

If your customer decides to stop doing business with you, you can also permanently close a Twilio subaccount, which will release all phone numbers and prevent further usage on that subaccount.

How To Use Twilio Subaccounts

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

Tada! You have a subaccount. Now you can then assign phone numbers, place calls, send SMS messages, etc., using a subaccount’s sid in the URL. Similarly, you can retrieve call records, SMS logs, notifications, etc. via that account’s REST URIs. It’s just like using Twilio normally, but with the ability to swap out the account sid in the URL!

Try it Out!

You can find the complete documentation for subaccounts in the Twilio REST API reference, or check out code examples of creating a subaccount in the How To: Using Twilio Subaccounts. The HowTo also illustrates adding new numbers, reporting on usage and applying a custom consumer facing price structure to your Twilio application.

The subaccounts API is activated for all existing and new Twilio customers.  Currently, subaccount data is not available in the Twilio account portal, but UI support will be be coming soon.

You can start using them in your applications immediately. If you have any questions, feel free to send us an email at help@twilio.com or post a question in the forums.