Skip to main content
POST
/
api
/
phone-numbers
{
  "phone_number": "+15551234567",
  "provider": "twilio",
  "supports_inbound": true,
  "supports_outbound": true,
  "integration_id": "intg_a1b2c3d4e5f6"
}

{
  "success": true,
  "message": "Phone number imported successfully with twilio",
  "data": {
    "phone_number_id": "phon_a1b2c3d4e5f6",
    "phone_number": "+15551234567",
    "provider": "twilio",
    "status": "free",
    "supports_inbound": true,
    "supports_outbound": true,
    "integration_id": "intg_a1b2c3d4e5f6",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
Import a phone number from a provider (Twilio or LiveKit SIP).
For Twilio numbers, you must first create a Twilio integration and provide its ID. For SIP numbers, LiveKit trunks are automatically created.

​
Headers

​
X-API-Key
string
required
Your API key for authentication.
​
X-Organization-Id
string
required
The organization ID.
​
Content-Type
string
required
Must be application/json.

​
Permissions

  • phone_numbers:create (admin, agent_manager)

​
Request Body

​
phone_number
string
required
Phone number in E.164 format (e.g., +12345678900).
​
provider
string
required
Provider type: twilio or sip.
​
supports_inbound
boolean
default:"false"
Whether the number supports inbound calls.
​
supports_outbound
boolean
default:"false"
Whether the number supports outbound calls.

​
Twilio-Specific Parameters

​
integration_id
string
Integration ID (required for Twilio provider). Must be a valid Twilio integration.

​
SIP-Specific Parameters (LiveKit)

​
sip_trunk_name
string
Name for the SIP trunk.
​
sip_username
string
SIP username for authentication.
​
sip_password
string
SIP password for authentication.
​
sip_server_address
string
SIP server address (required for outbound).
​
inbound_room_name
string
Room name pattern for inbound calls.
​
inbound_pin
string
Optional PIN for inbound calls (4-10 characters).
​
media_encryption
string
default:"allow"
SIP media encryption mode: disable, allow, or require.

​
Response

​
success
boolean
Indicates if the import was successful.
​
message
string
Human-readable success message.
​
data
object
The created phone number object.
{
  "phone_number": "+15551234567",
  "provider": "twilio",
  "supports_inbound": true,
  "supports_outbound": true,
  "integration_id": "intg_a1b2c3d4e5f6"
}

{
  "phone_number": "+15559876543",
  "provider": "sip",
  "supports_inbound": true,
  "supports_outbound": true,
  "sip_trunk_name": "my-trunk",
  "sip_server_address": "sip.example.com",
  "sip_username": "user",
  "sip_password": "pass",
  "media_encryption": "require"
}

{
  "success": true,
  "message": "Phone number imported successfully with twilio",
  "data": {
    "phone_number_id": "phon_a1b2c3d4e5f6",
    "phone_number": "+15551234567",
    "provider": "twilio",
    "status": "free",
    "supports_inbound": true,
    "supports_outbound": true,
    "integration_id": "intg_a1b2c3d4e5f6",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Errors

​
400
object
Missing required fields or invalid provider.
​
404
object
Integration not found (for Twilio).
​
403
object
Integration belongs to different organization.
​
409
object
Phone number already exists in the system.