Skip to main content
POST
Create Agency Workspace
Creates a workspace under your agency, optionally subscribes it to a plan, and returns a ready-to-use workspace API key for it — so an onboarding script never has to stop and mint a key or make a second billing call by hand.

Endpoint

  • Method: POST
  • Path: /api/agency/subaccounts
  • Auth: Authorization: Bearer tucoagency_xxxxxxxxxxxxx (agency key)

Body

Example request

Success response (200)

The last four fields appear only when you passed plan. Omit it and the response is exactly what it always was.
workspaceApiKey is shown once. Store it when you create the workspace — it cannot be retrieved later, only replaced from the workspace’s Integrations page.
It is a normal workspace key: it works on every documented endpoint for that workspace, and on no other workspace. It is not an agency key and cannot reach the agency endpoints. In the rare case key creation fails, the workspace is still created and workspaceApiKey is null — make one from the workspace’s Integrations page.

Subscribing in the same call

A plan is not optional in practice. plan is what grants a workspace its line limits, and an agency workspace with no plan is refused outright — a line transfer into one fails. So every onboarding script made the second call anyway. plan on create collapses the two.
There is no enterprise plan. email-only (Mini) exists but is retired and is rejected for new subscriptions. Workspaces already on it keep renewing.
It runs the same billing path as POST /api/agency/billing/subscribe, so the behaviour matches exactly:
  • Invoiced agency — the workspace gets the plan and no card is charged. billingMode: "invoice", and no Stripe subscription exists for it, which is what makes your client structurally unreachable by dunning and payment mail. Line caps do not apply either — see below.
  • Stripe agency — your saved card is charged off-session, as it would be on the standalone route. billingMode: "stripe".

An invalid plan is rejected before anything is created

400, and no workspace exists — the plan is validated before the workspace is created, so a typo cannot leave an orphan behind.

A billing failure does not lose the workspace

If the plan cannot be applied after the workspace exists — a declined card, Stripe unreachable — you still get 200, the workspace, and its key:
Failing the whole request would hide a workspace that already exists and get you a duplicate on retry. Check planError, then retry the billing step alone with POST /api/agency/billing/subscribe — do not create the workspace again.

If Tuco invoices your agency, lines are uncapped

Plan line limits exist to meter what a card gets charged for. When Tuco invoices your agency offline for the whole group, there is nothing for them to meter — they can only block a line you have already agreed to pay for. So for an invoiced agency, every client workspace can order any number of lines, whatever plan it carries. It applies to all three paths — ordering a line, creating one directly, and the capacity the dashboard reports, which returns unlimitedReason: "invoiced_agency".
This is a commercial arrangement, not a setting. Tuco switches it on per agency, the same switch that enables line-health webhooks. On Stripe billing, normal plan caps apply and extra lines are add-on purchases.
You still pass a plan: it is what sets the workspace’s message throughput and what marks it active. It just stops being a ceiling on lines.

What the new workspace starts as

  • Owned by your agency (isAgencyWorkspace: true) — it has no card of its own and bills through you.
  • subscriptionStatus: "active" when you passed a plan, "none" otherwise. Subscribe it before moving lines in; a transfer into an unsubscribed workspace is refused.
  • You and your agency co-admins are admins on it, so it appears in the workspace switcher immediately.
  • It has its own workspace API key, returned above.

Error responses