Skip to main content
POST
/
v1
/
calls
/
stage
Stage a SIP call
curl --request POST \
  --url https://api.callrounded.com/v1/calls/stage \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "from_number": "<string>",
  "to_number": "<string>",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "direction": "inbound",
  "dynamic_variables_values": {},
  "custom_headers": {}
}
'
{
  "message": "<string>",
  "data": {
    "call_id": "<string>"
  },
  "error": {
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "message": "An error occurred while processing your request",
    "status": 400,
    "type": "generic_error"
  },
  "status": 201
}

Authorizations

​
X-Api-Key
string
header
required

The API Key created in Rounded Studio.

Query Parameters

​
sync
boolean
default:false

If true, block until the call is ready (status 'staged') or timeout.

Body

application/json

Staging pre-initializes the call (agent configuration, variables, and resources) before the actual SIP call arrives, reducing cold-start latency to near zero.

Once staged, the inbound SIP call must include the header X-Rounded-Call-Id: <call_id> so it is routed to the staged call.

​
from_number
string
required

The caller's phone number in E.164 format.

Example:

"+33912345678"

​
to_number
string
required

The destination phone number in E.164 format.

Example:

"+33612345678"

​
agent_id
string<uuid>
required

The ID of the agent that will handle the call.

Example:

"411b82c8-462a-4e1b-89bc-10ab3ce1ed29"

​
direction
enum<string>
default:inbound

The call direction. Use 'inbound' for pre-warmed inbound calls.

Available options:
inbound,
outbound
​
dynamic_variables_values
Dynamic Variables Values · object

Initial variable values to inject into the agent conversation before it starts.

​
custom_headers
Custom Headers · object

Custom SIP headers to include when the call is established (key-value pairs).

Response

Call staging initiated (async) or call staged and ready (sync)

Response from staging a SIP call.

The call_id is used to:

  • Poll GET /v1/calls/{call_id} to check when the status becomes staged (call ready).
  • Pass as the X-Rounded-Call-Id SIP header value when triggering the inbound call.
​
message
string
required
​
data
StageSipCallApiResponseData · object
required
​
error
ApiResponseError · object
Example:
{
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "message": "An error occurred while processing your request",
  "status": 400,
  "type": "generic_error"
}
​
status
integer
default:201