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

# Attach Numbers to Agent

> Route inbound calls on your phone numbers to an agent.

### Overview

Points one or more of your phone numbers at the agent so inbound calls run it. Any existing pathway or persona assignment on those numbers is replaced. Calls answer with the agent's `production` version once one is promoted; until then they run the newest version saved on the dev timeline at the time of the attach, so re-attach after saving to refresh it. Enterprise plans can pass `environment: "staging"` so calls run the version pinned to staging instead. The agent must have at least one saved version. Use [Detach Numbers from Agent](/api-v2/post/agents-id-inbound-detach) to undo.

Requires an admin, owner, operator, or prompter role.

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="agent_id" type="string" required>
  The agent's unique identifier.
</ParamField>

### Body Parameters

<ParamField body="inbound_numbers" type="string[]" required>
  Phone numbers to attach, each exactly as it appears on your account (for example `+18005551234`). Must be a non-empty array of non-empty strings; surrounding whitespace is trimmed. Returns `400 INVALID_BODY` if the array is missing, empty, or contains a non-string. Returns `400 INVALID_INBOUND_NUMBERS` if any number is not on your account, in which case nothing is attached.
</ParamField>

<ParamField body="environment" type="string">
  Which environment calls to these numbers run: `production` or `staging`. When you omit it, a number already attached to this agent on staging stays on staging, and every other number answers on production. Pass `production` to move a staging number back. Any other value returns `400 INVALID_BODY`.

  `staging` is enterprise only and applies to calls. Texts to a staging number still run the production version. Every check below runs before anything is written:

  * `403 ENTERPRISE_REQUIRED` if your organization is not on an enterprise plan.
  * `409 STAGING_NUMBER_UNSUPPORTED` if your account or any of the numbers runs on dedicated infrastructure.
  * `409 AGENT_ENV_UNPINNED` if nothing is published to staging.
  * `409 AGENT_VARIABLE_UNRESOLVED` if a variable the staging version references has no staging value, or `409 AGENT_SNAPSHOT_INVALID` if the staging version can't run.
</ParamField>

### Response

<ResponseField name="data.agent_id" type="string">
  The agent ID from the request path.
</ResponseField>

<ResponseField name="data.persona_id" type="string">
  ID of the persona the attached numbers route through. Created on the agent's first attach and reused afterwards.
</ResponseField>

<ResponseField name="data.pathway_id" type="string">
  ID of the pathway compiled from the agent's version for this binding. Regenerated on every attach.
</ResponseField>

<ResponseField name="data.compiled_from_version" type="string">
  ID of the agent version the binding was compiled from: the newest version on the dev timeline. Versions saved on branches are ignored.
</ResponseField>

<ResponseField name="data.attached" type="string[]">
  The numbers that were attached, after trimming.
</ResponseField>

<ResponseField name="errors" type="null | array">
  `null` on success, or a list of error objects if the request failed. Returns `404 NOT_FOUND` for an unknown agent, `400 NO_VERSIONS` when the agent has no saved versions, and `422 COMPILE_FAILED` when the newest version cannot be compiled.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "agent_id": "56ad3ffc-41c3-4466-b41f-220d17779a74",
      "persona_id": "4cbdee81-f067-4fb7-8738-0995316ab3ce",
      "pathway_id": "48e86cb8-4d1a-4be6-a85a-4c277255eeb4",
      "compiled_from_version": "4adbe770-fc45-42ea-aa17-7533429c34f3",
      "attached": [
        "+18005551234",
        "+18005556789"
      ]
    },
    "errors": null
  }
  ```

  ```json Staging Not Published theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "AGENT_ENV_UNPINNED",
        "message": "Staging has no published version. Publish to staging first."
      }
    ]
  }
  ```

  ```json Invalid Numbers theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "INVALID_INBOUND_NUMBERS",
        "message": "Some phone numbers were not found or do not belong to you"
      }
    ]
  }
  ```

  ```json Invalid Body theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "INVALID_BODY",
        "message": "inbound_numbers must be a non-empty array of phone numbers"
      }
    ]
  }
  ```

  ```json No Versions theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "NO_VERSIONS",
        "message": "Agent has no saved versions — save it in the builder first"
      }
    ]
  }
  ```

  ```json Not Found theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "NOT_FOUND",
        "message": "Agent not found"
      }
    ]
  }
  ```
</ResponseExample>

***

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


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