Trovacast

Platform

Subaccounts

Create projects under your organization — each with its own keys, wallet and data — fund them from your balance, suspend them and read their usage, without ever reading their data.

A subaccount is a project your organization creates under itself — a store, a brand, a region. It is a separate organization with its own keys, wallet, members, contacts, messages, calls and audit trail. Your organization (the parent) creates it, funds it, suspends it, mints its keys and reads its usage; it never reads its data. One level only, up to 100. A key with subaccounts:read reads them; subaccounts:write (live keys only) changes them. Administrators do the same in the console under Settings → Subaccounts.

Create one

A store run by the same business
curl -X POST 'https://api.trovacast.com/v1/subaccounts' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Mumbai store",
  "ownerEmail": "owner@acme.example",
  "business": "same",
  "calling": true,
  "messaging": true
}'
201 (json)
{
  "object": "subaccount",
  "id": "4b7e9c1d-2a3f-4e5d-8c6b-7a8f9e0d1c2b",
  "name": "Mumbai store",
  "status": "active",
  "suspendedBy": null,
  "suspendedAt": null,
  "business": "same",
  "verification": {
    "required": true,
    "verified": true,
    "inherited": true
  },
  "entitlements": {
    "calling": true,
    "messaging": true
  },
  "plan": {
    "id": "0f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f",
    "name": "Growth"
  },
  "balance": {
    "amountMinor": 0,
    "currency": "INR"
  },
  "usage": {
    "since": "2026-11-06T10:00:00.000Z",
    "calls": 0,
    "minutes": 0,
    "callChargesMinor": 0,
    "messages": 0,
    "messageChargesMinor": 0
  },
  "createdAt": "2026-11-06T10:00:00.000Z",
  "invitation": {
    "delivered": true,
    "expiresAt": "2026-11-09T10:00:00.000Z"
  }
}
  • ownerEmail becomes the subaccount’s first administrator and is invited by email — the invitation is never returned. It may be your own address.
  • business is your attestation, kept on the audit log. same: the same legal business as you — the subaccount shares your business verification, approved and revoked with yours. separate: another business — it verifies on its own (its test key can use /v1/verifications) before its live keys and live traffic work.
  • calling and messaging default to yours and can never be more than yours.
  • Refused while your own verification is not approved (VERIFICATION_REQUIRED), when your organization is itself a subaccount (SUBACCOUNT_NESTING_NOT_ALLOWED), when a partner or an integration manages it (SUBACCOUNTS_NOT_AVAILABLE), and past the cap — 10 by default, or your organization's own after a platform review (SUBACCOUNT_LIMIT_REACHED).

Fund it

A subaccount has its own wallet, starting at zero, and is billed on your plan’s rate card with no monthly fee, included minutes or trial credit of its own — your subscription pays the plan. Move credit from your balance to it, or its unspent credit back to you (direction: "to_parent"). Both wallets move in one transaction, the paying one never below zero (SUBACCOUNT_INSUFFICIENT_BALANCE), and your statements show it as transfer_out / transfer_in. Send an Idempotency-Key: a retry answers the first transfer.

Move ₹500 to the store
curl -X POST 'https://api.trovacast.com/v1/subaccounts/4b7e9c1d-2a3f-4e5d-8c6b-7a8f9e0d1c2b/transfers' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "amountMinor": 50000,
  "direction": "to_subaccount"
}'
201 (json)
{
  "object": "subaccount_transfer",
  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "subaccountId": "4b7e9c1d-2a3f-4e5d-8c6b-7a8f9e0d1c2b",
  "direction": "to_subaccount",
  "amountMinor": 50000,
  "currency": "INR",
  "parentBalanceMinor": 290100,
  "subaccountBalanceMinor": 50000,
  "createdAt": "2026-11-06T10:05:00.000Z"
}

Usage

Charged calls and billed minutes, charged messages by channel (SMS segments as units) and the balance, over from (inclusive) to to (exclusive) — by default its current billing period so far, at most 92 days. Counts and money only: never a contact, number, message or call.

