> ## 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](/platform/connect-your-agent) for the full flow.

<Note>
  Requests are rate-limited globally and per IP. A `429` includes a `Retry-After` header in seconds.
</Note>

### Body Parameters

<ParamField body="client_name" type="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 `._/-`.
</ParamField>

<ParamField body="prefill" type="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.
</ParamField>

<ParamField body="prefill.name" type="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.
</ParamField>

<ParamField body="prefill.first_name" type="string">
  First name, up to 128 characters.
</ParamField>

<ParamField body="prefill.last_name" type="string">
  Last name, up to 128 characters.
</ParamField>

<ParamField body="prefill.email" type="string">
  Email address, up to 128 characters. Dropped unless it has the shape `x@y.z`.
</ParamField>

<ParamField body="prefill.phone" type="string">
  Phone number, up to 128 characters, normalized to E.164 with US as the default region. Dropped when it can't be normalized.
</ParamField>

### Response

<ResponseField name="data" type="object">
  Device and user codes for the flow.
</ResponseField>

<ResponseField name="data.device_code" type="string">
  Opaque code your bot polls with at `/v1/agent/onboarding/poll`. Keep this private.
</ResponseField>

<ResponseField name="data.user_code" type="string">
  Short code to show the owner. They enter this at `verification_url` if it isn't already pre-filled.
</ResponseField>

<ResponseField name="data.verification_url" type="string">
  The page where the owner completes signup, without the code embedded.
</ResponseField>

<ResponseField name="data.verification_url_complete" type="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.
</ResponseField>

<ResponseField name="data.expires_in" type="number">
  Seconds until the codes expire (`900`, 15 minutes).
</ResponseField>

<ResponseField name="data.interval" type="number">
  Minimum seconds to wait between calls to `/poll`.
</ResponseField>

<ResponseField name="errors" type="null | array">
  `null` on success.
</ResponseField>

<ResponseExample>
  ```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."
      }
    ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)


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