Agent Onboarding API

The Agent Onboarding API lets AI agents sign up users, handle plan selection and payment, and receive an API token — all without the user opening a dashboard. This is designed for Claude Code, Cursor, and any agent that wants to onboard users programmatically.

Base URL: https://app.humblytics.com

---

Overview

The signup flow has two parts:

1. The agent calls /api/v1/auth/agent-initiate to create a session and get a unique verification URL.

2. The user opens that URL in their browser to verify identity and complete payment.

3. The agent polls until the session is complete, then receives an authToken for all subsequent API calls.

---

Step 1 · Initiate Signup

Create a signup session for a new user.

Request

curl -X POST https://app.humblytics.com/api/v1/auth/agent-initiate \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "name": "Jane Smith" }'

Parameters

Name	Type	Required	Description
email	string	Yes	User's email address
name	string	Yes	User's full name

Response (201)

{
  "token": "<session-token>",
  "verifyUrl": "https://app.humblytics.com/agent-verify?token=<session-token>",
  "expiresAt": 1234567890000
}

Error Responses

Status	Body	Meaning
409	{ "error": "user_exists" }	Email already has an account
400	{ "error": "invalid_email" }	Email format is invalid

The session expires in 10 minutes if the user doesn't open the verification link.

---

Step 2 · User Verification

Tell the user to open the verification URL in their browser. The page will:

1. Silently verify the user is human

2. Create their Humblytics account and set a browser session

3. Ask them to choose Business Monthly ($79/mo) or Business Annual ($65/mo, save $168/yr)

4. Redirect to Stripe to complete payment

5. Show a confirmation page

The agent should present the URL clearly and wait for the user to complete the browser flow before proceeding.

---

Step 3 · Poll for Completion

Poll every 3–5 seconds until status is "complete" or the session expires.

Request

curl https://app.humblytics.com/api/v1/auth/agent-signup-status?token=<session-token>

While waiting

{ "status": "pending" }

When complete

{
  "status": "complete",
  "authToken": "<jwt>"
}

Error Responses

Status	Meaning
404	Token not found
410	Session expired — ask the user to start over

The authToken is delivered once — the session is deleted after this response. Store the token immediately.

---

Step 4 · Use the Token

All subsequent API calls use the token as a Bearer header:

Authorization: Bearer <authToken>

This token works with all Humblytics API endpoints including the External Analytics API and Split Testing API.

---

Step 5 · Add a Website

With the token, the agent can immediately add a website to the account.

Request

curl -X POST https://app.humblytics.com/api/v1/add-custom-site \
  -H "Authorization: Bearer <authToken>" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com", "name": "My Site" }'

Response

{
  "propertyId": "<property-id>",
  "scriptId": "<script-id>"
}

Install the tracking script on the user's site:

<script async src="https://app.humblytics.com/hmbl.min.js?id=<script-id>"></script>

---

Step 6 · Stripe Payment Links (Fallback)

If the user skipped payment during signup, send them directly to Stripe:

Plan	URL
Monthly	https://buy.stripe.com/6oU9AS4TVdaQafZ9tS2Nq0k?prefilled_email=<email>
Annual	https://buy.stripe.com/8x2cN40DF4EkafZ49y2Nq0j?prefilled_email=<email>

---

Quick Reference

Step	Method	Endpoint
Initiate signup	POST	/api/v1/auth/agent-initiate
Poll for completion	GET	/api/v1/auth/agent-signup-status?token=<token>
Add a website	POST	/api/v1/add-custom-site
List websites	GET	/api/v1/property/all
Billing status	GET	/api/v1/billing/status

---

Agent Spec File

The full onboarding spec is available as a standalone markdown file that agents can load as context:

https://app.humblytics.com/agent.md

You can also open it directly in your editor:

• Cursor: Add to Cursor — opens Cursor and creates a rule from the spec

• Claude Code: Run curl -o HUMBLYTICS.md https://app.humblytics.com/agent.md then include in your CLAUDE.md

Add it to your CLAUDE.md, .cursorrules, or system prompt and your agent will know how to onboard users automatically.

---

Related

• External Analytics API — Query traffic, pages, clicks, forms, and funnels

• Split Testing API — Create and manage A/B tests programmatically