---
title: "Assign Phone Number"
method: POST
path: "/v1/smb/phone-numbers/assignments"
tags: ["smb", "SMB"]
---

# Assign Phone Number

`POST /v1/smb/phone-numbers/assignments`

## Request

- Base URL: `https://api.elevenlabs.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.elevenlabs.io/v1/smb/phone-numbers/assignments`
- Auth: none declared

Give a receptionist a phone number. A number the workspace already holds but has not attached is used first. Otherwise, in the US and Canada, a number with one of the requested `area_codes` is taken from the pool or bought, falling back to any number in the business's country. In countries that require paperwork, the number is issued right away but takes public calls only once the workspace's own registration is approved (see `accepts_public_calls`). Counts toward the plan's phone number limit, and free plans can take only a few new numbers a day. Returns 404 when no number is available and 403 `telephony_managed_by_reseller` when the reseller supplies the workspace's numbers from its own Twilio account and none is free.

## Headers

- `xi-api-key` string, nullable: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
- `xi-workspace-id` string, nullable: The customer workspace a reseller's API key acts on.

## Request body

- CreatePhoneAssignmentRequest: Body for giving a receptionist a phone number.
  - `customer_facing_agent_id` string, required: The receptionist that answers calls to the number.
  - `area_codes` string[], nullable: Preferred US or Canadian area codes, e.g. `["415", "628"]`. Codes outside the business's country are ignored, and any number is given when none of these is available.
  - `number_type` 'local' | 'mobile': Which kind of regulated number a request or an issued number is for. Lives here rather than next to the application model because a phone assignment records it too, and the assignment model cannot import from ``telephony.models`` without a cycle back into this module.

## Response `201`

Successful Response

- SMBPhoneAssignmentDBModel: Persisted phone assignment; see ``SMBPhoneAssignmentBase`` for field semantics.
  - `phone_number` string
  - `is_byo` boolean: True when the phone is bring-your-own: registered by the workspace using their own telephony provider (Twilio credentials or SIP trunk). BYO phones are never part of the shared pool, do not count against the tier-based phone quota, and are deleted (rather than returned to the pool) on release.
  - `provider` 'twilio' | 'sip_trunk': Telephony provider for this phone number. Defaults to twilio for backwards compatibility with existing documents.
  - `nanp_area_code` integer: US/Canada NANP area code (NPA) as an integer.
  - `customer_facing_agent_id` string, nullable: Determines assignment status: None = pool (unassigned), non-None = assigned to this customer-facing agent. When set, inbound calls to this phone route to that agent.
  - `deactivated_at_unix` integer, nullable: Unix timestamp when this assignment was deactivated. Drives the per-assignment 14-day grace cleanup. None when active.
  - `deactivation_reason` 'tier_downgrade' | 'no_entitlement' | 'user': Why a phone assignment is currently inactive.
  - `regulatory_status` 'held' | 'approved': Regulatory standing of a number in a country that requires paperwork. Absent (``None``) on numbers from countries with no requirements, which is every pooled US/Canada number — those are usable the moment they are bought.
  - `regulatory_number_type` 'local' | 'mobile': Which kind of regulated number a request or an issued number is for. Lives here rather than next to the application model because a phone assignment records it too, and the assignment model cannot import from ``telephony.models`` without a cycle back into this module.
  - `regulatory_country` string
  - `_id` string, required
  - `created_at_unix` integer: Unix timestamp (seconds since epoch)
  - `updated_at_unix` integer: Unix timestamp (seconds since epoch)
  - `is_active` boolean, required
  - `accepts_public_calls` boolean, required: Whether inbound calls from the public may reach the agent.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-30** `b77988199a2e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/smb/phone-numbers/assignments/post.md)

---

[API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) - [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/revisions/b402c33b07b4?raw)