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

# Assigning agents to numbers

> Bind a published agent version to a number for inbound and outbound calls.

A phone number routes calls to an agent only after you assign a published agent version to it. Each number has two independent slots — one for inbound calls and one for outbound calls — so the same number can answer with one agent and dial out with another, or use the same agent for both.

Assignment is performed by the agent version **publish** endpoint. Publishing a version both marks it as live and deploys it onto the inbound and/or outbound slots of the numbers you name in the request.

## The two-slot model

Every number stores two assignment slots:

| Slot     | Column                      | Applies to                     |
| -------- | --------------------------- | ------------------------------ |
| Inbound  | `inbound_agent_version_id`  | Calls placed *to* the number   |
| Outbound | `outbound_agent_version_id` | Calls placed *from* the number |

The slots are independent. Setting one direction never touches the other unless you explicitly target `both`. An empty slot means no agent handles that direction for that number.

<Note>
  Only published versions are assignable. The publish endpoint sets the version's `published` flag to `true` before it writes the assignment, so deploying a version always publishes it in the same call.
</Note>

## Assign a version

Call the publish endpoint with the version you want live, the numbers to deploy to, and the direction.

```
POST /core/agents/{id}/versions/{version}/publish
```

```json theme={null}
{
  "phone_numbers": ["+15551234567", "+15559876543"],
  "direction": "inbound"
}
```

| Field                    | Type                              | Default   | Description                                                                      |
| ------------------------ | --------------------------------- | --------- | -------------------------------------------------------------------------------- |
| `phone_numbers`          | array of strings                  | none      | Numbers to deploy this version to. Omit to publish without changing assignments. |
| `unassign_phone_numbers` | array of strings                  | none      | Numbers to clear this agent from.                                                |
| `direction`              | `inbound` \| `outbound` \| `both` | `inbound` | Which slot(s) to write or clear.                                                 |

The endpoint requires the `agents:manage` scope and returns the list of updated `PhoneNumber` records.

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/{id}/versions/2/publish \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{"phone_numbers": ["+15551234567"], "direction": "both"}'
```

<Warning>
  Publishing is blocked while a version's instructions are being generated, and when the instructions are stale (`dirty`) and have not been manually edited — regenerate first. Both cases return `400`.
</Warning>

## Direction values

| Value      | Inbound slot | Outbound slot |
| ---------- | ------------ | ------------- |
| `inbound`  | written      | unchanged     |
| `outbound` | unchanged    | written       |
| `both`     | written      | written       |

```
direction: both
                ┌──────────────────────────────┐
                │        +1 555 123 4567        │
   inbound  ───▶│  inbound_agent_version_id ◀── │  agent v2
   outbound ◀───│  outbound_agent_version_id ◀──│  agent v2
                └──────────────────────────────┘
```

## Unassign a version

To remove an agent from a number, send the numbers under `unassign_phone_numbers` with the direction to clear. Only slots currently pointing at a version of this agent are cleared — slots holding a different agent are left untouched.

```json theme={null}
{
  "unassign_phone_numbers": ["+15551234567"],
  "direction": "outbound"
}
```

You can assign and unassign in the same request by including both `phone_numbers` and `unassign_phone_numbers`. The response combines both result sets, deduplicated by number.

## Editing from the Phone Numbers page

The **Phone Numbers** page provides an edit dialog as an alternate entry point to the same flow. For each number you pick an agent and version per side (**Inbound** and **Outbound**), and selecting **None** clears that side. Behind the dialog, choosing a version calls the same publish endpoint, and clearing a side calls the same unassign path — so the result is identical to driving the API directly.

## Related

<CardGroup cols={2}>
  <Card title="Creating an agent" icon="robot" href="/agents/creating-an-agent">
    Build and publish the agent version you assign to a number.
  </Card>

  <Card title="Telephony overview" icon="phone" href="/telephony/overview">
    How numbers, calls, and agents fit together.
  </Card>
</CardGroup>