Skip to main content
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

Providerprovider idSetup methods
Twiliotwilioapi_key
Telnyxtelnyxapi_key, guided_telnyx
SignalWiresignalwireapi_key
Vonagevonageapi_key
Manual (any SIP trunk)manualmanual

​
Endpoints

MethodPathDescription
GET/v1/voip-connectionsList connections
POST/v1/voip-connectionsCreate a connection
GET/v1/voip-connections/{connection_id}Retrieve a connection
PATCH/v1/voip-connections/{connection_id}Update credentials / name
DELETE/v1/voip-connections/{connection_id}Remove a connection
POST/v1/voip-connections/testTest raw credentials (no persisted connection)
POST/v1/voip-connections/suggest-nameInfer a display name from credentials
GET/v1/voip-connections/{connection_id}/available-numbersList importable numbers
POST/v1/voip-connections/{connection_id}/import-numbersImport selected numbers

​
Connection object

{
  "id": 5,
  "name": "Acme Telnyx Main",
  "provider": "telnyx",
  "setup_method": "api_key",
  "status": "connected",
  "inferred_name": false,
  "sip_config": { "domain": "acme.sip.telnyx.com" },
  "last_tested_at": "2026-04-20T18:24:10.113Z",
  "numbers_imported": 3,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
FieldTypeDescription
idintegerConnection id
namestringDisplay name
providerstringtwilio, telnyx, signalwire, vonage, manual
setup_methodstringapi_key, manual, guided_telnyx
statusstringpending, testing, connected, error
inferred_namebooleantrue when we auto-generated the name
sip_configobjectProvider-specific SIP config (read-only; redacted)
last_tested_attimestamp | nullLast successful credential test
numbers_importedintegerCount of phone numbers imported through this connection
Credentials are never returned by the API once saved. GET responses carry only the fields above; the full credentials object is write-only. Use PATCH with the new credentials to rotate them.

​
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

FieldTypeRequiredDescription
providerstringyesProvider id (see table above)
namestringnoDefaults to a provider-inferred value
setup_methodstringnoDefaults to api_key; Telnyx supports guided_telnyx
credentialsobjectyesProvider-specific key/secret/connection fields
sip_configobjectnoExtra SIP config — e.g. {"domain": "..."}
verification_evidence_idUUIDyesId returned by POST /voip-connections/test
Returns 201 Created with the Connection object. Errors:
StatusCondition
400Provider mismatch (evidence generated for a different provider)
400Evidence reused / stale / missing
422Credentials failed re-verification

​
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"}'
FieldTypeDescription
namestring
credentialsobjectRotate credentials. Requires a fresh verification_evidence_id
sip_configobject
verification_evidence_idUUIDRequired if credentials is present

​
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. 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. 
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" }
  }'
Response (success)
{
  "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..." }
  }'
Response
{
  "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 (inbound routing + outbound authorization check). 
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"]}'
Response
{
  "imported_count": 2,
  "provider_charge_estimate_cents": 0,
  "provider_charge_note": "No upstream charges for imports through this provider.",
  "results": [
    { "id": 201, "number": "+15550001234", "status": "provisioning" },
    { "id": 202, "number": "+15550009999", "status": "provisioning" }
  ]
}

Phone Numbers

Assign agents to imported numbers and run verify-voip.

Outbound Calls

Outbound calling requires a VoIP-backed number.