VoIP Connections

Bring your own phone numbers into ThunderPhone from Twilio or Telnyx, or from SignalWire, Vonage, Plivo and any other SIP trunk as manual connections: create VoIP connections, verify credentials, and manage imported numbers.

VoIP connections let you plug your existing telephony provider into ThunderPhone. Once connected, you can list, import, and verify phone numbers from your provider account; imported numbers become Phone number resources you can assign agents to.

Supported providers#

Endpoints#

Connection object#

{
  "id": 5,
  "name": "Acme Telnyx Main",
  "provider": "telnyx",
  "status": "connected",
  "setup_method": "api_key",
  "inferred_name": false,
  "credentials": { "apiKey": "********", "connectionId": "123456" },
  "sip_config": { "domain": "acme.sip.telnyx.com" },
  "test_result": { "checks": { "credentials_valid": true } },
  "last_tested_at": "2026-04-20T18:24:10.113Z",
  "numbers_imported": 3,
  "provisioning_supported": true,
  "provisioning_message": null,
  "transfer_refused_at": null,
  "transfer_enabled_at": null,
  "relay": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

List connections#

curl https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns an array of Connection objects.

Create a connection#

Creation is a two-phase flow:

1. Call POST /v1/voip-connections/test with the credentials and get back a verification evidence id if the test passes.
2. Call this endpoint with the same credentials plus verification_evidence_id — the evidence proves the credentials were already validated, avoiding double-billing for the test.

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Telnyx Main",
    "provider": "telnyx",
    "setup_method": "api_key",
    "credentials": {
      "apiKey": "KEY...",
      "connectionId": "123456"
    },
    "sip_config": { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

Request fields#

Returns 201 Created with the Connection object. With enable_transfers, a Twilio error never fails the create: the connection is saved without transfers, transfer_enabled_at stays null, and test_result.transfer_enable_error says why. Call Turn on call transfers to try again; success removes transfer_enable_error.

Errors:

Update a connection#

curl -X PATCH https://api.thunderphone.com/v1/voip-connections/5 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed"}'

Secrets are merged, never echoed: a key containing key, token, secret or password that you send as "********", as an empty string, or omit entirely keeps its stored value; send null to clear it. A request that only echoes the masked read-back is not a credential change and needs no evidence.

Delete a connection#

curl -X DELETE https://api.thunderphone.com/v1/voip-connections/5 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 204 No Content. Phone numbers imported through the deleted connection are not removed — they stay in your org with voip_connection_id cleared.

Turn on call transfers#

Twilio trunks refuse cold transfers until the trunk allows them. This sets the connection's Twilio SIP trunk to TransferMode=enable-all and leaves the trunk's caller-ID setting as it is. With Twilio's default (TransferCallerId=from-transferee), the transferred call shows the number of the person being transferred (the caller on inbound calls, the person your agent called on outbound calls). Transferred calls are then carried and billed on your Twilio account. Admin or owner only.

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/enable-transfers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 200 with the connection object: transfer_enabled_at set and transfer_refused_at cleared. It is safe to call again: Twilio is left unchanged if transfers are already on, and the call returns 200.

Test credentials#

Probes the provider API with the supplied credentials (for manual, checks that the SIP host resolves to a public address and, for TCP/TLS, accepts a connection on the port — a real call is only placed when a number is verified). On success, the response includes a verification_evidence_id you can pass to Create or Update to create/rotate the connection without a second round trip.

Pass connection_id to test an edit: the submitted credentials / sip_config are merged over the stored connection (masked, blank or omitted secrets keep their stored values, exactly as Update will merge them), so the evidence matches the update you are about to send.

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

Get the inbound SIP host#

GET /v1/voip-connections/sip-host

Returns the SIP host a manual connection's trunk must send inbound calls to: sip.thunderphone.com, ThunderPhone's SIP edge. Point the trunk at <sip_host>:5060 for UDP or TCP, or <sip_host>:5061 for TLS, and address each call to the dialed number in E.164 form, with the same number, including the +, in both the request line and the To header (sip:+14155550142@<sip_host>). Read it from here rather than keeping a copy. Trunks set up earlier with a <your-project>.sip.livekit.cloud address keep working while the connection has no allowed source IPs. The edge's IP addresses are listed under IP allowlisting.

curl https://api.thunderphone.com/v1/voip-connections/sip-host \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "sip_host": "sip.thunderphone.com"
}

Suggest a connection name#

Asks the provider for an inferred display name. Used by the dashboard onboarding flow.

curl -X POST https://api.thunderphone.com/v1/voip-connections/suggest-name \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY..." }
  }'

