Stage an inbound 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": "+33912345678",
"to_number": "+33612345678",
"agent_id": "411b82c8-462a-4e1b-89bc-10ab3ce1ed29",
"dynamic_variables_values": {}
}
'import requests
url = "https://api.callrounded.com/v1/calls/stage"
payload = {
"from_number": "+33912345678",
"to_number": "+33612345678",
"agent_id": "411b82c8-462a-4e1b-89bc-10ab3ce1ed29",
"dynamic_variables_values": {}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
from_number: '+33912345678',
to_number: '+33612345678',
agent_id: '411b82c8-462a-4e1b-89bc-10ab3ce1ed29',
dynamic_variables_values: {}
})
};
fetch('https://api.callrounded.com/v1/calls/stage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.callrounded.com/v1/calls/stage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from_number' => '+33912345678',
'to_number' => '+33612345678',
'agent_id' => '411b82c8-462a-4e1b-89bc-10ab3ce1ed29',
'dynamic_variables_values' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.callrounded.com/v1/calls/stage"
payload := strings.NewReader("{\n \"from_number\": \"+33912345678\",\n \"to_number\": \"+33612345678\",\n \"agent_id\": \"411b82c8-462a-4e1b-89bc-10ab3ce1ed29\",\n \"dynamic_variables_values\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.callrounded.com/v1/calls/stage")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"from_number\": \"+33912345678\",\n \"to_number\": \"+33612345678\",\n \"agent_id\": \"411b82c8-462a-4e1b-89bc-10ab3ce1ed29\",\n \"dynamic_variables_values\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.callrounded.com/v1/calls/stage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from_number\": \"+33912345678\",\n \"to_number\": \"+33612345678\",\n \"agent_id\": \"411b82c8-462a-4e1b-89bc-10ab3ce1ed29\",\n \"dynamic_variables_values\": {}\n}"
response = http.request(request)
puts response.read_body{
"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
}calls
Stage an inbound SIP call
Pre-initialize a call (agent configuration, variables initialization, and resources) before an inbound SIP call arrives, reducing cold-start latency to near zero.
Async: Returns the call_id immediately. Poll GET /v1/calls/{call_id} and wait for the status to become staged before triggering the SIP call.
Sync: Blocks until the call is ready (status staged) or a timeout occurs (HTTP 408).
Once staged, trigger the inbound SIP call with the header:
X-Rounded-Call-Id: {call_id}
This ensures the call is routed to the staged agent.
Call status flow: initiated → staged → ringing → in_progress → completed
If no SIP call arrives within the staging timeout (60s), the call is marked no_answer and cleaned up.
Tip: If your agent uses Call context: Variables initialization to load data when processing a call, prefer using this endpoint to prepare it beforehand.
POST
/
v1
/
calls
/
stage
Stage an inbound 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": "+33912345678",
"to_number": "+33612345678",
"agent_id": "411b82c8-462a-4e1b-89bc-10ab3ce1ed29",
"dynamic_variables_values": {}
}
'import requests
url = "https://api.callrounded.com/v1/calls/stage"
payload = {
"from_number": "+33912345678",
"to_number": "+33612345678",
"agent_id": "411b82c8-462a-4e1b-89bc-10ab3ce1ed29",
"dynamic_variables_values": {}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
from_number: '+33912345678',
to_number: '+33612345678',
agent_id: '411b82c8-462a-4e1b-89bc-10ab3ce1ed29',
dynamic_variables_values: {}
})
};
fetch('https://api.callrounded.com/v1/calls/stage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.callrounded.com/v1/calls/stage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from_number' => '+33912345678',
'to_number' => '+33612345678',
'agent_id' => '411b82c8-462a-4e1b-89bc-10ab3ce1ed29',
'dynamic_variables_values' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.callrounded.com/v1/calls/stage"
payload := strings.NewReader("{\n \"from_number\": \"+33912345678\",\n \"to_number\": \"+33612345678\",\n \"agent_id\": \"411b82c8-462a-4e1b-89bc-10ab3ce1ed29\",\n \"dynamic_variables_values\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.callrounded.com/v1/calls/stage")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"from_number\": \"+33912345678\",\n \"to_number\": \"+33612345678\",\n \"agent_id\": \"411b82c8-462a-4e1b-89bc-10ab3ce1ed29\",\n \"dynamic_variables_values\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.callrounded.com/v1/calls/stage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from_number\": \"+33912345678\",\n \"to_number\": \"+33612345678\",\n \"agent_id\": \"411b82c8-462a-4e1b-89bc-10ab3ce1ed29\",\n \"dynamic_variables_values\": {}\n}"
response = http.request(request)
puts response.read_body{
"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
The API Key created in Rounded Studio.
- You can create it by going to the "API Keys" settings of your profile.
- Need help? You can email us at team@callrounded.com or join our Discord community.
Query Parameters
If true, block until the call is ready (status 'staged') or timeout.
Body
application/json
Request body for staging an inbound SIP call.
This endpoint is only supported for inbound calls. Staging pre-initializes the call (agent configuration, variables, and resources) before the actual inbound 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.
The caller's phone number in E.164 format.
Example:
"+33912345678"
The destination phone number in E.164 format.
Example:
"+33612345678"
The ID of the agent that will handle the call.
Example:
"411b82c8-462a-4e1b-89bc-10ab3ce1ed29"
Initial variable values to inject into the agent conversation before it starts.
Show child attributes
Show child attributes
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 becomesstaged(call ready). - Pass as the
X-Rounded-Call-IdSIP header value when triggering the inbound call.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
{
"details": [
{
"field": "email",
"message": "Invalid email format"
}
],
"message": "An error occurred while processing your request",
"status": 400,
"type": "generic_error"
}