Reallocate Credit Balances

PATCH

workspace

sub

credit-balances

Reallocate Credit Balances

curl --request PATCH \
  --url https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "allocations": {
    "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": 5000,
    "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": 3000
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances"

payload = { "allocations": {
        "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": 5000,
        "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": 3000
    } }
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    allocations: {
      'b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30': 5000,
      'd21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88': 3000
    }
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances', 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://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'allocations' => [
        'b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30' => 5000,
        'd21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88' => 3000
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$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://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances"

	payload := strings.NewReader("{\n  \"allocations\": {\n    \"b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30\": 5000,\n    \"d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88\": 3000\n  }\n}")

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

	req.Header.Add("X-API-KEY", "<x-api-key>")
	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.patch("https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"allocations\": {\n    \"b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30\": 5000,\n    \"d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88\": 3000\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances")

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

request = Net::HTTP::Patch.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"allocations\": {\n    \"b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30\": 5000,\n    \"d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88\": 3000\n  }\n}"

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

{
  "parent_workspace_id": "2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11",
  "parent_available_balance": "12000.00",
  "allocations": {
    "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": "5000.00",
    "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": "3000.00"
  },
  "primary": {
    "id": "2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11",
    "name": "Acme Collections HQ"
  }
}

{
  "detail": "These allocations need 9000.00 from the primary's pot, which only holds 4000.00. Lower the allocations or add balance to the primary workspace first."
}

{
  "error": {
    "code": "401 Unauthorized",
    "message": "Invalid credentials"
  }
}

{
  "detail": "Sub-workspaces are not enabled for this workspace."
}

{
  "detail": "Workspace is not a sub-workspace family parent."
}

{
  "error": {
    "code": "500 Internal Server Error",
    "message": "An unexpected error occurred on the server."
  }
}

Set every sub-workspace’s wallet to an absolute balance. The net difference moves from or to the primary’s unallocated pot. Prepaid families in individual billing mode only.

When to use

Distributing a top-up made on the primary across clients or teams.
Pulling unused balance back from one sub-workspace to fund another.

Request parameters

Parameter	Type	Required	Description
`allocations`	object	Yes	Map of `sub_workspace_id` to its new absolute balance, not a delta. Must include every active sub-workspace exactly once. Values are `0` or more, two decimals.

Rules

The net amount moving out of the primary’s pot cannot exceed what the pot holds. Top up on the primary first, then allocate.
A sub-workspace with a 0 balance cannot place calls; sub-workspaces have no overdraft.
Every move is recorded in the workspace ledgers as a transfer, never as a charge.

Integration notes

Authenticate with the primary workspace’s API key.
Read the current wallets and family.available_pot from Get Sub-workspaces first, then send the full map.
Amounts in the response are decimal strings ("5000.00"), unlike the read endpoints.

In a common-billing family the wallet is shared on the primary and sub-workspaces hold nothing. This endpoint returns 400 This family uses a shared balance; per-sub wallets do not exist. Allocate concurrency instead.

Error responses

400: Balance allocation applies to prepaid families only.
400: This family uses a shared balance; per-sub wallets do not exist.
400: allocations name workspaces that are not active sub-workspaces of this family: [...]
400: allocations must cover every active sub-workspace; missing: [...]
400: These allocations need 9000.00 from the primary's pot, which only holds 4000.00. Lower the allocations or add balance to the primary workspace first.
401: Invalid or missing API key.
403: Sub-workspaces are not enabled for this workspace.
404: Workspace is not a sub-workspace family parent. — the primary has no sub-workspaces yet.
422: Empty map, negative value, or a key that is not a UUID.

Example

curl --request PATCH "https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "allocations": {
      "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": 5000.00,
      "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": 3000.00
    }
  }'

Headers

X-API-KEY

string

required

(Required) The API key of the PRIMARY workspace. A sub-workspace's key is refused with 400.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

Body

application/json

allocations

object

required

(Required) sub_workspace_id -> the sub-workspace's NEW absolute balance (not a delta). Must include every active sub-workspace exactly once. Values >= 0, two decimals.

Show child attributes

Response

Successful Response: The applied balances. Amounts are decimal strings.

parent_workspace_id

string

Example:

"2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11"

parent_available_balance

string

The primary's unallocated pot after the move, as a decimal string.

Example:

"12000.00"

allocations

object

Show child attributes

Example:

{
  "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": "5000.00",
  "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": "3000.00"
}

primary

object

Show child attributes

Reallocate Credit Balances

curl --request PATCH \
  --url https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "allocations": {
    "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": 5000,
    "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": 3000
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances"

payload = { "allocations": {
        "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": 5000,
        "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": 3000
    } }
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    allocations: {
      'b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30': 5000,
      'd21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88': 3000
    }
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances', 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://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'allocations' => [
        'b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30' => 5000,
        'd21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88' => 3000
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$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://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances"

	payload := strings.NewReader("{\n  \"allocations\": {\n    \"b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30\": 5000,\n    \"d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88\": 3000\n  }\n}")

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

	req.Header.Add("X-API-KEY", "<x-api-key>")
	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.patch("https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"allocations\": {\n    \"b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30\": 5000,\n    \"d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88\": 3000\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/workspace/sub/credit-balances")

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

request = Net::HTTP::Patch.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"allocations\": {\n    \"b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30\": 5000,\n    \"d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88\": 3000\n  }\n}"

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

{
  "parent_workspace_id": "2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11",
  "parent_available_balance": "12000.00",
  "allocations": {
    "b7c1f0e2-4d3a-4a91-9f2e-8c1d5a6b7e30": "5000.00",
    "d21e8c55-9a0f-4c3b-86de-1f4b7a2c9e88": "3000.00"
  },
  "primary": {
    "id": "2f9a1c44-7e88-4bb1-9a01-5d3c2e7f6a11",
    "name": "Acme Collections HQ"
  }
}

{
  "detail": "These allocations need 9000.00 from the primary's pot, which only holds 4000.00. Lower the allocations or add balance to the primary workspace first."
}

{
  "error": {
    "code": "401 Unauthorized",
    "message": "Invalid credentials"
  }
}

{
  "detail": "Sub-workspaces are not enabled for this workspace."
}

{
  "detail": "Workspace is not a sub-workspace family parent."
}

{
  "error": {
    "code": "500 Internal Server Error",
    "message": "An unexpected error occurred on the server."
  }
}

Get Started

API Reference

Webhooks Setup

Telephony Integration

MCP Server

External Integrations

Privacy and Compliance

Reallocate Credit Balances

When to use

Request parameters

Rules

Integration notes

Error responses

Example

Headers

Body

Response

​When to use

​Request parameters

​Rules

​Integration notes

​Error responses

​Example

Headers

Body

Response

When to use

Request parameters

Rules

Integration notes

Error responses

Example