> ## 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.

# Approve Agent Onboarding

> Claim a device-authorization code after the owner signs up in the browser. Called by the Bland dashboard, not by the bot.

### Overview

This endpoint is called from the browser by the dashboard during the [agent onboarding](https://docs.bland.ai/platform/connect-your-agent.md) flow, after the owner signs up (or logs in) and either starts the [Agent Phone Plan](https://docs.bland.ai/platform/agent-phone-plan.md) or chooses to connect the bot on the org's free credits. It isn't called directly by the bot, the bot only ever sees its effect through `/v1/agent/onboarding/poll`.

> [!NOTE]
>
> Requires an authenticated dashboard session for an org (not a personal account, and not an API key). The response never includes the `api_key`, only the bot's later `poll` call receives it.

### Body Parameters

**user\_code** `string` *required*

The short code shown to the owner by `/v1/agent/onboarding/start`.

**skip\_plan** `boolean`

Pass `true` to connect the bot without an Agent Phone Plan, on the org's free credits. Strictly a boolean; `"true"` as a string is rejected. Without it, an org that has no active plan gets `402 PLAN_REQUIRED`. An org that already has an active plan ignores `skip_plan` entirely: the plan payload is returned as usual, including the `PLAN_NUMBER_PENDING` wait while its number is provisioned.

### Response

**data** `object`

Confirmation that the code was claimed for this org.

**data.status** `string`

`approved`.

**data.org\_id** `string`

The org the code was claimed for.

**data.phone\_number** `string | null`

The number provisioned for this org's Agent Phone Plan, or `null` when the code was approved with `skip_plan: true` and the org has no plan.

**data.client\_name** `string`

The `client_name` the bot passed to `/start`, if any.

**data.key\_prefix** `string`

The first 14 characters of the API key that will be issued to the bot, the same handle Settings > API Keys shows. Display only, never the key itself.

**errors** `null | array`

`null` on success.

```json Response theme={null}
{
  "data": {
    "status": "approved",
    "org_id": "...",
    "phone_number": "+15551234567",
    "client_name": "my-bot",
    "key_prefix": "org_3f9a1c7e2b"
  },
  "errors": null
}
```

```json Response with skip_plan theme={null}
{
  "data": {
    "status": "approved",
    "org_id": "...",
    "phone_number": null,
    "client_name": "my-bot",
    "key_prefix": "org_3f9a1c7e2b"
  },
  "errors": null
}
```

```json Invalid code (400) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "INVALID_USER_CODE",
      "message": "Enter the code your agent gave you."
    }
  ]
}
```

```json Plan required (402) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "PLAN_REQUIRED",
      "message": "Start the Agent Phone Plan to connect your agent."
    }
  ]
}
```

```json Number pending (409) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "PLAN_NUMBER_PENDING",
      "message": "Your number is still being set up. Try again in a moment."
    }
  ]
}
```

```json Code not found (404) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CODE_NOT_FOUND",
      "message": "That code is not valid. Ask your agent for a new one."
    }
  ]
}
```

```json Code already used (409) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CODE_ALREADY_USED",
      "message": "That code has already been used. Ask your agent for a new one."
    }
  ]
}
```

```json Org context required (403) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "ORG_CONTEXT_REQUIRED",
      "message": "Switch to an organization to connect an agent."
    }
  ]
}
```

```json Invalid origin (403) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "INVALID_ORIGIN",
      "message": "Approve this code from the Bland dashboard. This request did not come from it."
    }
  ]
}
```

```json Too many requests (429) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many attempts. Wait a few minutes and try again."
    }
  ]
}
```

***

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.