This period’s usage
curl 'https://api.trovacast.com/v1/subaccounts/4b7e9c1d-2a3f-4e5d-8c6b-7a8f9e0d1c2b/usage' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 (json)
{
  "object": "subaccount_usage",
  "subaccountId": "4b7e9c1d-2a3f-4e5d-8c6b-7a8f9e0d1c2b",
  "from": "2026-11-06T10:00:00.000Z",
  "to": "2026-11-20T08:00:00.000Z",
  "currency": "INR",
  "calls": {
    "count": 42,
    "minutes": 117,
    "amountMinor": 17550
  },
  "messages": {
    "count": 310,
    "amountMinor": 6200,
    "byChannel": [
      {
        "channel": "sms",
        "messages": 310,
        "units": 310,
        "amountMinor": 6200
      }
    ]
  },
  "amountMinor": 23750,
  "balance": {
    "amountMinor": 26250,
    "currency": "INR"
  }
}

Keys and suspension

  • POST /v1/subaccounts/{subaccountId}/api-keys mints a key for the subaccount — mode: "test" by default; a live key waits for its business verification (LIVE_KEYS_REQUIRE_VERIFICATION). The secret is in that response only. The key is the subaccount’s: it acts only there, and its own administrators see and can revoke it. DELETE …/api-keys/{keyId} revokes any of its keys.
  • PATCH /v1/subaccounts/{subaccountId} with status: "suspended" (and a reason) stops its keys and sign-ins at once; status: "active" lifts your suspension — one the platform placed is 409 ORGANIZATION_SUSPENDED_BY_PLATFORM. name renames it. If your own organization is suspended, its active subaccounts are suspended with it (suspendedBy: "with_parent") and come back when it does; one you had suspended on its own stays suspended. A change of your plan moves your subaccounts to it too.
Mint a test key for the store
curl -X POST 'https://api.trovacast.com/v1/subaccounts/4b7e9c1d-2a3f-4e5d-8c6b-7a8f9e0d1c2b/api-keys' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Store backend",
  "scopes": [
    "contacts:read",
    "messages:write"
  ],
  "mode": "test"
}'

Isolation

A subaccount is a different organization. Its key gets 404 on your contacts, messages and calls and on its siblings’; your key gets 404 on its data. The explicit way in is a key you mint there: it acts as the subaccount, and every mint is audited in the subaccount’s own trail, listed on its Developers page and revocable by its administrators. Every subaccountId is looked up among your subaccounts, so another organization’s is the same 404 as one that does not exist. A person you name as its owner reads its data through their own seat in it, like any member.

Errors

CodeStatusMeaning and what to do
SUBACCOUNTS_NOT_AVAILABLE409Your organization is managed by a partner or was provisioned by an integration, so its projects are created by whoever manages it, not as subaccounts.What to do: Do not retry: ask the partner or integration that manages your organization to create the project.
SUBACCOUNT_INSUFFICIENT_BALANCE409The wallet paying for a subaccount transfer holds less than the amount (availableMinor says what it holds). Nothing moved.What to do: Transfer at most availableMinor, or top up the paying wallet first and retry.
SUBACCOUNT_LIMIT_REACHED409Your organization already has the most subaccounts it may hold (limit: 10 by default, or your organization's own cap the platform set; closed ones count). See Subaccounts.What to do: Reuse one of your existing subaccounts (GET /v1/subaccounts); closing one does not free a place. Need more? Ask us to review your organization's cap.
SUBACCOUNT_NESTING_NOT_ALLOWED409Your organization is itself a subaccount, and subaccounts go one level deep.What to do: Create the subaccount from the parent organization instead (POST /v1/subaccounts with one of the parent's keys).
VERIFICATION_INHERITED_FROM_PARENT409This subaccount is the same business as its parent, so its business verification is the parent's — approved and revoked with it. It does not fill in or submit its own.What to do: Do not retry: complete the parent organization's verification instead, and read this one's state with GET /v1/verifications.