Skip to main content
Subaccounts let you manage multiple customer accounts under your main account. Each subaccount has its own Auth ID and Token, while charges deduct from the main account. API Endpoint 
https://api.plivo.com/v1/Account/{auth_id}/Subaccount/

​
The Subaccount Object

​
Attributes

​
auth_id
string
Auth ID of the subaccount.
​
auth_token
string
Auth Token of the subaccount.
​
name
string
Name of the subaccount.
​
enabled
boolean
Whether the subaccount is enabled.
​
account
string
URI to the parent account.
​
created
string
Date the subaccount was created.
​
modified
string
Date the subaccount was last modified.
​
resource_uri
string
URI to the subaccount resource.

​
Example Object

{
  "account": "/v1/Account/MA2025RK4E639VJFZAGV/",
  "api_id": "968f0a22-9237-11e7-a51d-0245fa790d9e",
  "auth_id": "SA2025RK4E639VJFZAMM",
  "auth_token": "NWM3YjliMjk0ZGYxMGM2YjJiYWE0MjEwZDM5YWU5",
  "created": "2022-09-05",
  "enabled": true,
  "modified": null,
  "name": "Subaccount Test",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Subaccount/SA2025RK4E639VJFZAMM/"
}

​
Create a Subaccount

Creates a new subaccount. 
POST https://api.plivo.com/v1/Account/{auth_id}/Subaccount/

​
Arguments

​
name
string
required
A human-readable name for the subaccount.
​
enabled
boolean
Whether the subaccount should be enabled. Default: false.

​
Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.subaccounts.create(
    name='Wayne Enterprises Subaccount',
    enabled=True)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.subAccounts.create('Test Subaccount', true)
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.subaccounts.create('Test Subaccount', true)
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->subaccounts->create('Test Subaccount', true);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.account.Subaccount;

Plivo.init("<auth_id>", "<auth_token>");

SubaccountCreateResponse response = Subaccount.creator("Test Subaccount")
    .enabled(true)
    .create();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Subaccount.Create(
    enabled: true,
    name: "Test Subaccount");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Subaccounts.Create(plivo.SubaccountCreateParams{
        Name:    "Test Subaccount",
        Enabled: true,
    })
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"name": "Test Subaccount", "enabled": true}' \
    https://api.plivo.com/v1/Account/{auth_id}/Subaccount/

​
Response

​
api_id
string
Unique identifier for the API request.
​
auth_id
string
Auth ID of the subaccount.
​
auth_token
string
Auth Token of the subaccount.
​
message
string
Status of the request. Returns created on a successful creation.
{
  "api_id": "324a7dd8-0db2-11e4-8a4a-123140008edf",
  "auth_id": "SA2025RK4E639VJFZAMM",
  "auth_token": "MTZjYWM0YzVjNjMwZmVmODFiNWJjNPJmOGJjZjgw",
  "message": "created"
}

​
Retrieve a Subaccount

Get details of a specific subaccount. 
GET https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/

​
Arguments

No arguments required.

​
Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.subaccounts.get(auth_id='SA2025RK4E639VJFZAMM')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.subaccounts.get('SA2025RK4E639VJFZAMM')
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.subaccounts.get('SA2025RK4E639VJFZAMM')
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->subaccounts->get('SA2025RK4E639VJFZAMM');
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.account.Subaccount;

Plivo.init("<auth_id>", "<auth_token>");

Subaccount response = Subaccount.getter("SA2025RK4E639VJFZAMM").get();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Subaccount.Get(id: "SA2025RK4E639VJFZAMM");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Subaccounts.Get("SA2025RK4E639VJFZAMM")
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/

​
Response

​
account
string
URI to the parent account.
​
api_id
string
Unique identifier for the API request.
​
auth_id
string
Auth ID of the subaccount.
​
auth_token
string
Auth Token of the subaccount.
​
created
string
Date the subaccount was created.
​
enabled
boolean
Whether the subaccount is enabled.
​
modified
string
Date the subaccount was last modified.
​
name
string
Name of the subaccount.
​
resource_uri
string
URI to the subaccount resource.
{
  "account": "/v1/Account/MA2025RK4E639VJFZAGV/",
  "api_id": "323972b2-0db3-11e4-a2d1-22000ac5040c",
  "auth_id": "SA2025RK4E639VJFZAMM",
  "auth_token": "MTZjYWM0YzVjNjMwZmVmODFiNWJjNWJmOGJjZjgw",
  "created": "2022-07-17",
  "enabled": false,
  "modified": null,
  "name": "Han Solo",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Subaccount/SA2025RK4E639VJFZAMM/"
}

