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

# create_onboarding_session

> Create a hosted onboarding session: Agentcard collects the user's details, verifies their email with an emailed code, takes consent, and hands you a finished c…

Connect to `https://mcp.agentcard.sh/mcp` with your **organization credential** (`client_id` + `client_secret`, or the org access token).

## What it does

Create a hosted onboarding session: Agentcard collects the user's details, verifies their email with an emailed code, takes consent, and hands you a finished cardholder — use it when you'd rather not collect names and birthdates in your own UI. Send the user to the returned url (expires in 60 minutes); we redirect them to your registered return\_url with ?session\_id= when done. Subscribe to the cardholder\_onboarding\_session.completed webhook or poll get\_onboarding\_session.

## Inputs

| Field | Type | Description |
| - | - | - |
| `return_url` *(required)* | string | Where we send the user afterward. Must match a URL registered with `agent-cards-admin orgs onboarding-return-urls`. |
| `email` | string | Prefill only — the flow verifies whatever address the user proves. |
| `external_user_id` | string | Your id for this user; echoed on reads and the completion webhook. |
| `cardholder_id` | string | An existing cardholder to claim instead of creating a new one. |
| `state` | string | Opaque string (max 512 chars) echoed on the final redirect. |

## Returns

| Field | Type | Description |
| - | - | - |
| `message` *(required)* | string | Human-readable next step. |
| `sessionId` | string | The session id (cos\_…). |
| `url` | string | Send the user here. Embeds a secret token — treat like a password-reset link. |
| `expiresAt` | string | ISO 8601 expiry (60 minutes). |

## Example call

```json theme={null}
{
  "tool": "create_onboarding_session",
  "arguments": {
    "return_url": "\u2026"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.