> ## 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"
  }
}
```