Developer

VoIP Connections

Bring your own phone numbers into ThunderPhone from Twilio, Telnyx, SignalWire, or Vonage: 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,
  "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.

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.

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
  }
}

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
}

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#