Create a new Sub-Account API

POST

sub-accounts

create

cURL

curl --request POST \
  --url https://api.bolna.ai/sub-accounts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "alpha-007",
  "min_concurrency": 5,
  "max_concurrency": 20,
  "multi_tenant": false,
  "db_host": "prod-alpha-007-db-east-1.my-database.com",
  "db_name": "alpha-007_db",
  "db_port": 5432,
  "db_user": "alpha-007_user",
  "db_password": "alpha-007_password"
}
'

import requests

url = "https://api.bolna.ai/sub-accounts/create"

payload = {
    "name": "alpha-007",
    "min_concurrency": 5,
    "max_concurrency": 20,
    "multi_tenant": False,
    "db_host": "prod-alpha-007-db-east-1.my-database.com",
    "db_name": "alpha-007_db",
    "db_port": 5432,
    "db_user": "alpha-007_user",
    "db_password": "alpha-007_password"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'alpha-007',
    min_concurrency: 5,
    max_concurrency: 20,
    multi_tenant: false,
    db_host: 'prod-alpha-007-db-east-1.my-database.com',
    db_name: 'alpha-007_db',
    db_port: 5432,
    db_user: 'alpha-007_user',
    db_password: 'alpha-007_password'
  })
};

fetch('https://api.bolna.ai/sub-accounts/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/sub-accounts/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'alpha-007',
    'min_concurrency' => 5,
    'max_concurrency' => 20,
    'multi_tenant' => false,
    'db_host' => 'prod-alpha-007-db-east-1.my-database.com',
    'db_name' => 'alpha-007_db',
    'db_port' => 5432,
    'db_user' => 'alpha-007_user',
    'db_password' => 'alpha-007_password'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/sub-accounts/create"

	payload := strings.NewReader("{\n  \"name\": \"alpha-007\",\n  \"min_concurrency\": 5,\n  \"max_concurrency\": 20,\n  \"multi_tenant\": false,\n  \"db_host\": \"prod-alpha-007-db-east-1.my-database.com\",\n  \"db_name\": \"alpha-007_db\",\n  \"db_port\": 5432,\n  \"db_user\": \"alpha-007_user\",\n  \"db_password\": \"alpha-007_password\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bolna.ai/sub-accounts/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"alpha-007\",\n  \"min_concurrency\": 5,\n  \"max_concurrency\": 20,\n  \"multi_tenant\": false,\n  \"db_host\": \"prod-alpha-007-db-east-1.my-database.com\",\n  \"db_name\": \"alpha-007_db\",\n  \"db_port\": 5432,\n  \"db_user\": \"alpha-007_user\",\n  \"db_password\": \"alpha-007_password\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/sub-accounts/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"alpha-007\",\n  \"min_concurrency\": 5,\n  \"max_concurrency\": 20,\n  \"multi_tenant\": false,\n  \"db_host\": \"prod-alpha-007-db-east-1.my-database.com\",\n  \"db_name\": \"alpha-007_db\",\n  \"db_port\": 5432,\n  \"db_user\": \"alpha-007_user\",\n  \"db_password\": \"alpha-007_password\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "alpha-007",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "api_key": "sa-b33f4fbf011d4661a273a46b11d185f8",
  "multi_tenant": false,
  "db_host": null,
  "db_name": null,
  "db_port": null,
  "db_user": null,
  "db_password": null,
  "min_concurrency": 5,
  "max_concurrency": 20,
  "created_at": "2025-01-23T01:14:37Z",
  "updated_at": "2025-01-23T01:14:37Z"
}

This is an enterprise feature.You can read more about our enterprise offering here Bolna enterprise.

Only organization admins can create sub-accounts.

Concurrency

Every sub-account is created with a concurrency envelope:

min_concurrency — concurrency guaranteed to this sub-account even when the organization is at capacity. Use 0 for no guarantee.
max_concurrency — the sub-account’s hard cap. Omit it for an elastic sub-account that can burst into the organization’s unused capacity; set 0 to pause the sub-account.

The request is rejected with 400 if the per-account minimums or maximums would exceed the organization’s envelope. See Concurrency management for how guarantees, caps, and shared capacity work together.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Payload for creating a new sub-account

name

string

required

Name of the sub-account

Example:

"alpha-007"

min_concurrency

integer

required

Guaranteed concurrency reserved for this sub-account even when the organization is at capacity. 0 means no guarantee.

Example:

5

max_concurrency

integer

Hard cap on this sub-account's concurrency. Omit (or send null) for an elastic account that can burst into the organization's unused capacity. 0 pauses the sub-account.

Example:

20

multi_tenant

boolean

default:false

The sub-account is stored in a separate database

db_host

string

Database host for multi_tenant sub-account

Example:

"prod-alpha-007-db-east-1.my-database.com"

db_name

string

Database name for multi_tenant sub-account

Example:

"alpha-007_db"

db_port

string

Database port for multi_tenant sub-account

Example:

5432

db_user

string

Database root user for multi_tenant sub-account

Example:

"alpha-007_user"

db_password

string

Database root password for multi_tenant sub-account

Example:

"alpha-007_password"

Response

Sub-account create response

string<uuid>

Unque identifier for the created sub-account

name

string

Name of the sub-account

Example:

"alpha-007"

user_id

string<uuid>

ID of the user who created the sub-account

organization_id

string<uuid>

Organization ID the sub-account belongs to

api_key

string

Sub-account API Key used to interact with sub-account resources like agents, executions, batches, etc.

Pattern: ^sa-[a-f0-9]{32}$

Example:

"sa-b33f4fbf011d4661a273a46b11d185f8"

multi_tenant

boolean

Whether the sub-account is being stored in a separate database

Example:

false

db_host

string

Database host if the sub-account is multi_tenant:true

Example:

null

db_name

string

Database name if the sub-account is multi_tenant:true

Example:

null

db_port

string

Database port if the sub-account is multi_tenant:true

Example:

null

db_user

string

Database root user if the sub-account is multi_tenant:true

Example:

null

db_password

string

Database root password if the sub-account is multi_tenant:true

Example:

null

min_concurrency

integer

Guaranteed concurrency reserved for this sub-account even when the organization is at capacity. 0 means no guarantee.

Example:

5

max_concurrency

integer

Hard cap on this sub-account's concurrency. Omit (or send null) for an elastic account that can burst into the organization's unused capacity. 0 pauses the sub-account.

Example:

20

created_at

string<date-time>

Timestamp of sub-account creation

Example:

"2025-01-23T01:14:37Z"

updated_at

string<date-time>

Timestamp of sub-account updation

Example:

"2025-01-23T01:14:37Z"

List Sub-AccountsRetrieve all sub-accounts linked to your main account enabling centralized visibility and management.

⌘I

cURL

curl --request POST \
  --url https://api.bolna.ai/sub-accounts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "alpha-007",
  "min_concurrency": 5,
  "max_concurrency": 20,
  "multi_tenant": false,
  "db_host": "prod-alpha-007-db-east-1.my-database.com",
  "db_name": "alpha-007_db",
  "db_port": 5432,
  "db_user": "alpha-007_user",
  "db_password": "alpha-007_password"
}
'

