---
title: "Join a listed existing workspace (action:\"join\", team_id) or create a new one (action:\"create\", workspace_name) — the same createTeamSnapshot / self-invite path the web flow uses. A team_id that is not joinable by the verified email domain is refused with 403 forbidden. On create, the response also carries the new workspace's free Pro-trial status with its benefits (pro_trial) and, when the verified email is a non-public company domain, a domain_join offer; the agent may then call action:\"enable_domain_join\" to let anyone with that verified email domain auto-join the workspace (only the user's own verified non-public company domain is ever accepted — never a public or consumer email domain). Returns the resulting team_id and advances to the calendar step."
method: POST
path: "/v1/signup/workspace"
---

# Join a listed existing workspace (action:"join", team_id) or create a new one (action:"create", workspace_name) — the same createTeamSnapshot / self-invite path the web flow uses. A team_id that is not joinable by the verified email domain is refused with 403 forbidden. On create, the response also carries the new workspace's free Pro-trial status with its benefits (pro_trial) and, when the verified email is a non-public company domain, a domain_join offer; the agent may then call action:"enable_domain_join" to let anyone with that verified email domain auto-join the workspace (only the user's own verified non-public company domain is ever accepted — never a public or consumer email domain). Returns the resulting team_id and advances to the calendar step.

`POST /v1/signup/workspace`

## Request

- Base URL: `https://api.usebubbles.com`
- URL: `https://api.usebubbles.com/v1/signup/workspace`
- Auth: none required

## Request body

- SignupWorkspaceRequest: POST /v1/signup/workspace request body — join a listed workspace, create a new one, or (after create, if the response offered it) enable domain-join.
  - `signup_session` string, required: A verified signup token.
  - `action` 'join' | 'create' | 'enable_domain_join', required: Join an existing workspace, create a new one, or (after creating, for a non-public verified domain the response offered) allow anyone with that verified email domain to auto-join.
  - `team_id` string: For action:"join" — a listed, domain-matched workspace id.
  - `workspace_name` string: For action:"create" — the new workspace name.

## Response `200`

Success.

- SignupWorkspaceResponse: POST /v1/signup/workspace response — workspace ready.
  - `next_step` 'calendar', required: The next call to make.
  - `team_id` string: The workspace the user joined or created.
  - `pro_trial` SignupProTrial: The new workspace's free Pro-trial status (present only when creating).
    - `active` boolean, required: Whether the new workspace is on a free Pro trial.
    - `plan` string, required: The workspace plan (e.g. "pro").
    - `benefits` string[], required: The Pro plan benefits to relay to the user.
  - `domain_join` SignupDomainJoin: Whether the user may open their new workspace to their verified email domain (present only when creating).
    - `available` boolean, required: True when the verified email domain is a non-public company domain that can be offered for auto-join.
    - `domain` string, required: The user's verified email domain.
  - `domain_join_enabled` boolean: True on an action:"enable_domain_join" response — the domain is now open for auto-join.
  - `domain` string: The domain opened for auto-join (enable_domain_join response).
  - `agent_context` string, required: Agent-facing guidance for this step: what happened, what to tell the user, and what to ask/call next.
  - `relay_to_user` string, required: Plain-language text for the agent to show the user.
  - `signup_session` string, required: Opaque token advanced to the calendar step.

## Other responses

- `400`: A query parameter or request body was malformed (invalid_request).
- `500`: An unexpected server error occurred (internal_error).

---

[API](https://skmtc.dev/usebubbles/apis/bubbles-public-api.md) - [All operations](https://skmtc.dev/usebubbles/apis/bubbles-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usebubbles/apis/bubbles-public-api/revisions/31570f5d4b05?raw)