​
List All Subaccounts

Returns all subaccounts sorted by creation date, newest first. 
GET https://api.plivo.com/v1/Account/{auth_id}/Subaccount/

​
Arguments

​
limit
integer
Results per page. Maximum 20.
​
offset
integer
Pagination offset.

​
Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.subaccounts.list(offset=0, limit=5)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.subaccounts.list({ offset: 0, limit: 5 })
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.subaccounts.list(limit: 5, offset: 0)
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->subaccounts->list(3, 2);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.account.Subaccount;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<Subaccount> response = Subaccount.lister()
    .offset(0)
    .limit(5)
    .list();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Subaccount.List(limit: 5, offset: 0);
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Subaccounts.List(plivo.SubaccountListParams{
        Offset: 0,
        Limit:  5,
    })
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Subaccount/

​
Response

​
api_id
string
Unique identifier for the API request.
​
meta
object
Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching subaccounts).
​
objects
array
Array of subaccount objects — see The Subaccount Object.
{
  "api_id": "b38bf42e-0db4-11e4-8a4a-123140008edf",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "account": "/v1/Account/MA2025RK4E639VJFZAGV/",
      "auth_id": "SA2025RK4E639VJFZAMM",
      "auth_token": "MTZjYWM0YzVjNjMwZmVmODFiNWJjNWJmOGJjZjgw",
      "created": "2022-07-17",
      "enabled": false,
      "modified": null,
      "name": "Chewbacca",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Subaccount/SA2025RK4E639VJFZAMM/"
    }
  ]
}

​
Update a Subaccount

Updates a subaccount. Parameters not provided remain unchanged. 
POST https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/

​
Arguments

​
name
string
required
Name of the subaccount.
​
enabled
boolean
Whether the subaccount should be enabled.

​
Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.subaccounts.update(
    auth_id='SA2025RK4E639VJFZAMM',
    name='Updated Subaccount Name')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.subaccounts.update('SA2025RK4E639VJFZAMM', 'Updated Subaccount Name')
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.subaccounts.update(
    'SA2025RK4E639VJFZAMM',
    'Updated Subaccount Name',
    false)
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->subaccounts->update(
    'SA2025RK4E639VJFZAMM',
    'Updated Subaccount Name');
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.account.Subaccount;

Plivo.init("<auth_id>", "<auth_token>");

SubaccountUpdateResponse response = Subaccount.updater("SA2025RK4E639VJFZAMM", "Updated Subaccount Name")
    .update();
System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Subaccount.Update(
    id: "SA2025RK4E639VJFZAMM",
    name: "Updated Subaccount Name");
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Subaccounts.Update("SA2025RK4E639VJFZAMM", plivo.SubaccountUpdateParams{
        Name: "Updated Subaccount Name",
    })
    fmt.Println(response)
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"name": "Updated Subaccount Name"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/

​
Response

​
message
string
Status of the request. Returns changed on a successful update.
​
api_id
string
Unique identifier for the API request.
{
  "message": "changed",
  "api_id": "5a9fcb68-523d-11e1-86da-6ff39efcb949"
}

​
Delete a Subaccount

Permanently deletes a subaccount. 
DELETE https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/

​
Arguments

​
cascade
boolean
If true, deletes associated Applications, Endpoints, and Numbers. If false, maps them to the main account. Default: false.

​
Example

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.subaccounts.delete(
    auth_id='SA2025RK4E639VJFZAMM',
    cascade=True)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.subaccounts.delete('SA2025RK4E639VJFZAMM', true)
    .then(response => console.log(response));

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.subaccounts.delete('SA2025RK4E639VJFZAMM', true)
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->subaccounts->delete('SA2025RK4E639VJFZAMM', true);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.account.Subaccount;

Plivo.init("<auth_id>", "<auth_token>");

Subaccount.deleter("SA2025RK4E639VJFZAMM").cascade(true).delete();
System.out.println("Deleted successfully.");

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Subaccount.Delete(
    id: "SA2025RK4E639VJFZAMM",
    cascade: true);
Console.WriteLine(response);

package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    err := client.Subaccounts.Delete("SA2025RK4E639VJFZAMM", plivo.SubaccountDeleteParams{Cascade: true})
    if err == nil {
        fmt.Println("Deleted successfully.")
    }
}

curl -X DELETE --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Subaccount/{subauth_id}/

​
Response

HTTP Status Code: 204