Skip to navigation
API ReferenceConversations

Sip Outbound Call

Places an outbound voice-agent phone call through the user’s SIP trunk using the supplied SIP credentials, caller ID, destination phone number, and conversation configuration. Use only when the user requests a call to that recipient and is authorized to use the trunk and caller ID. With dry_run omitted or false, this contacts the recipient and may incur telephony charges; repeating a successful request may place another call. Set dry_run to true to validate setup without placing a call. A dry run does not verify that the recipient can be reached or test call audio.

Authentication

AuthorizationBearer

Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.

Headers

X-Sip-AddressstringRequired
SIP address of the user's SIP trunk. Required.
X-Sip-Auth-UsernamestringOptional
SIP auth username, if your provider requires it.
X-Sip-Auth-PasswordstringOptional
SIP auth password, if your provider requires it.

Request

This endpoint expects an object.
from_phone_numberstringRequired
Caller ID phone number in E.164 format.
to_phone_numberstringRequired
Destination phone number in E.164 format.
from_display_namestringOptional<=256 characters

Display name for the caller ID (the SIP From header) on this call. Sent only when non-empty. Whether it reaches the callee depends on your SIP carrier - carriers that forward the From display name (e.g. Telnyx) present it, while others (e.g. Twilio) drop it or override it with a CNAM lookup.

configobjectOptional

When an agent is provided, these config options override the agent settings.

dry_runbooleanOptionalDefaults to false

If true, validates the outbound call setup without placing a call. Returns HTTP 200 with conversation_id and twilio_call_sid set to null.

sipobjectOptional
SIP trunk settings for the outbound trunk created for this call.

Response

Success response
SipOutboundDryRunResponseobject
OR
SipOutboundCallInitiatedResponseobject

Errors

400
Bad Request Error
401
Unauthorized Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error