Phones - Sip Trunks

Get SIP trunk by ID

get/api/v1/phones/sip-trunks/:id

Request

Base URL: https://api.voicelogica.ai
URL: https://api.voicelogica.ai/api/v1/phones/sip-trunks/:id
Auth: API key in header x-api-key

Headers

x-api-keystring required

Your API key for authentication. Required for all endpoints.

x-company-idstring

Optional company ID for resellers. When provided, the API request will operate on behalf of the specified subsidiary company. The API key must have access to the specified company.

Response

SIP trunk retrieved

idstring required

Unique identifier

createdAtstring date-time required

Creation timestamp

activeboolean required

Whether the entity is active

createdBystring required

Name of the user who created the entity

createdByIdstring required

ID of the user who created the entity

modifiedAtstring date-time

ISO 8601 date string

modifiedBystring

Name of the user who last modified the entity

modifiedByIdstring

ID of the user who last modified the entity

companyIdstring required

Company identifier

companyobject

Any valid JSON value

groupIdsstring[]

Linked group IDs

namestring required

Display name for this SIP trunk

hoststring

Remote SIP host, FQDN, or IP

portinteger required

Remote SIP port

transport'udp' | 'tcp' | 'tls' required

SIP transport (udp, tcp, tls)

sipTrunkRole'provider_trunk' | 'remote_pbx_extension' | 'customer_pbx_trunk'

Business role for this SIP trunk

source'system' | 'custom'

Who provisioned this trunk: 'system' (VL free DID) or 'custom' (customer-configured)

provider'msteams'

Managed peer preset ('msteams' = Microsoft Teams Direct Routing; peer fields are server-controlled). The customer pairs <trunkId>.sip.voicelogica.ai as the SBC in their Microsoft tenant.

sipDomainstring

Incoming PBX trunk SIP domain slug; render as <slug>.sip.voicelogica.ai

supportsInboundboolean

Whether this provider trunk can receive inbound calls

supportsOutboundboolean

Whether this provider trunk can originate outbound calls

blockInternationalCallsboolean

When true, outbound calls and transfers on this trunk to explicitly international numbers (+ / 00 prefix) outside Greece and Cyprus are refused

outsideLinePrefixstring

PBX outside-line digit(s) (usually '0'): stripped from inbound caller numbers, added to outbound dialed numbers

inboundAuthType'ip_auth' | 'registration' | 'none' required

Inbound authentication mode

outboundAuthType'registration' | 'ip_auth' | 'none' required

Outbound authentication mode

usernamestring

Outbound SIP username when using registration or digest

passwordstring

Outbound SIP password when using registration or digest

authIdstring

SIP auth ID / login ID for digest authentication

ipWhiteliststring[] required

Trusted static source IPs or CIDR ranges for inbound SIP

allowedRtpIpsstring[]

Additional RTP source IPs (same port) for split-edge media

privateServersstring[]

Admin-only RTP server IPs this trunk must use (empty = public pool)

domainstring

SIP domain / realm

fromDomainstring

From header domain override

outboundProxystring

Outbound SIP proxy if configured

sipProxystring

Alias for outboundProxy; outbound SIP proxy if configured

defaultPhoneNumberstring

Default phone number for this trunk; used in Refer-To for agent/PIN transfers

codecsstring[] required

Allowed codecs for this trunk

enabledboolean required

Whether this trunk is enabled for routing

allowOriginationThroughRemotePbxboolean

Whether remote PBX extension trunks may originate through the remote PBX

staticDestinationHoststring

Static PBX host/IP for IP-auth incoming PBX trunks that do not REGISTER

staticDestinationPortinteger

Static PBX SIP port for IP-auth incoming PBX trunks that do not REGISTER

maxChannelsinteger nullable

Maximum concurrent calls allowed on this trunk (null = unlimited)

pickUpDelayinteger

Seconds the inbound call rings before the AI answers (0 = immediately)

registrationExpiresSecondsinteger

