---
title: "Assign Phone Number"
method: POST
path: "/voice_agents/voice-agents/{voice_agent_id}/assign-phone-number"
tags: ["voice_agents"]
---

# Assign Phone Number

`POST /voice_agents/voice-agents/{voice_agent_id}/assign-phone-number`

Assign a phone number to a voice agent.

Logic:
1. Check if agent already has a phone number assigned
2. Look for an available (unassigned) Twilio phone number
3. If no available number, create a new Twilio phone number
4. Assign the number to the agent's external_id

## Path parameters

- `voice_agent_id` string, uuid, required

## Response `200`

Successful Response

- PhoneNumberDBRead — Phone number read model including LiveKit-specific fields.
  - `external_id` string, required
  - `external_created_at` string, date-time, required
  - `external_updated_at` string, date-time, required
  - `external_assistant_id` string, nullable, required
  - `number` string, required
  - `name` string, nullable, required
  - `provider` 'twilio' | 'byo-phone-number' | 'telnyx', required
  - `status` 'active' | 'activating' | 'blocked', nullable, required
  - `outbound_voice_agent_id` string, uuid, nullable, required
  - `id` string, uuid, required
  - `tenant_id` string, uuid, nullable
  - `inbound_voice_agent_id` string, uuid, nullable
  - `voice_platform` string, nullable
  - `livekit_dispatch_rule_id` string, nullable
  - `livekit_inbound_trunk_id` string, nullable
  - `livekit_outbound_trunk_id` string, nullable
  - `sip_prefix_to_strip` string, nullable
  - `sip_default_region` string, nullable
  - `language` string, nullable
  - `intent_context` string, nullable

## Other responses

- `422` — Validation Error

## Changes

> 21 revisions in range; 1 not diffed.

- **2026-09-03** `d65b8fefae34` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status

[Change history](https://skmtc.dev/getanana/apis/cleon-api/changes/voice_agents/voice-agents/:voice_agent_id/assign-phone-number/post.md)

---

[API](https://skmtc.dev/getanana/apis/cleon-api.md) · [All operations](https://skmtc.dev/getanana/apis/cleon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getanana/apis/cleon-api/revisions/59d90f796108?raw)