Subaccount API

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.

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

Concepts

API Reference

Subaccount API

The Subaccount Object

Attributes

Example Object

Create a Subaccount

Arguments

Example

Response

Retrieve a Subaccount

Arguments

Example

Response

List All Subaccounts

Arguments

Example

Response

Update a Subaccount

Arguments

Example

Response

Delete a Subaccount

Arguments

Example

Response

​The Subaccount Object

​Attributes

​Example Object

​Create a Subaccount

​Arguments

​Example

​Response

​Retrieve a Subaccount

​Arguments

​Example

​Response

​List All Subaccounts

​Arguments

​Example

​Response

​Update a Subaccount

​Arguments

​Example

​Response

​Delete a Subaccount

​Arguments

​Example

​Response

The Subaccount Object

Attributes

Example Object

Create a Subaccount

Arguments

Example

Response

Retrieve a Subaccount

Arguments

Example

Response

List All Subaccounts

Arguments

Example

Response

Update a Subaccount

Arguments

Example

Response

Delete a Subaccount

Arguments

Example

Response