---
title: "Prepare a single-use sign-up link for a person (no account or trial is created)"
method: POST
path: "/api/agents/handoff"
---

# Prepare a single-use sign-up link for a person (no account or trial is created)

`POST /api/agents/handoff`

## Request

- Base URL: `https://smartwebchat.eu`
- URL: `https://smartwebchat.eu/api/agents/handoff`
- Auth: none required

Returns handoff_url and expires_in_seconds. The link carries language, industry and recommended plan into registration and onboarding and works once. The account and the trial are created only when the person signs up. Rate limited to 20 requests per hour per IP, REST and MCP together. Disabled by default: 503 with error handoff_disabled; /agents/start shows the current status.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `locale` string: Language of the sign-up page, for example 'en'. Unsupported languages fall back to 'de'.
  - `industry_key` 'anwaelte' | 'apotheken' | 'arztpraxen' | 'fahrschulen' | 'friseure' | 'handwerker' | 'heilmittelpraxen' | 'hotels' | 'immobilien' | 'kfz-werkstaetten' | 'kosmetikstudios' | 'pflegedienste' | 'pflegeheime' | 'physiotherapie' | 'restaurants' | 'sanitaetshaeuser' | 'steuerberater' | 'tieraerzte' | 'versicherungsmakler' | 'zahnaerzte': Industry of the business, one of `how_to_test.agent_demo_contract.industries` in /agents/start.
  - `recommended_plan` 'business' | 'agency' | 'white_label': Plan you recommend: business, agency, white_label. Only plans with a trial preselect the trial type; the person can change it.
  - `demo_session_id` string: Optional demo session id from the scanner demo; its context is restored after sign-up.

## Response `200`

Replay of the same request (Idempotency-Replayed: true).

## Other responses

- `201`: handoff_url, expires_in_seconds, single_use.
- `400`: invalid_json, invalid_input or invalid_idempotency_key.
- `409`: handoff_no_longer_valid: send a new Idempotency-Key.
- `413`: payload_too_large.
- `422`: idempotency_key_reused.
- `429`: rate_limited — Retry-After: 3600
- `503`: handoff_disabled or unavailable.

---

[API](https://skmtc.dev/smartwebchat/apis/smartwebchat-api.md) · [All operations](https://skmtc.dev/smartwebchat/apis/smartwebchat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smartwebchat/apis/smartwebchat-api/revisions/1b052502dacb?raw)