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

string

Auth ID of the subaccount.

string

Auth Token of the subaccount.

string

Name of the subaccount.

boolean

Whether the subaccount is enabled.

string

URI to the parent account.

string

Date the subaccount was created.

string

Date the subaccount was last modified.

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

string

required

A human-readable name for the subaccount.

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

string

Unique identifier for the API request.

string

Auth ID of the subaccount.

string

Auth Token of the subaccount.

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

string

URI to the parent account.

string

Unique identifier for the API request.

string

Auth ID of the subaccount.

string

Auth Token of the subaccount.

string

Date the subaccount was created.

boolean

Whether the subaccount is enabled.

string

Date the subaccount was last modified.

string

Name of the subaccount.

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

integer

Results per page. Maximum 20.

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

string

Unique identifier for the API request.

object

Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching subaccounts).

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

string

required

Name of the subaccount.

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

string

Status of the request. Returns changed on a successful update.

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

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