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

# Assign a phone number to an agent

> MCP reference for assign_phone_number_to_agent.

Tool: `assign_phone_number_to_agent`. Requires **Admin or Owner** in the applicable workspace and a connected [OAuth session](https://docs.agents.labs.bandwidth.com/mcp/authentication.md).

Changes inbound routing and may contact the phone provider. Use IDs from `list_phone_numbers` and `list_agents`. For replacement, obtain user authorization, set `confirm_reassignment: true`, and supply the current `inbound_workflow_id` as `expected_inbound_workflow_id`. A stale or unconfirmed replacement fails without saving.

`saved: true` means the assignment was saved. Inspect `provider_sync` and warnings separately: a provider failure can leave the assignment saved, and successful sync may still need manual provider routing. Repeating the same assignment retries sync. This does not buy/activate numbers, publish agents, place calls, or verify a live call.

## Arguments

| Name | Type | Required | Defaults and limits |
| - | - | - | - |
| `confirm_reassignment` | boolean | No | Default: `false` |
| `expected_inbound_workflow_id` | integer or null | No | Default: `null` |
| `phone_number_id` | integer | Yes | exclusiveMinimum: `0` |
| `workflow_id` | integer | Yes | exclusiveMinimum: `0` |

## Example arguments

Replace sample resource IDs with IDs returned in your selected workspace.

```json theme={null}
{
  "phone_number_id": 7,
  "workflow_id": 42
}
```

## Result and errors

The schema below describes MCP `structuredContent`, including the `result` wrapper where present. Your client may also display a text representation. Read success flags and structured errors before continuing; transport success alone does not prove the operation succeeded. Authentication, missing membership, and insufficient role can fail before a tool result is produced. See [troubleshooting](https://docs.agents.labs.bandwidth.com/mcp/troubleshooting.md).

**Effect:** Changes state. **Retry:** Declared idempotent. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.

> [accordion] Input schema
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "confirm_reassignment": {
>       "default": false,
>       "type": "boolean"
>     },
>     "expected_inbound_workflow_id": {
>       "anyOf": [
>         {
>           "exclusiveMinimum": 0,
>           "type": "integer"
>         },
>         {
>           "type": "null"
>         }
>       ],
>       "default": null
>     },
>     "phone_number_id": {
>       "exclusiveMinimum": 0,
>       "type": "integer"
>     },
>     "workflow_id": {
>       "exclusiveMinimum": 0,
>       "type": "integer"
>     }
>   },
>   "required": [
>     "phone_number_id",
>     "workflow_id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] Result schema
>
> ```json theme={null}
> {
>   "properties": {
>     "organization_id": {
>       "type": "integer"
>     },
>     "phone_number": {
>       "properties": {
>         "address": {
>           "type": "string"
>         },
>         "address_normalized": {
>           "type": "string"
>         },
>         "address_type": {
>           "type": "string"
>         },
>         "country_code": {
>           "anyOf": [
>             {
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "id": {
>           "type": "integer"
>         },
>         "inbound_workflow_id": {
>           "anyOf": [
>             {
>               "type": "integer"
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "inbound_workflow_name": {
>           "anyOf": [
>             {
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "inbound_workflow_status": {
>           "anyOf": [
>             {
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "is_active": {
>           "type": "boolean"
>         },
>         "is_default_caller_id": {
>           "type": "boolean"
>         },
>         "label": {
>           "anyOf": [
>             {
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "provider": {
>           "type": "string"
>         },
>         "telephony_configuration_id": {
>           "type": "integer"
>         },
>         "telephony_configuration_name": {
>           "type": "string"
>         }
>       },
>       "required": [
>         "id",
>         "telephony_configuration_id",
>         "telephony_configuration_name",
>         "provider",
>         "address",
>         "address_normalized",
>         "address_type",
>         "country_code",
>         "label",
>         "is_active",
>         "is_default_caller_id",
>         "inbound_workflow_id",
>         "inbound_workflow_name",
>         "inbound_workflow_status"
>       ],
>       "type": "object"
>     },
>     "provider_sync": {
>       "properties": {
>         "message": {
>           "anyOf": [
>             {
>               "type": "string"
>             },
>             {
>               "type": "null"
>             }
>           ],
>           "default": null
>         },
>         "ok": {
>           "type": "boolean"
>         }
>       },
>       "required": [
>         "ok"
>       ],
>       "type": "object"
>     },
>     "saved": {
>       "const": true,
>       "default": true,
>       "type": "boolean"
>     },
>     "warnings": {
>       "items": {
>         "type": "string"
>       },
>       "type": "array"
>     }
>   },
>   "required": [
>     "organization_id",
>     "phone_number",
>     "provider_sync",
>     "warnings"
>   ],
>   "type": "object"
> }
> ```


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