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": "+33912345678",
  "to_number": "+33612345678",
  "agent_id": "411b82c8-462a-4e1b-89bc-10ab3ce1ed29",
  "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:anonymous@example.com>;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 length: 8
Examples:

"+33912345678"

​
to_number
string
required

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

Minimum length: 8
Examples:

"+33612345678"

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

Examples:

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

​
dynamic_variables_values
object | null

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.

Examples:
{
  "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
object | null

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.

Examples:
{
  "From": "Anonymous <sip:anonymous@example.com>;tag=3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "X-Custom-Header": "value"
}

Response

Successfully started phone call

​
message
string
required
​
data
object
required
​
error
object | null
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