Skip to main content
POST
/
api
/
phone-numbers
/
import
curl -X POST "https://api.zudu.ai/api/phone-numbers/import" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -d '{
    "phone_number": "+14155551234",
    "provider": "twilio",
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_auth_token_here",
    "nickname": "Main Office Line",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456"
  }'

{
  "message": "Phone number validated and imported successfully",
  "status": "success",
  "error": null,
  "data": {
    "phone_number": {
      "phone_number": "+14155551234",
      "nickname": "Main Office Line",
      "organization_id": "org_1234567890",
      "phone_number_type": "CUSTOM",
      "number_provider": "twilio",
      "inbound_agent_id": "agent_123",
      "outbound_agent_id": "agent_456",
      "inbound_trunk_id": "trunk_inbound_abc123",
      "outbound_trunk_id": "trunk_outbound_def456",
      "dispatch_rule_id": "dispatch_xyz789",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "validation_result": {
      "phone_number": "+14155551234",
      "friendly_name": "Main Office Line",
      "capabilities": {
        "voice": true,
        "sms": true
      },
      "status": "active",
      "message": "Phone number validated successfully"
    },
    "import_details": {
      "imported_at": 1705315800000,
      "organization_id": "org_1234567890",
      "provider": "twilio"
    }
}
Validate phone number ownership with a provider (Twilio or Plivo) and import it into your organization. This endpoint will create LiveKit SIP trunks and configure routing for both inbound and outbound calls. 
curl -X POST "https://api.zudu.ai/api/phone-numbers/import" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -d '{
    "phone_number": "+14155551234",
    "provider": "twilio",
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_auth_token_here",
    "nickname": "Main Office Line",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456"
  }'

{
  "message": "Phone number validated and imported successfully",
  "status": "success",
  "error": null,
  "data": {
    "phone_number": {
      "phone_number": "+14155551234",
      "nickname": "Main Office Line",
      "organization_id": "org_1234567890",
      "phone_number_type": "CUSTOM",
      "number_provider": "twilio",
      "inbound_agent_id": "agent_123",
      "outbound_agent_id": "agent_456",
      "inbound_trunk_id": "trunk_inbound_abc123",
      "outbound_trunk_id": "trunk_outbound_def456",
      "dispatch_rule_id": "dispatch_xyz789",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "validation_result": {
      "phone_number": "+14155551234",
      "friendly_name": "Main Office Line",
      "capabilities": {
        "voice": true,
        "sms": true
      },
      "status": "active",
      "message": "Phone number validated successfully"
    },
    "import_details": {
      "imported_at": 1705315800000,
      "organization_id": "org_1234567890",
      "provider": "twilio"
    }
}

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Request Body

​
phone_number
string
required
Phone number in E.164 format to importExample: "+14155551234"
​
provider
string
required
Phone number providerValid values: twilio, plivoExample: "twilio"
​
account_sid
string
required
Provider account SID
  • For Twilio: Account SID (starts with AC)
  • For Plivo: Auth ID
Example: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
​
auth_token
string
required
Provider authentication token
  • For Twilio: Auth Token
  • For Plivo: Auth Token
Example: "your_auth_token_here"
​
nickname
string
Optional nickname/label for the phone numberExample: "Main Office Line"
​
inbound_agent_id
string
Optional agent ID to assign for inbound callsExample: "agent_123"
​
outbound_agent_id
string
Optional agent ID to assign for outbound callsExample: "agent_456"

​
Response Fields

​
phone_number
object
The imported phone number object with all configurationIncludes:
  • phone_number: Phone number in E.164 format
  • nickname: Nickname if provided
  • organization_id: Organization ID
  • phone_number_type: Type (usually CUSTOM for imported numbers)
  • number_provider: Provider name
  • inbound_agent_id: Assigned inbound agent ID (if provided)
  • outbound_agent_id: Assigned outbound agent ID (if provided)
  • inbound_trunk_id: LiveKit inbound trunk ID
  • outbound_trunk_id: LiveKit outbound trunk ID
  • dispatch_rule_id: LiveKit dispatch rule ID
  • created_at: Creation timestamp
​
validation_result
object
Validation result from the provider
  • phone_number: Validated phone number
  • friendly_name: Friendly name from provider
  • capabilities: Phone number capabilities (voice, SMS, etc.)
  • status: Status from provider
  • message: Validation message
​
import_details
object
Import metadata
  • imported_at: Timestamp when import completed
  • organization_id: Organization ID
  • provider: Provider name

​
Error Responses

​
error
string
Bad Request - Validation error or invalid provider
{
  "message": "Phone number validation failed",
  "status": "error",
  "error": "Invalid phone number format"
}
Or:
{
  "message": "Unsupported provider",
  "status": "error",
  "error": "Provider 'invalid_provider' is not supported."
}
​
error
string
Unauthorized - Missing or invalid API key/secret, or provider authentication failed
{
  "message": "Twilio trunk setup failed",
  "status": "error",
  "error": "Authentication failed. Please verify your Twilio Account SID and Auth Token are correct."
}
​
error
string
Conflict - Phone number already exists
{
  "message": "Phone number already exists",
  "status": "error",
  "error": "Phone number is already registered in your organization"
}
​
error
string
Internal Server Error - Failed to import phone number
{
  "message": "Failed to validate and import phone number",
  "status": "error",
  "error": "Database connection failed"
}

​
Notes

  • The endpoint validates phone number ownership with the provider before importing
  • For Twilio: Creates SIP trunks, LiveKit inbound/outbound trunks, and dispatch rules
  • For Plivo: Creates Plivo SIP trunks and LiveKit trunks
  • Provider credentials are validated with the provider API before import
  • If the provider account already exists, only the auth token will be updated
  • Phone numbers must be in E.164 format (e.g., +14155551234)
  • Imported phone numbers are immediately available for use
  • If LiveKit trunk creation fails, the import will fail with an error message