Outbound REGISTER Expires interval (60-86400s)

grantedRegistrationExpiresSecondsinteger

Registrar 423 Min-Expires floor (SIP operational; refresh cadence / wire Expires only — user registrationExpiresSeconds is unchanged)

registrarBindingExpiresSecondsinteger

Registrar 200 Expires header when shorter than we requested (refresh/stale only; never Contact expires countdown)

otherRegistrationsstring[]

Edge trunks: other devices registered on the same carrier account (host:port), per the registrar; they ring too and can answer calls first

registrationRefreshSecondsinteger

Computed REGISTER refresh interval in seconds (read-only; not stored)

srtpEnabledboolean

Whether this trunk offers SDES SRTP on outbound INVITEs (peer can answer with matching crypto or reject with 488 for plain-RTP retry)

registeredboolean required

Whether the trunk is currently registered (maintained by the SIP stack for registration modes)

lastRegisteredAtstring date-time

ISO 8601 date string

lastResolvedPeerIpstring

Last DNS-resolved peer IP (system-written)

Type of destination used by the inbound route

destinationIdstring

Default inbound destination entity id

webhookUrlstring

Pre-answer CALL_INBOUND webhook URL (empty string when auto-disabled after repeated delivery failures)

tunnelType'none' | 'wireguard'

NAT traversal: none or wireguard edge relay

contactHost'phone_id' | 'company_id' | 'ip'

Host in our SIP Contact: phone_id (default), company_id, or ip (only for a proxy that mishandles a hostname). Ignored on edge trunks.

edgeDeviceIdstring

Bound edge device id when tunnelType is wireguard

trunkNumberCountinteger

Total trunk numbers attached to this trunk

inboundTrunkNumberCountinteger

Trunk numbers enabled for inbound routing

outboundCallerIdTrunkNumberCountinteger

Trunk numbers enabled as outbound caller IDs

hasInboundTrunkNumbersboolean

True when this trunk has at least one inbound-enabled trunk number

guidancestring

Connection outcome explanation, returned when the trunk is created

connectionInfostring[]

Key connection values as "label: value" lines (SBC address, SIP domain, platform signaling IP…), returned when the trunk is created

nextStepsstring[]

Kind-specific steps to finish connecting this trunk (e.g. the SBC address to pair for Teams, the SIP domain to point a PBX at), returned when the trunk is created

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "active": true,
  "createdBy": "John Doe",
  "createdById": "123",
  "modifiedAt": "2024-01-15T10:30:00.000Z",
  "modifiedBy": "Jane Doe",
  "modifiedById": "456",
  "companyId": "507f1f77bcf86cd799439012",
  "name": "Carrier A",
  "host": "sip.carrier.example",
  "port": 5060,
  "transport": "udp",
  "sipTrunkRole": "provider_trunk",
  "source": "custom",
  "supportsInbound": true,
  "supportsOutbound": true,
  "inboundAuthType": "ip_auth",
  "outboundAuthType": "registration",
  "username": "user",
  "password": "secret",
  "ipWhitelist": [
    "203.0.113.10"
  ],
  "domain": "carrier.example",
  "sipProxy": "vpbx-sbc.carrier.example",
  "defaultPhoneNumber": "2192192051",
  "codecs": [
    "pcmu",
    "pcma",
    "telephone-event"
  ],
  "enabled": true,
  "allowOriginationThroughRemotePbx": false,
  "registered": true,
  "lastRegisteredAt": "2024-01-15T09:00:00.000Z",
  "registrationExpiresSeconds": 300,
  "registrationRefreshSeconds": 240,
  "destinationType": "ai_agent",
  "destinationId": "507f1f77bcf86cd799439022",
  "trunkNumberCount": 2,
  "inboundTrunkNumberCount": 1,
  "outboundCallerIdTrunkNumberCount": 2,
  "hasInboundTrunkNumbers": true,
  "inboundPeers": []
}

Changes

No recorded changes to this operation across all 2 revisions of this API.