---
title: "Onboarding"
description: "Read and manage your organization's onboarding checklist state."
---

Each organization carries a server-side onboarding checklist (the
"getting started" coach in the dashboard). Steps complete
**automatically** as the org performs the underlying action — creating
and talking to an agent, adding billing, getting a phone number, and
taking a first call. The API exposes the state read-only, plus
dismiss/undismiss controls and one explicit skip.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/onboarding` | Current onboarding state |
| `POST` | `/v1/onboarding/dismiss` | Hide the checklist |
| `POST` | `/v1/onboarding/undismiss` | Show it again |
| `POST` | `/v1/onboarding/agent-talk/skip` | Complete the agent step without the mic test |

## Onboarding object

All four endpoints return the same object (the POSTs return the
updated state):

```json
{
  "steps": {
    "agent":   { "completed": true,  "completed_at": "2026-04-20T18:24:10.113Z" },
    "billing": { "completed": true,  "completed_at": "2026-04-20T18:30:02.551Z" },
    "phone":   { "completed": false, "completed_at": null },
    "call":    { "completed": false, "completed_at": null }
  },
  "all_complete": false,
  "dismissed": false,
  "dismissed_at": null
}
```

| Step | Completes when… |
|------|-----------------|
| `agent` | The org has an agent **and** someone talked to it via a mic session (or the talk step was explicitly [skipped](#skip-the-agent-talk-step)) |
| `billing` | A payment method is saved or a top-up succeeds |
| `phone` | The org gets its first phone number |
| `call` | The org's first real call completes |

`dismissed` hides the checklist in the dashboard without changing step
state; `undismiss` re-shows it. Steps never un-complete.

### Skip the agent-talk step

`POST /v1/onboarding/agent-talk/skip` marks the `agent` step complete
even though no mic call happened — used when the builder tour's
optional "Talk to your agent" step is skipped. The org must actually
have an agent for the step to complete.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/onboarding \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Step 1: create an agent.
  </Card>
  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Step 2: add funds.
  </Card>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Step 3: get a number.
  </Card>
  <Card title="Mic Sessions" icon="microphone" href="/api-reference/mic-sessions">
    Talk to your agent from the browser.
  </Card>
</CardGroup>