Skip to main content

​
New subaccount wizard: step-by-step

The dashboard ships a guided flow at Settings → Subaccounts → New subaccount (/settings/subaccounts/new) that provisions a child organization step by step instead of in one API call. Reach for it when a human approves each stage — brand assets, a custom domain, funding — before the subaccount goes live. Automation that onboards customers from your own portal should use the one-call POST /api/v1/subaccounts/provision instead. The walkthrough below names the exact API call each step issues, so you can trace every screen to its endpoint. Every call runs under a parent-org session with the owner or admin role; the initial credit transfer is owner-only.
The wizard persists your in-progress draft in the browser, so closing the tab or coming back tomorrow resumes where you left off. A saved API key is shown once in memory and never written to the draft.

​
Step 1 — Basics

Creates the subaccount and decides its tenant-level limits. Continuing issues:
On success the API returns 201 with the new subaccount id, tenant_id, slug, and a one-time api_key. Save the key when it is shown — it cannot be retrieved later, only rotated. pending_setup: true leaves the subaccount in pending status so an abandoned setup never leaves a billing-active tenant behind; the final step flips it to active. The create is idempotent: the wizard sends a stable Idempotency-Key per registration, so a retry after a lost response replays the first attempt instead of colliding on the slug with a 409.

​
Step 2 — Brand

Decides how the subaccount’s dashboard looks to its users.
  • Inherit branding from parent (default) — the child renders with your logo, colours, and dashboard name. Nothing else to fill in.
  • Custom branding — turn inheritance off and supply a dashboard name, a logo, a favicon, and at least one brand colour (primary or accent). Logo and favicon accept PNG, JPEG, WebP, or GIF up to 2 MB.
Continuing issues PUT /api/v1/subaccounts/{id}/branding — either { "inherit_from_parent": true } or the override fields (dashboard_name, logo_url, favicon_url, primary_color, accent_color).

​
Step 3 — Domain (optional)

Serves the subaccount’s dashboard from its own hostname with an automatically provisioned SSL certificate. Skippable — you can add a domain later from the subaccount’s detail page.
  1. At your DNS provider, add a CNAME record for the hostname pointing at the target the step displays.
  2. Enter the hostname and click Register — issues POST /api/v1/subaccounts/{id}/domains.
  3. Click Verify — issues POST /api/v1/subaccounts/{id}/domains/{domainId}/verify. The status chip moves through pending → verifying (CNAME matched, certificate provisioning) → active. A background verifier also flips the status without another click once DNS propagates.
Verification failures surface a plain-language error — a CNAME pointing at the wrong target or a DNS lookup failure — rather than the raw provider string.

​
Step 4 — Connections (optional)

Per-channel decision: whether your subaccounts send on the platform’s shared connection or on a connection you bring (your own SIP trunk, SMPP account, email domain, WhatsApp Business account, and so on). The toggle is per channel and applies to every subaccount — there is no per-subaccount override. Skippable; subaccounts run on the platform default until you set a BYO connection. The full model, provider types, and billing shape are in Per-channel connection mode.

​
Step 5 — Credits

Sets the subaccount’s pricing and optionally funds it. Continuing issues PUT /api/v1/subaccounts/{id}/pricing with reseller_margin_pct and monthly_spend_cap_cents, then — if a non-zero transfer was entered and you are an owner — POST /api/v1/subaccounts/{id}/transfer-credits. The step shows your current parent balance and blocks a transfer that would exceed it. Pricing saves even when the transfer is skipped, so an admin can finish the wizard and have an owner fund the subaccount later.

​
Step 6 — Review & launch

Read-back of everything the flow captured: name and slug, seat and rate limits, branding mode, registered domain and its verification status, margin, spend cap, and the initial transfer. Launch subaccount issues POST /api/v1/subaccounts/{id}/finalize, flipping the subaccount from pending to active. The endpoint is idempotent — a retried launch after a network blip returns success and changes nothing — and lands you on the new subaccount’s detail page.

​
Degraded-failure paths

  • A failed step keeps its state. The step surfaces an inline error and stays put; nothing submitted earlier is lost, and the draft persists in the browser.
  • Create times out or drops mid-flight. Provisioning builds the child’s tenant synchronously and can take most of a minute. Retrying continues with the same idempotency key, so you converge on the first attempt’s 201 — you never create a duplicate or fight a 409 slug loop.
  • Insufficient balance on the transfer. The step reports that the parent wallet cannot cover the amount. Pricing was already saved; lower the amount or fund the parent and retry.
  • Owner-only transfer as an admin. The transfer input is hidden for non-owners; if it still fires, the step explains that only owners can move credits and that pricing is already saved — an owner can fund the subaccount later from its billing page.
  • Domain verification fails. The status chip shows failed with a plain-language reason. Fix the CNAME, click Verify again, or skip the step and add the domain later.
  • Resuming a deleted registration. If the pending subaccount your draft points at was deleted from the subaccounts list, the wizard detects the dead pointer on load, discards the stale draft, and starts you on a clean step 1.
  • Starting over. “Start a new registration” asks for confirmation, deletes the pending subaccount created at step 1 if one exists, and resets to a blank step 1 — so no half-configured pending row is orphaned.
  • Pending forever. A subaccount abandoned in pending shows in your list but cannot serve traffic. Finalize it (idempotent, safe to retry) or delete it — see White-label subaccounts.

​
Verify the result

  • Dashboard — the subaccount appears under Settings → Subaccounts with status active and its domain verification state.
  • API — GET /api/v1/subaccounts/{id} returns the subaccount with its limits and pricing; GET /api/v1/subaccounts lists it among your children.
  • Audit log — the parent’s Settings → Audit log records the create and the finalize, so you can confirm who launched the subaccount and when.

​
See also