{
  "suggested_connection_name": "Telnyx: Acme Main",
  "suggested_connection_name_inferred": true
}

Discover Twilio subaccounts#

Lists the active subaccounts a Twilio parent account can see, marking the ones this org already has a connection for. Pass either raw parent credentials or the connection_id of an existing Twilio connection. Subaccount auth tokens are read from Twilio and kept server-side under the returned discovery_id (valid for 30 minutes); they are never returned. Admin role required.

curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "accountSid": "ACparent...", "authToken": "..." }
  }'

{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}

An empty subaccounts array means the credentials belong to an account with no active subaccounts (or to a subaccount itself).

Connect Twilio subaccounts#

Creates one ordinary Twilio connection per selected subaccount, each with its own verification evidence and SIP trunk inside that subaccount. Rows are independent: one subaccount failing never blocks the others, and a failed sid can be sent again with the same discovery_id until it expires. Admin role required.

curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discovery_id":   "7c1e...",
    "subaccount_sids": ["ACsupport...", "ACsales..."]
  }'

{
  "results": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "status": "created", "connection": { "id": 9, "provider": "twilio", "setup_method": "twilio_subaccount", "...": "..." }, "error": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "status": "skipped", "connection": { "id": 5, "...": "..." }, "error": null }
  ]
}

Returns 400 when the discovery_id has expired ("Subaccount discovery expired. Run discovery again.").

List available numbers#

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns the list of phone numbers visible to this connection's credentials that are not yet imported into any ThunderPhone org:

[
  {
    "id": "provider-handle-abc",
    "number": "+15550001234",
    "friendlyName": "Main office",
    "type": "local",
    "capabilities": ["voice"],
    "region": "US-CA",
    "monthlyFee": 100
  }
]

Import numbers#

Moves the selected numbers into ThunderPhone as Phone number resources. Imports start in status="provisioning" — call POST /v1/phone-numbers/{id}/verify-voip to complete verification. For a manual SIP connection that places a short probe call from the number, through your trunk, to a ThunderPhone number — see Verify a VoIP-sourced number.

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

{
  "imported_count": 2,
  "provider_charge_estimate_cents": 0,
  "provider_charge_note": "Import does not create ThunderPhone charges. Provider charges are billed by your VoIP provider only.",
  "results": [
    { "id": 201, "number": "+15550001234", "status": "provisioning" },
    { "id": 202, "number": "+15550009999", "status": "provisioning" }
  ]
}

numbers accepts 1–50 entries per request.

Search purchasable numbers#

For connections where provisioning_supported is true (currently Telnyx only), search the provider's inventory for numbers you can buy without leaving ThunderPhone.

curl 'https://api.thunderphone.com/v1/voip-connections/5/search-numbers?country=US&area_code=415&type=local' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "results": [
    {
      "id": "provider-handle-abc",
      "number": "+14155550123",
      "friendlyName": "+1 415 555 0123",
      "type": "local",
      "capabilities": ["voice"],
      "region": "US-CA",
      "monthlyFee": 100,
      "monthlyFeeCurrency": "USD"
    }
  ],
  "provider_charge_note": "Purchasing this number and its recurring monthly service are billed directly by Telnyx. ThunderPhone does not add a provisioning fee."
}

Provision (buy) a number#

Places a number order with the provider using the connection's credentials, then registers the number in ThunderPhone. The provider — not ThunderPhone — bills the purchase and monthly fee.

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/provision-number \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "+14155550123"}'

{
  "order_id": "ord_abc123",
  "order_status": "pending",
  "provider_charge_note": "Purchasing this number and its recurring monthly service are billed directly by Telnyx. ThunderPhone does not add a provisioning fee.",
  "result": { "id": 203, "number": "+14155550123", "status": "provisioning" }
}

Returns 201 Created when a new order was placed, or 200 OK when the number was already owned and only registration was needed.

Related#