> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Agent Account Setup

> Start new-customer setup without an API key, then verify ownership in Trackly.

Starts setup for a new business account using a business name and email. **No API key is required.** This call creates a setup request, not an account, sending number, or credential.

Open the returned `verification_url`. The human creates the matching new account, verifies the same email, signs in as its direct owner, completes any required two-step verification, and explicitly connects the account. Existing accounts cannot be reparented through this flow.

The new account remains on the free plan with its own billing responsibility. Setup does not make Trackly pay for its messages or bypass normal billing, sender, or compliance requirements.

## Body Parameters

<ParamField body="name" type="string" required>
  Exact business name to use when creating the new account, at most 255 characters.
</ParamField>

<ParamField body="email" type="string" required>
  Email the owner will verify during signup, at most 255 characters. Leading/trailing spaces are removed and the address is normalized to lowercase.
</ParamField>

Only `name` and `email` are accepted. Do not provide passwords, verification codes, provider credentials, or API keys.

## Response Fields

<ResponseField name="onboarding" type="object">Setup state with `id`, `status`, `name`, `expires_at`, nullable `account_id`, and `next_step`.</ResponseField>
<ResponseField name="verification_url" type="string">Trackly setup page. Its URL fragment carries a limited status capability; the page removes the fragment and uses a no-referrer policy.</ResponseField>
<ResponseField name="poll_token" type="string">Status-only token for [Get Setup Status](/api-reference/v2/agent-onboarding/get). It is not an API key, login, email proof, or permission to send.</ResponseField>

A new request has `status: pending`, `account_id: null`, and `next_step: complete_signup`. It expires after one hour and is retained for at most one day. Responses use `Cache-Control: no-store`.

Creation is limited to 3 requests per normalized email per hour and 1,000 per IP/global hourly bucket. Requests return unavailable when safe setup admission or the configured Trackly parent is unavailable.

## Complete setup safely

After completion, open **Settings → API Keys** and create a sandbox key with **Require send approval** enabled. Set an appropriate daily cap and allowed sending lists, then copy the key directly into the MCP client's private connection settings. Never paste the API key into chat, a prompt, or a shared document. Polling never returns or installs it.

Before a first send, obtain an active owned sending list through supported [number provisioning or BYOC](/concepts/phone-numbers), complete applicable business/carrier requirements, and arrange [billing](/account/billing) and [recipient consent](/concepts/compliance). Enrollment supplies none of these automatically. Sandbox sends also require an eligible sending list and may call configured webhooks.

If signup outlasts the one-hour window, retain the original setup link and account. An eligible verified owner can renew that original request within its one-day retention window; see [setup recovery](/api-reference/v2/agent-onboarding/get). After retention ends, contact support instead of creating duplicate accounts.

## Errors

| HTTP | Code                         | Meaning                                                    |
| ---- | ---------------------------- | ---------------------------------------------------------- |
| 400  | `onboarding_invalid_request` | Missing/invalid name or email, or unsupported body fields. |
| 429  | `onboarding_rate_limited`    | Admission limit reached; obey `Retry-After`.               |
| 503  | `onboarding_unavailable`     | Setup cannot be safely started now.                        |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v2/agent-onboarding \
    -H "Content-Type: application/json" \
    -d '{"name":"Example Pizza","email":"owner@example.com"}'
  ```
</RequestExample>