import requests

url = "https://api.bolna.ai/sub-accounts/create"

payload = {
    "name": "alpha-007",
    "min_concurrency": 5,
    "max_concurrency": 20,
    "multi_tenant": False,
    "db_host": "prod-alpha-007-db-east-1.my-database.com",
    "db_name": "alpha-007_db",
    "db_port": 5432,
    "db_user": "alpha-007_user",
    "db_password": "alpha-007_password"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'alpha-007',
    min_concurrency: 5,
    max_concurrency: 20,
    multi_tenant: false,
    db_host: 'prod-alpha-007-db-east-1.my-database.com',
    db_name: 'alpha-007_db',
    db_port: 5432,
    db_user: 'alpha-007_user',
    db_password: 'alpha-007_password'
  })
};

fetch('https://api.bolna.ai/sub-accounts/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/sub-accounts/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'alpha-007',
    'min_concurrency' => 5,
    'max_concurrency' => 20,
    'multi_tenant' => false,
    'db_host' => 'prod-alpha-007-db-east-1.my-database.com',
    'db_name' => 'alpha-007_db',
    'db_port' => 5432,
    'db_user' => 'alpha-007_user',
    'db_password' => 'alpha-007_password'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/sub-accounts/create"

	payload := strings.NewReader("{\n  \"name\": \"alpha-007\",\n  \"min_concurrency\": 5,\n  \"max_concurrency\": 20,\n  \"multi_tenant\": false,\n  \"db_host\": \"prod-alpha-007-db-east-1.my-database.com\",\n  \"db_name\": \"alpha-007_db\",\n  \"db_port\": 5432,\n  \"db_user\": \"alpha-007_user\",\n  \"db_password\": \"alpha-007_password\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bolna.ai/sub-accounts/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"alpha-007\",\n  \"min_concurrency\": 5,\n  \"max_concurrency\": 20,\n  \"multi_tenant\": false,\n  \"db_host\": \"prod-alpha-007-db-east-1.my-database.com\",\n  \"db_name\": \"alpha-007_db\",\n  \"db_port\": 5432,\n  \"db_user\": \"alpha-007_user\",\n  \"db_password\": \"alpha-007_password\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/sub-accounts/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"alpha-007\",\n  \"min_concurrency\": 5,\n  \"max_concurrency\": 20,\n  \"multi_tenant\": false,\n  \"db_host\": \"prod-alpha-007-db-east-1.my-database.com\",\n  \"db_name\": \"alpha-007_db\",\n  \"db_port\": 5432,\n  \"db_user\": \"alpha-007_user\",\n  \"db_password\": \"alpha-007_password\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "alpha-007",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "api_key": "sa-b33f4fbf011d4661a273a46b11d185f8",
  "multi_tenant": false,
  "db_host": null,
  "db_name": null,
  "db_port": null,
  "db_user": null,
  "db_password": null,
  "min_concurrency": 5,
  "max_concurrency": 20,
  "created_at": "2025-01-23T01:14:37Z",
  "updated_at": "2025-01-23T01:14:37Z"
}

Overview

Agents

Calls

Executions

Batches

Inbound

Phone Numbers

Knowledgebases

Dispositions

Providers

Sub-Accounts

Voice

User

SIP Trunks (BYOT)

Violations

Legacy APIs

Create a new Sub-Account API

Concurrency

Authorizations

Body

Response

​Concurrency

Authorizations

Body

Response

Concurrency