Create Phone Number

Create a new phone number. If using Twilio as the provider, this will automatically configure the necessary trunk infrastructure.

HTTP Request

$
POST https://app.resemble.ai/api/v2/phone_numbers

Request Body

Outbound Trunk Configuration (Optional)

Inbound Trunk Configuration (Optional)

Example Request

$
curl --request POST "https://app.resemble.ai/api/v2/phone_numbers" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  --data '{
>
    "phone_number": "+14155551234",
>
    "label": "Support Line",
>
    "supports_inbound": true,
>
    "supports_outbound": false,
>
    "provider": "twilio",
>
    "twilio_account_sid": "AC...",
>
    "twilio_auth_token": "your_auth_token"
>
  }'

Response (Success)

1
{
2
  "success": true,
3
  "item": {
4
    "id": 1,
5
    "phone_number": "+14155551234",
6
    "label": "Support Line",
7
    "supports_inbound": true,
8
    "supports_outbound": false,
9
    "provider": "twilio",
10
    "status": "active",
11
    "agent_id": null,
12
    "agent_name": null,
13
    "agent_uuid": null,
14
    "outbound_trunk": {},
15
    "inbound_trunk": {
16
      "twilio_trunk_sid": "TK...",
17
      "domain_name": "example.pstn.twilio.com",
18
      "configured": true,
19
      "configured_at": "2025-01-27T10:00:00Z",
20
      "livekit_trunk_id": "TR_...",
21
      "livekit_dispatch_rule_id": "DR_...",
22
      "livekit_configured": true,
23
      "livekit_configured_at": "2025-01-27T10:00:00Z"
24
    },
25
    "twilio_account_sid": "AC...",
26
    "has_twilio_credentials": true,
27
    "created_at": "2025-01-27T10:00:00Z",
28
    "updated_at": "2025-01-27T10:00:00Z"
29
  },
30
  "message": "Phone number created successfully"
31
}

Response (Error)

1
{
2
  "success": false,
3
  "errors": {
4
    "phone_number": ["is already in use"],
5
    "label": ["can't be blank"],
6
    "provider": ["Invalid provider. Must be one of: twilio"],
7
    "twilio_credentials": ["Twilio Account SID and Auth Token are required when provider is Twilio"],
8
    "twilio_trunk": ["Failed to create Twilio trunk: Invalid credentials"]
9
  },
10
  "message": "Failed to create phone number"
11
}

Validation Rules

• phone_number: Required, must be unique across the platform, E.164 format recommended
• label: Required, cannot be empty
• provider: Must be “twilio” (currently only supported provider)
• twilio_account_sid: Required when provider is “twilio”
• twilio_auth_token: Required when provider is “twilio”
• outbound_trunk.transport: Must be one of: “auto”, “udp”, “tcp”, “tls”
• outbound_trunk.media_encryption: Must be one of: “disabled”, “allowed”, “required”
• inbound_trunk.media_encryption: Must be one of: “disabled”, “allowed”, “required”
• inbound_trunk.allowed_addresses: Must be array of strings
• inbound_trunk.allowed_numbers: Must be array of strings

Automatic Twilio Setup

When you create a phone number with Twilio provider and credentials:

1. Twilio Trunk Setup (automatic):

   • Creates SIP trunk in Twilio
   • Configures origination URLs for inbound (if supports_inbound: true)
   • Creates credential lists for outbound (if supports_outbound: true)
   • Sets up connection policies for inbound routing

2. Rollback on Failure:

   • If any setup step fails, all external resources are automatically cleaned up
   • No orphaned resources are left in Twilio
   • Detailed error messages guide you to resolution

Important Notes

• Phone numbers cannot be updated after creation
• If you need to make changes, delete and recreate the phone number
• Twilio credentials are securely stored and never returned in API responses
• The has_twilio_credentials flag indicates whether credentials are configured