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": "<string>",
  "to_number": "<string>",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dynamic_variables_values": {}
}
'

import requests

url = "https://api.callrounded.com/v1/calls/stage"

payload = {
    "from_number": "<string>",
    "to_number": "<string>",
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "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: '<string>',
    to_number: '<string>',
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    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' => '<string>',
    'to_number' => '<string>',
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    '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\": \"<string>\",\n  \"to_number\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\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\": \"<string>\",\n  \"to_number\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\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\": \"<string>\",\n  \"to_number\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\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

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": "<string>",
  "to_number": "<string>",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dynamic_variables_values": {}
}
'

import requests

url = "https://api.callrounded.com/v1/calls/stage"

payload = {
    "from_number": "<string>",
    "to_number": "<string>",
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "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: '<string>',
    to_number: '<string>',
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    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' => '<string>',
    'to_number' => '<string>',
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    '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\": \"<string>\",\n  \"to_number\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\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\": \"<string>\",\n  \"to_number\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\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\": \"<string>\",\n  \"to_number\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\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

X-Api-Key

string

header

required

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

sync

boolean

default:false

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.

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"

dynamic_variables_values

Dynamic Variables Values · object | null

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

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 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

Show child attributes

error

ApiResponseError · object | null

Show child attributes

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

calls

knowledge bases

agents

phone-numbers

post-call-questions

Stage an inbound SIP call

Authorizations

Query Parameters

Body

Response