Skip to main content
POST
/
v1
/
calls
/
phone
Start a new phone call
curl --request POST \
  --url https://api.callrounded.com/v1/calls/phone \
  --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": {
    "active": true,
    "age": 35,
    "appointment_date": "2023-05-15T14:30:00Z",
    "first_name": "John",
    "last_name": "Doe",
    "opening_hours": {
      "monday": [
        {
          "end": "17:00",
          "start": "07:00"
        }
      ]
    }
  },
  "custom_headers": {
    "From": "Anonymous <sip:[email protected]>;tag=3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "X-Custom-Header": "value"
  }
}
'
{
  "data": {
    "call_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "message": "Phone call started successfully",
  "status": 201
}

Authorizations

​
X-Api-Key
string
header
required

The API Key created in Rounded Studio.

Body

application/json
​
from_number
string
required

Phone number emitting the call, in E.164 format. It must be a phone number from your Rounded organization.

Minimum string length: 8
​
to_number
string
required

Phone number receiving the call, in E.164 format.

Minimum string length: 8
​
agent_id
string<uuid>
required

Id of the agent making the call. You can get the id from your agent's config page URL, e.g. https://app.callrounded.com/agents/411b82c8-462a-4e1b-89bc-10ab3ce1ed29.

​
dynamic_variables_values
Dynamic Variables Values · object

Values for the variables that should be initialized before call starts, provided as a JSON object. Values can be strings, numbers, booleans, or nested JSON objects.

Example:
{
  "active": true,
  "age": 35,
  "appointment_date": "2023-05-15T14:30:00Z",
  "first_name": "John",
  "last_name": "Doe",
  "opening_hours": {
    "monday": [{ "end": "17:00", "start": "07:00" }]
  }
}
​
custom_headers
Custom Headers · object

If SIP is used, the custom headers will be forwarded to the configured trunk provider when sending the INVITE request to start the call. If more control is needed, it's also possible to override default headers like From, To, P-Asserted-Identity, etc.

Example:
{
  "From": "Anonymous <sip:[email protected]>;tag=3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "X-Custom-Header": "value"
}

Response

Successfully started phone call

​
message
string
required
​
data
PhoneCallCreateApiResponseData · 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