---
title: "Begin an agent-driven signup: submit an email, and Bubbles emails a verification code. The response is identical whether or not an account already exists (it never reveals whether the email is registered before the code is verified — the unified flow logs in existing users and signs up new ones). Returns a signup_session to pass to the next steps and relay_to_user text to show the user. Call again to resend. A malformed/disallowed/temporary email is rejected with 400 invalid_request. Per-IP throttled."
method: POST
path: "/v1/signup/start"
---

# Begin an agent-driven signup: submit an email, and Bubbles emails a verification code. The response is identical whether or not an account already exists (it never reveals whether the email is registered before the code is verified — the unified flow logs in existing users and signs up new ones). Returns a signup_session to pass to the next steps and relay_to_user text to show the user. Call again to resend. A malformed/disallowed/temporary email is rejected with 400 invalid_request. Per-IP throttled.

`POST /v1/signup/start`

## Request

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

## Request body

- SignupStartRequest: POST /v1/signup/start request body.
  - `email` string, required: The work email to sign up / send the verification code to.

## Response `200`

Success.

- SignupStartResponse: POST /v1/signup/start response — a verification code was emailed. The response is identical whether or not an account already exists (it never reveals whether the email is registered before the code is verified).
  - `next_step` 'verify', required: The next call to make.
  - `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 to pass to the next 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)