ELelevenlabs
smb
SMB

Assign Phone Number

Changed on

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.

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

Headers

xi-api-keystring 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-idstring nullable

The customer workspace a reseller's API key acts on.

Request body

customer_facing_agent_idstring required

The receptionist that answers calls to the number.

area_codesstring[] 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

Successful Response

phone_numberstring
is_byoboolean

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_codeinteger

US/Canada NANP area code (NPA) as an integer.

customer_facing_agent_idstring 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_unixinteger 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_countrystring
_idstring required
created_at_unixinteger

Unix timestamp (seconds since epoch)

updated_at_unixinteger

Unix timestamp (seconds since epoch)

is_activeboolean required
accepts_public_callsboolean required

Whether inbound calls from the public may reach the agent.

Changes