Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt

Use this file to discover all available pages before exploring further.

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.