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

# Start Agent Onboarding

> Start the device-authorization flow a bot uses to get its own Bland API key, plus a phone number if its owner starts the Agent Phone Plan. No API key required.

### Overview

No authentication is required for this endpoint, it's how a bot gets an API key in the first place. See the [Agent onboarding API](https://docs.bland.ai/platform/connect-your-agent.md) for the full flow.

> [!NOTE]
>
> Requests are rate-limited globally and per IP. A `429` includes a `Retry-After` header in seconds.

### Body Parameters

**client\_name** `string`

A name for the bot starting the flow, shown to the owner during signup so they know what's asking. Max length `64`. Allowed characters: letters, numbers, spaces, and `._/-`.

**prefill** `object`

Values to pre-fill the owner's sign-up form. Pass what the bot already knows. Invalid values are dropped silently, never a `400`. Values that survive validation are appended to `verification_url_complete` as a URL fragment, form-encoded the way `URLSearchParams` does it (`@` becomes `%40`, `+` becomes `%2B`, a space becomes `+`). The fragment stays in the owner's browser; Bland never stores or logs pre-fill values.

**prefill.name** `string`

Full name, up to 128 characters. Split on its first space into first and last name when `first_name` and `last_name` are absent.

**prefill.first\_name** `string`

First name, up to 128 characters.

**prefill.last\_name** `string`

Last name, up to 128 characters.

**prefill.email** `string`

Email address, up to 128 characters. Dropped unless it has the shape `x@y.z`.

**prefill.phone** `string`

Phone number, up to 128 characters, normalized to E.164 with US as the default region. Dropped when it can't be normalized.

### Response

**data** `object`

Device and user codes for the flow.

**data.device\_code** `string`

Opaque code your bot polls with at `/v1/agent/onboarding/poll`. Keep this private.

**data.user\_code** `string`

Short code to show the owner. They enter this at `verification_url` if it isn't already pre-filled.

**data.verification\_url** `string`

The page where the owner completes signup, without the code embedded.

**data.verification\_url\_complete** `string`

The same page with `user_code` pre-filled. When `prefill` values survive validation, they are appended as a URL fragment, for example `...?code=BQPL-7VXR#first_name=Sam&last_name=Lee&email=sam%40example.com&phone=%2B14155550123`. Prefer this when you can show a clickable link.

**data.expires\_in** `number`

Seconds until the codes expire (`900`, 15 minutes).

**data.interval** `number`

Minimum seconds to wait between calls to `/poll`.

**errors** `null | array`

`null` on success.

```json Response theme={null}
{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}
```

```json Response with prefill theme={null}
{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR#first_name=Sam&last_name=Lee&email=sam%40example.com&phone=%2B14155550123",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}
```

```json Feature disabled (503) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "FEATURE_DISABLED",
      "message": "Agent onboarding is temporarily unavailable."
    }
  ]
}
```

```json Too many requests (429) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many requests. Try again later."
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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