Telephony

The Telephony API manages your voice infrastructure: phone numbers (provisioned via Twilio, Vonage, or Telnyx) and SIP trunks for direct carrier connections.

Base path: /api/v1/telephony

---

Phone Numbers

Search available numbers

Find available phone numbers to provision.

GET /api/v1/telephony/numbers/search

Query parameters:

Parameter	Type	Description
country	string	ISO 3166-1 alpha-2 country code (e.g., US, GB, AU)
areaCode	string	Area code / number prefix
contains	string	Digits the number must contain
capabilities	string	Comma-separated: voice, sms, mms
provider	string	twilio, vonage, telnyx
tollFree	boolean	Search toll-free numbers only
limit	integer	Max results (default 10, max 50)

curl "https://api.voisnap.ai/api/v1/telephony/numbers/search?country=US&areaCode=415&capabilities=voice,sms&limit=5" \
  -H "Authorization: Bearer vsnp_live_..."

numbers = client.telephony.numbers.search(
    country="US",
    area_code="415",
    capabilities=["voice", "sms"],
    limit=5
)
for n in numbers:
    print(f"{n.phone_number} — {n.monthly_cost_usd}/mo — Provider: {n.provider}")

const numbers = await client.telephony.numbers.search({
  country: 'US',
  areaCode: '415',
  capabilities: ['voice', 'sms'],
  limit: 5,
});

Response:

{
  "numbers": [
    {
      "phoneNumber": "+14155550100",
      "country": "US",
      "region": "California",
      "locality": "San Francisco",
      "provider": "twilio",
      "capabilities": ["voice", "sms"],
      "tollFree": false,
      "monthlyCostUsd": 1.15
    },
    {
      "phoneNumber": "+14155550123",
      "country": "US",
      "region": "California",
      "locality": "San Francisco",
      "provider": "twilio",
      "capabilities": ["voice", "sms"],
      "tollFree": false,
      "monthlyCostUsd": 1.15
    }
  ]
}

---

Provision a number

Purchase and provision a phone number to your account.

POST /api/v1/telephony/numbers

curl -X POST https://api.voisnap.ai/api/v1/telephony/numbers \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "provider": "twilio",
    "friendlyName": "Acme Support Line"
  }'

number = client.telephony.numbers.provision(
    phone_number="+14155550100",
    provider="twilio",
    friendly_name="Acme Support Line"
)
print(f"Provisioned: {number.id}")

Response:

{
  "id": "num_01HXABC123DEF",
  "phoneNumber": "+14155550100",
  "friendlyName": "Acme Support Line",
  "country": "US",
  "provider": "twilio",
  "capabilities": ["voice", "sms"],
  "assignedAgentId": null,
  "status": "active",
  "monthlyCostUsd": 1.15,
  "provisionedAt": "2025-06-16T10:00:00Z"
}

---

List provisioned numbers

GET /api/v1/telephony/numbers

curl https://api.voisnap.ai/api/v1/telephony/numbers \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "data": [
    {
      "id": "num_01HXABC123DEF",
      "phoneNumber": "+14155550100",
      "friendlyName": "Acme Support Line",
      "assignedAgentId": "agt_01HXK8Z3MNPQRS",
      "assignedAgentName": "Aria – Support Agent",
      "status": "active",
      "monthlyCostUsd": 1.15,
      "provisionedAt": "2025-06-16T10:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "totalPages": 1
}

---

Assign a number to an agent

POST /api/v1/telephony/numbers/{numberId}/assign/{agentId}

curl -X POST "https://api.voisnap.ai/api/v1/telephony/numbers/num_01HXABC123DEF/assign/agt_01HXK8Z3MNPQRS" \
  -H "Authorization: Bearer vsnp_live_..."

client.telephony.numbers.assign(
    number_id="num_01HXABC123DEF",
    agent_id="agt_01HXK8Z3MNPQRS"
)

await client.telephony.numbers.assign('num_01HXABC123DEF', 'agt_01HXK8Z3MNPQRS');

---

Unassign a number

POST /api/v1/telephony/numbers/{numberId}/unassign

curl -X POST "https://api.voisnap.ai/api/v1/telephony/numbers/num_01HXABC123DEF/unassign" \
  -H "Authorization: Bearer vsnp_live_..."

---

Release a number

Releases (cancels) the number. Monthly billing stops at the next billing cycle.

DELETE /api/v1/telephony/numbers/{numberId}

:::warning This immediately removes the number from your account. Any calls to this number will no longer route to Voisnap. :::

curl -X DELETE https://api.voisnap.ai/api/v1/telephony/numbers/num_01HXABC123DEF \
  -H "Authorization: Bearer vsnp_live_..."

---

Number usage stats

GET /api/v1/telephony/numbers/{numberId}/stats

curl "https://api.voisnap.ai/api/v1/telephony/numbers/num_01HXABC123DEF/stats?dateFrom=2025-06-01&dateTo=2025-06-30" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "numberId": "num_01HXABC123DEF",
  "phoneNumber": "+14155550100",
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "inboundCalls": 842,
  "outboundCalls": 298,
  "totalMinutes": 4812,
  "totalCostUsd": 57.74
}

---

Number pricing

GET /api/v1/telephony/numbers/pricing

Query: country, provider, tollFree.

Response:

{
  "country": "US",
  "provider": "twilio",
  "localNumber": { "monthlyCostUsd": 1.15, "inboundMinuteCostUsd": 0.0085, "outboundMinuteCostUsd": 0.013 },
  "tollFreeNumber": { "monthlyCostUsd": 2.15, "inboundMinuteCostUsd": 0.022, "outboundMinuteCostUsd": 0.013 }
}

---

SIP Trunks

SIP trunks allow you to connect Voisnap to your own carrier or PBX.

Create a SIP trunk

POST /api/v1/telephony/sip-trunks

curl -X POST https://api.voisnap.ai/api/v1/telephony/sip-trunks \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporate PBX",
    "sipUri": "sip:trunk.acme.com:5060",
    "username": "voisnap_trunk_user",
    "password": "s3cur3p@ssw0rd",
    "transport": "TLS",
    "codecs": ["PCMU", "PCMA", "G722"],
    "maxConcurrentCalls": 50
  }'

Response:

{
  "id": "sip_01HXMN8ZABC",
  "name": "Acme Corporate PBX",
  "sipUri": "sip:trunk.acme.com:5060",
  "transport": "TLS",
  "status": "pending_verification",
  "maxConcurrentCalls": 50,
  "voisnapSipEndpoint": "sip:inbound.voisnap.ai:5061",
  "createdAt": "2025-06-16T10:00:00Z"
}

List SIP trunks

GET /api/v1/telephony/sip-trunks

Update a SIP trunk

PATCH /api/v1/telephony/sip-trunks/{trunkId}

Delete a SIP trunk

DELETE /api/v1/telephony/sip-trunks/{trunkId}

Test SIP trunk connectivity

POST /api/v1/telephony/sip-trunks/{trunkId}/test

Sends an OPTIONS ping to the SIP endpoint and verifies registration.

curl -X POST https://api.voisnap.ai/api/v1/telephony/sip-trunks/sip_01HXMN8ZABC/test \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "trunkId": "sip_01HXMN8ZABC",
  "status": "reachable",
  "latencyMs": 42,
  "testedAt": "2025-06-16T10:05:00Z"
}