curl -X POST https://api.tracklysms.com/api/v2/agent-onboarding \
-H "Content-Type: application/json" \
-d '{"name":"Example Pizza","email":"owner@example.com"}'
{
"onboarding": {},
"verification_url": "<string>",
"poll_token": "<string>"
}Agent Account Setup (v2)
Start Agent Account Setup
Start new-customer setup without an API key, then verify ownership in Trackly.
POST
/
v2
/
agent-onboarding
curl -X POST https://api.tracklysms.com/api/v2/agent-onboarding \
-H "Content-Type: application/json" \
-d '{"name":"Example Pizza","email":"owner@example.com"}'
{
"onboarding": {},
"verification_url": "<string>",
"poll_token": "<string>"
}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
Only
A new request has
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
string
required
Exact business name to use when creating the new account, at most 255 characters.
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.
name and email are accepted. Do not provide passwords, verification codes, provider credentials, or API keys.
Response Fields
object
Setup state with
id, status, name, expires_at, nullable account_id, and next_step.string
Trackly setup page. Its URL fragment carries a limited status capability; the page removes the fragment and uses a no-referrer policy.
string
Status-only token for Get Setup Status. It is not an API key, login, email proof, or permission to send.
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, complete applicable business/carrier requirements, and arrange billing and recipient consent. 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. 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
curl -X POST https://api.tracklysms.com/api/v2/agent-onboarding \
-H "Content-Type: application/json" \
-d '{"name":"Example Pizza","email":"owner@example.com"}'