Place an outbound call

Start a call through an assigned Voiceflow or bring-your-own SIP connection.

Endpoint
POST
/v1/sip-connection/{sipConnectionID}/outbound

Authentication

Authorization
string
header
required

A Voiceflow API key authorized for project:READ and project.versions:READ on the connection's assigned agent. Keep the key server-side. SIP digest credentials and Socket.IO session keys do not authorize this request.

Path parameters

sipConnectionID
string
required

The connection ID shown by Outbound call API in Creator. This is not the connection's SIP hostname or an agent ID.

Request body

to
string
required

A valid phone number in E.164 format. Bring your own SIP also accepts a digits-only PBX extension of 1–15 digits; Voiceflow SIP does not. Arbitrary SIP URIs are not accepted here.

Minimum length: 1

Response

200

Dial request accepted. Empty response body.

Error 400

Invalid destination; connection not assigned; outbound settings incomplete; or connection not ready for outbound calls. Check the destination and saved connection settings before retrying.

Error 402

Workspace credit limit reached.

Error 404

SIP connection not found.

Error 429

Production concurrency limit reached. Wait for capacity before retrying.

Credentials

Call from a trusted server using a Voiceflow API key authorized for project:READ and project.versions:READ on the assigned agent. Do not send the SIP username/password or a Socket.IO session key as HTTP authorization. See API authentication.

Destination and connection requirements

The connection must be assigned and have outbound routing and Caller ID configured. to does not accept an arbitrary SIP URI. The operation has no request fields for variables, custom headers, Environment overrides, batch calling or a client-supplied idempotency key.

Interpret the result

HTTP 200 has an empty body. It confirms the dial request was accepted, not that the destination answered, that a transfer succeeded, or that a conversation completed. No call ID is returned.

An ambiguous timeout can occur after a dial was accepted. Check your provider’s call records before retrying; an automatic retry can place another call.

Test the configured connection

In Creator, open Phone numbers → Outbound call API → View for the configured connection. Copy the connection-specific URL, or use Test call → Call with a destination you control. This starts a real call through the selected trunk.

The Request frame above shows the equivalent server-side call. Keep the sipConnectionID from the URL separate from the SIP hostname used for inbound routing.

Recover from a failed request

The operation’s response list above covers source-defined 400, 402, 404 and 429 conditions. Resolve authentication failures by checking the API key and assigned-project permissions. For a 400, distinguish invalid destination, missing assignment, incomplete outbound settings and connection provisioning before retrying. See SIP troubleshooting.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.