Subaccounts in Twilio are accounts that are "owned" by your main 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 manage the activity and resources of each customer independently.
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 v2010 API resources for 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. Alternatively, you can generate API Keys at the subaccount level for authentication.
Main account API Keys are only available to access main account resources. Access to subaccount resources will be denied.
Your main account credentials will allow you to access resources for any of your subaccounts that fall under the v2010 REST API. However, resources on subdomains, such as studio.twilio.com
and taskrouter.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, such as the Workspace resource. Observe the returned URL
value in the example payloads: if the URL begins with https://SOME-SUBDOMAIN.twilio.com
, then you must access that resource using subaccount-specific credentials. If you do the same for some other resource, such as the Messaging resource, and see that URI
begins with /2010-04-01
, then it can be safely accessed using either your main account or subaccount credentials.
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.
To create a new subaccount, make an HTTP POST
request to your Accounts list resource URI:
1/2010-04-01/Accounts2
If successful, Twilio responds with a representation of the new Account resource.
Your request to create a subaccount may include the following parameters:
application/x-www-form-urlencoded
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 system. For example, you may want to create subaccounts where the FriendlyName is the primary key of the customer in your application's database.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createAccount() {11const account = await client.api.v2010.accounts.create({12friendlyName: "Submarine",13});1415console.log(account.authToken);16}1718createAccount();
1{2"auth_token": "auth_token",3"date_created": "Thu, 30 Jul 2015 20:00:00 +0000",4"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",5"friendly_name": "Submarine",6"owner_account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",8"status": "active",9"subresource_uris": {10"available_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json",11"calls": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json",12"conferences": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conferences.json",13"incoming_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json",14"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",15"outgoing_caller_ids": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OutgoingCallerIds.json",16"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",17"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",18"addresses": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses.json",19"signing_keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SigningKeys.json",20"connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ConnectApps.json",21"sip": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SIP.json",22"authorized_connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AuthorizedConnectApps.json",23"usage": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Usage.json",24"keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json",25"applications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json",26"short_codes": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json",27"queues": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Queues.json",28"messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json",29"balance": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Balance.json"30},31"type": "Full",32"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"33}
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 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 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.
You can query any particular subaccount and its related resources via the REST API by AccountSid.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchAccount() {11const account = await client.api.v201012.accounts("ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.fetch();1415console.log(account.authToken);16}1718fetchAccount();
1{2"auth_token": "auth_token",3"date_created": "Thu, 30 Jul 2015 20:00:00 +0000",4"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",5"friendly_name": "friendly_name",6"owner_account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",8"status": "active",9"subresource_uris": {10"available_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json",11"calls": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json",12"conferences": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conferences.json",13"incoming_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json",14"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",15"outgoing_caller_ids": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OutgoingCallerIds.json",16"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",17"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",18"addresses": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses.json",19"signing_keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SigningKeys.json",20"connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ConnectApps.json",21"sip": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SIP.json",22"authorized_connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AuthorizedConnectApps.json",23"usage": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Usage.json",24"keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json",25"applications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json",26"short_codes": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json",27"queues": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Queues.json",28"messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json",29"balance": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Balance.json"30},31"type": "Full",32"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"33}
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:
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listAccount() {11const accounts = await client.api.v2010.accounts.list({12friendlyName: "MySubaccount",13limit: 20,14});1516accounts.forEach((a) => console.log(a.authToken));17}1819listAccount();
1{2"first_page_uri": "/2010-04-01/Accounts.json?FriendlyName=friendly_name&Status=active&PageSize=50&Page=0",3"end": 0,4"previous_page_uri": null,5"accounts": [],6"uri": "/2010-04-01/Accounts.json?FriendlyName=friendly_name&Status=active&PageSize=50&Page=0",7"page_size": 50,8"start": 0,9"next_page_uri": null,10"page": 011}
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:
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const subaccountSid = process.env.TWILIO_SUBACCOUNT_SID;9const client = twilio(accountSid, authToken, { accountSid: subaccountSid });1011async function createCall() {12const call = await client.calls.create({13from: "+14158141829",14to: "+16518675310",15url: "http://twimlets.com/message?Message%5B0%5D=Hello%20from%20your%20subaccount",16});1718console.log(call.sid);19}2021createCall();
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"annotation": null,4"answered_by": null,5"api_version": "2010-04-01",6"caller_name": null,7"date_created": "Tue, 31 Aug 2010 20:36:28 +0000",8"date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",9"direction": "inbound",10"duration": "15",11"end_time": "Tue, 31 Aug 2010 20:36:44 +0000",12"forwarded_from": "+141586753093",13"from": "+14158141829",14"from_formatted": "(415) 867-5308",15"group_sid": null,16"parent_call_sid": null,17"phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",18"price": "-0.03000",19"price_unit": "USD",20"sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",21"start_time": "Tue, 31 Aug 2010 20:36:29 +0000",22"status": "completed",23"subresource_uris": {24"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",25"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",26"payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",27"events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",28"siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",29"streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",30"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",31"user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",32"user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"33},34"to": "+16518675310",35"to_formatted": "(415) 867-5309",36"trunk_sid": null,37"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",38"queue_time": "1000"39}
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const subaccountSid = process.env.TWILIO_SUBACCOUNT_SID;9const client = twilio(accountSid, authToken, { accountSid: subaccountSid });1011async function createMessage() {12const message = await client.messages.create({13body: "Ahoy there!",14from: "+14158141829",15to: "+16518675310",16});1718console.log(message.body);19}2021createMessage();
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"api_version": "2010-04-01",4"body": "Ahoy there!",5"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",6"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",7"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",8"direction": "outbound-api",9"error_code": null,10"error_message": null,11"from": "+14158141829",12"num_media": "0",13"num_segments": "1",14"price": null,15"price_unit": null,16"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",17"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",18"status": "queued",19"subresource_uris": {20"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"21},22"tags": {23"campaign_name": "Spring Sale 2022",24"message_type": "cart_abandoned"25},26"to": "+16518675310",27"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"28}
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 example below shows the API request to fetch all Calls that began on January 15, 2018. In the response, each object in the calls
array contains a price
property.
Note: In this example, the StartTime
parameter returns calls only that began on January 15, 2018. You can also use inequalities (e.g. <=
and >=
) and the EndTime
parameter to fetch all Calls from a specific date span. Learn more on the Call Resource API Reference page.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const subaccountSid = process.env.TWILIO_SUBACCOUNT_SID;9const client = twilio(accountSid, authToken, { accountSid: subaccountSid });1011async function listCall() {12const calls = await client.calls.list({13startTime: new Date("2018-01-15 00:00:00"),14limit: 20,15});1617calls.forEach((c) => console.log(c.price));18}1920listCall();
1{2"calls": [3{4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"annotation": "billingreferencetag1",6"answered_by": "machine_start",7"api_version": "2010-04-01",8"caller_name": "callerid1",9"date_created": "Fri, 18 Oct 2019 17:00:00 +0000",10"date_updated": "Fri, 18 Oct 2019 17:01:00 +0000",11"direction": "outbound-api",12"duration": "4",13"end_time": "Fri, 18 Oct 2019 17:03:00 +0000",14"forwarded_from": "calledvia1",15"from": "+13051416799",16"from_formatted": "(305) 141-6799",17"group_sid": "GPdeadbeefdeadbeefdeadbeefdeadbeef",18"parent_call_sid": "CAdeadbeefdeadbeefdeadbeefdeadbeef",19"phone_number_sid": "PNdeadbeefdeadbeefdeadbeefdeadbeef",20"price": "-0.200",21"price_unit": "USD",22"sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",23"start_time": "Fri, 18 Oct 2019 17:02:00 +0000",24"status": "completed",25"subresource_uris": {26"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",27"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",28"payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",29"events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",30"siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",31"streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",32"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",33"user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",34"user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"35},36"to": "+13051913581",37"to_formatted": "(305) 191-3581",38"trunk_sid": "TKdeadbeefdeadbeefdeadbeefdeadbeef",39"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",40"queue_time": "1000"41},42{43"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",44"annotation": "billingreferencetag2",45"answered_by": "human",46"api_version": "2010-04-01",47"caller_name": "callerid2",48"date_created": "Fri, 18 Oct 2019 16:00:00 +0000",49"date_updated": "Fri, 18 Oct 2019 16:01:00 +0000",50"direction": "inbound",51"duration": "3",52"end_time": "Fri, 18 Oct 2019 16:03:00 +0000",53"forwarded_from": "calledvia2",54"from": "+13051416798",55"from_formatted": "(305) 141-6798",56"group_sid": "GPdeadbeefdeadbeefdeadbeefdeadbeee",57"parent_call_sid": "CAdeadbeefdeadbeefdeadbeefdeadbeee",58"phone_number_sid": "PNdeadbeefdeadbeefdeadbeefdeadbeee",59"price": "-0.100",60"price_unit": "JPY",61"sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0",62"start_time": "Fri, 18 Oct 2019 16:02:00 +0000",63"status": "completed",64"subresource_uris": {65"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Notifications.json",66"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Recordings.json",67"payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Payments.json",68"events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Events.json",69"siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Siprec.json",70"streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Streams.json",71"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/Transcriptions.json",72"user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/UserDefinedMessageSubscriptions.json",73"user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0/UserDefinedMessages.json"74},75"to": "+13051913580",76"to_formatted": "(305) 191-3580",77"trunk_sid": "TKdeadbeefdeadbeefdeadbeefdeadbeef",78"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0.json",79"queue_time": "1000"80}81],82"end": 1,83"first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json?Status=completed&To=%2B123456789&From=%2B987654321&StartTime=2008-01-02&ParentCallSid=CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&EndTime=2009-01-02&PageSize=2&Page=0",84"next_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json?Status=completed&To=%2B123456789&From=%2B987654321&StartTime=2008-01-02&ParentCallSid=CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&EndTime=2009-01-02&PageSize=2&Page=1&PageToken=PACAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0",85"page": 0,86"page_size": 2,87"previous_page_uri": null,88"start": 0,89"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json?Status=completed&To=%2B123456789&From=%2B987654321&StartTime=2008-01-02&ParentCallSid=CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&EndTime=2009-01-02&PageSize=2&Page=0"90}
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 suspended. This must be done manually by changing the status of these calls to completed
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateAccount() {11const account = await client.api.v201012.accounts("ACXXXX-SUBACCOUNT-SID-XXXX")13.update({ status: "suspended" });1415console.log(account.sid);16}1718updateAccount();
1{2"auth_token": "auth_token",3"date_created": "Thu, 30 Jul 2015 20:00:00 +0000",4"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",5"friendly_name": "friendly_name",6"owner_account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"sid": "ACXXXX-SUBACCOUNT-SID-XXXX",8"status": "suspended",9"subresource_uris": {10"available_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json",11"calls": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json",12"conferences": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conferences.json",13"incoming_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json",14"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",15"outgoing_caller_ids": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OutgoingCallerIds.json",16"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",17"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",18"addresses": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses.json",19"signing_keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SigningKeys.json",20"connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ConnectApps.json",21"sip": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SIP.json",22"authorized_connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AuthorizedConnectApps.json",23"usage": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Usage.json",24"keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json",25"applications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json",26"short_codes": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json",27"queues": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Queues.json",28"messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json",29"balance": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Balance.json"30},31"type": "Full",32"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"33}
To reactivate a suspended subaccount, POST
the value active
for the
Status
parameter and we will restore the account to full service.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateAccount() {11const account = await client.api.v201012.accounts("ACXXXX-SUBACCOUNT-SID-XXXX")13.update({ status: "active" });1415console.log(account.authToken);16}1718updateAccount();
1{2"auth_token": "auth_token",3"date_created": "Thu, 30 Jul 2015 20:00:00 +0000",4"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",5"friendly_name": "friendly_name",6"owner_account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"sid": "ACXXXX-SUBACCOUNT-SID-XXXX",8"status": "active",9"subresource_uris": {10"available_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json",11"calls": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json",12"conferences": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conferences.json",13"incoming_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json",14"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",15"outgoing_caller_ids": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OutgoingCallerIds.json",16"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",17"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",18"addresses": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses.json",19"signing_keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SigningKeys.json",20"connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ConnectApps.json",21"sip": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SIP.json",22"authorized_connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AuthorizedConnectApps.json",23"usage": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Usage.json",24"keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json",25"applications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json",26"short_codes": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json",27"queues": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Queues.json",28"messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json",29"balance": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Balance.json"30},31"type": "Full",32"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"33}
Note that you must use your main account's authentication credentials to suspend a subaccount. You cannot suspend your main account.
If your customer closes their account with you, you can permanently close
the associated Twilio subaccount by POST
ing the parameter Status
with the
value closed
to the subaccount resource URI.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateAccount() {11const account = await client.api.v201012.accounts("ACXXXX-SUBACCOUNT-SID-XXXX")13.update({ status: "closed" });1415console.log(account.authToken);16}1718updateAccount();
1{2"auth_token": "auth_token",3"date_created": "Thu, 30 Jul 2015 20:00:00 +0000",4"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",5"friendly_name": "friendly_name",6"owner_account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"sid": "ACXXXX-SUBACCOUNT-SID-XXXX",8"status": "closed",9"subresource_uris": {10"available_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json",11"calls": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json",12"conferences": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conferences.json",13"incoming_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json",14"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",15"outgoing_caller_ids": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OutgoingCallerIds.json",16"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",17"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",18"addresses": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses.json",19"signing_keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SigningKeys.json",20"connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ConnectApps.json",21"sip": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SIP.json",22"authorized_connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AuthorizedConnectApps.json",23"usage": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Usage.json",24"keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json",25"applications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json",26"short_codes": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json",27"queues": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Queues.json",28"messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json",29"balance": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Balance.json"30},31"type": "Full",32"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"33}
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.
Note that you must use your main account's authentication credentials to close a subaccount. You also cannot close your main account.
If you have a WhatsApp Sender connected to your phone number, it will not be moved to the gaining account SID. To move phone numbers connected to WhatsApp Senders, open a support ticket to move the WhatsApp Sender before moving the phone number.
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.
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:
1// Download the helper library from https://www.twilio.com/docs/node/install2// Your Account Sid and Auth Token from twilio.com/console3// To set up environmental variables, see http://twil.io/secure4const accountSid = process.env.TWILIO_ACCOUNT_SID;5const authToken = process.env.TWILIO_AUTH_TOKEN;6const client = require('twilio')(accountSid, authToken);78client.incomingPhoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')9.update({accountSid: process.env.TWILIO_SUB_ACCOUNT_SID})10.then(incoming_phone_number => console.log(incoming_phone_number.friendlyName));
1{2"account_sid": "AC00000000000000000000000000000002",3"address_requirements": "none",4"address_sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"api_version": "2010-04-01",6"beta": false,7"capabilities": {8"mms": true,9"sms": false,10"voice": true11},12"date_created": "Thu, 30 Jul 2015 23:19:04 +0000",13"date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",14"emergency_status": "Inactive",15"emergency_address_sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",16"friendly_name": "My Company Line",17"identity_sid": "RIXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",18"origin": "origin",19"phone_number": "+15105647903",20"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",21"sms_application_sid": null,22"sms_fallback_method": "POST",23"sms_fallback_url": "",24"sms_method": "POST",25"sms_url": "",26"status_callback": "",27"status_callback_method": "POST",28"trunk_sid": null,29"uri": "/2010-04-01/Accounts/AC00000000000000000000000000000002/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",30"voice_application_sid": null,31"voice_caller_id_lookup": false,32"voice_fallback_method": "POST",33"voice_fallback_url": null,34"voice_method": "POST",35"voice_url": null36}