IllyVoIPdevelopers

Voice API

Execute action chain

Runs a sequence of live call actions in one request.

Try in API Playground ↗Sign in to prepare and run this request.
POST/api/v1/voice/call-control/execute

Before you start

Build an ordered action list for an existing call-control session.

Result

Inspect every action result; do not assume all actions completed because the request was accepted.

Charges and safe retries

Actions may play speech, collect input or alter a live call. Review each action and its billing rules.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X POST "https://api.illyvoip.com/api/v1/voice/call-control/execute" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}" \
  -H "Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_control_id": "YOUR_CALL_CONTROL_ID",
    "vars": {
        "customer": "Acme"
    },
    "actions": [
        {
            "type": "speak",
            "text": "Hello {{vars.customer}}."
        },
        {
            "type": "gather",
            "input": "speech",
            "prompt_text": "Tell me your account number.",
            "speech_language": "en-US",
            "timeout_ms": 8000,
            "save_as": "account"
        }
    ]
}'

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/voice/call-control/execute", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY,
    "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_KEY",
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "call_control_id": "YOUR_CALL_CONTROL_ID",
    "vars": {
        "customer": "Acme"
    },
    "actions": [
        {
            "type": "speak",
            "text": "Hello {{vars.customer}}."
        },
        {
            "type": "gather",
            "input": "speech",
            "prompt_text": "Tell me your account number.",
            "speech_language": "en-US",
            "timeout_ms": 8000,
            "save_as": "account"
        }
    ]
})
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/voice/call-control/execute');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY'),
        'Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => '{
    "call_control_id": "YOUR_CALL_CONTROL_ID",
    "vars": {
        "customer": "Acme"
    },
    "actions": [
        {
            "type": "speak",
            "text": "Hello {{vars.customer}}."
        },
        {
            "type": "gather",
            "input": "speech",
            "prompt_text": "Tell me your account number.",
            "speech_language": "en-US",
            "timeout_ms": 8000,
            "save_as": "account"
        }
    ]
}',
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "POST",
    "https://api.illyvoip.com/api/v1/voice/call-control/execute",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"],
        "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_KEY",
        'Content-Type': 'application/json'
    },
    json=json.loads("{\n    \"call_control_id\": \"YOUR_CALL_CONTROL_ID\",\n    \"vars\": {\n        \"customer\": \"Acme\"\n    },\n    \"actions\": [\n        {\n            \"type\": \"speak\",\n            \"text\": \"Hello {{vars.customer}}.\"\n        },\n        {\n            \"type\": \"gather\",\n            \"input\": \"speech\",\n            \"prompt_text\": \"Tell me your account number.\",\n            \"speech_language\": \"en-US\",\n            \"timeout_ms\": 8000,\n            \"save_as\": \"account\"\n        }\n    ]\n}"),
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request parameters

Header parameters

Idempotency-Keystringrequired

Unique retry key for this mutation. Reuse the same key only when retrying the same request.

minLength 8maxLength 128

Request body

application/json

Body required.

call_control_idstringrequired

Session ID from the create endpoint.

nullable false
varsobjectoptional
actionsarray<object>required

Ordered list of actions.

View nested fields

Array items

typestringrequired
enum ["playback", "speak", "gather", "wait", "hold", "unhold", "dtmf", "status", "transfer", "hangup"]
save_asstringoptional

Optional variable name for the action result.

save_fieldstringoptional

Optional response field to save.

Additional properties: allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "call_control_id": {
      "type": "string",
      "nullable": false,
      "description": "Session ID from the create endpoint."
    },
    "vars": {
      "type": "object",
      "additionalProperties": {}
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "type"
        ],
        "additionalProperties": true,
        "description": "Use the parameters documented for the selected individual call-control action. Action-specific required fields are validated by that endpoint.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "playback",
              "speak",
              "gather",
              "wait",
              "hold",
              "unhold",
              "dtmf",
              "status",
              "transfer",
              "hangup"
            ]
          },
          "save_as": {
            "type": "string",
            "description": "Optional variable name for the action result."
          },
          "save_field": {
            "type": "string",
            "description": "Optional response field to save."
          }
        }
      },
      "description": "Ordered list of actions."
    }
  },
  "required": [
    "call_control_id",
    "actions"
  ]
}
Example body
JSON
{
  "call_control_id": "vapi_760da5ee5a3c8b70777bae20fbda",
  "vars": {
    "customer": "Acme"
  },
  "actions": [
    {
      "type": "speak",
      "text": "Hello {{vars.customer}}."
    },
    {
      "type": "gather",
      "input": "speech",
      "prompt_text": "Tell me your account number.",
      "speech_language": "en-US",
      "timeout_ms": 8000,
      "save_as": "account"
    }
  ]
}

Request behavior

Use this for chained speak → gather → speak flows without round-tripping between each action. The response includes call_control_id, results and vars. Each result includes type, ok and the response fields of that action; an unsuccessful action includes error.

Inspect the batch status and each result even after HTTP 200. Charge objects may be null when no charge applies. An Idempotency-Key header is required; reuse the same key only for an identical request.

A selected text action may return voice_content_review_required with fields.review_reference. Open Communication reviews in your account to explain the activity. This stops later actions even when stop_on_error is false.

Earlier completed actions remain completed; the rejected text action is not charged or played. Repeating the same key returns the same result, not another attempt.

Conditions and examples

Idempotency-Key is required. It safely replays a completed identical batch; changing the request while reusing the key returns a conflict.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • call_control_id: Control session reference returned by Create or Answer; use it for subsequent live actions.
  • results: Per-action results in the submitted action chain; inspect each result.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Batch response. Inspect status and each action result; a stopped batch may return status error.

application/json

JSON
{
  "status": "success",
  "call_control_id": "vapi_760da5ee5a3c8b70777bae20fbda",
  "results": [
    {
      "type": "speak",
      "ok": true,
      "status": "success",
      "call_control_id": "vapi_760da5ee5a3c8b70777bae20fbda",
      "media": "vcm2.OPAQUE_CALL_SCOPED_MEDIA_REFERENCE",
      "tts_charge": null
    },
    {
      "type": "gather",
      "ok": true,
      "status": "success",
      "call_control_id": "vapi_760da5ee5a3c8b70777bae20fbda",
      "input": "speech",
      "transcript": "123456",
      "tts_charge": null,
      "stt_charge": null
    }
  ],
  "vars": {
    "customer": "Acme",
    "account": "123456"
  }
}
statusstringrequired
enum ["success", "error"]
call_control_idstringrequired
nullable false
resultsarray<value>required
View nested fields

Array items

oneOf schema alternatives

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
mediastringrequired

Opaque, short-lived media reference valid only for this account and call.

typestringrequired
enum ["playback"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
mediastringrequired

Opaque, short-lived media reference valid only for this account and call.

tts_chargeobjectrequired
nullable true
View nested fields
transaction_idstringrequired

Public transaction reference matching your ledger, or null when no balance movement exists.

nullable truepattern "^TX-[A-F0-9]{12,24}$"
productstringrequired
charactersintegerrequired
rate_per_char_eurnumberrequired
amount_eurnumberrequired

Additional properties: not allowed.

typestringrequired
enum ["speak"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
inputstringrequired
enum ["speech", "dtmf"]
transcriptstringoptional
tts_chargeobjectrequired
nullable true
View nested fields
transaction_idstringrequired

Public transaction reference matching your ledger, or null when no balance movement exists.

nullable truepattern "^TX-[A-F0-9]{12,24}$"
productstringrequired
charactersintegerrequired
rate_per_char_eurnumberrequired
amount_eurnumberrequired

Additional properties: not allowed.

stt_chargeobjectoptional
nullable true
View nested fields
transaction_idstringrequired

Public transaction reference matching your ledger, or null when no balance movement exists.

nullable truepattern "^TX-[A-F0-9]{12,24}$"
productstringrequired
duration_secondsintegerrequired
billed_minutesintegerrequired
rate_per_min_eurnumberrequired
amount_eurnumberrequired

Additional properties: not allowed.

digitsstringoptional

Captured keypad digits for input dtmf.

typestringrequired
enum ["gather"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
secondsintegerrequired
typestringrequired
enum ["wait"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
music_classstringrequired
nullable true
typestringrequired
enum ["hold"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
typestringrequired
enum ["unhold"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
digitsstringrequired
typestringrequired
enum ["dtmf"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired

Public call reference used for subsequent control requests.

nullable false
statestringrequired
call_statusstringrequired
terminalbooleanrequired
tostringrequired
fromstringrequired
created_atstringrequired
format "date-time"nullable true
answered_atstringrequired
format "date-time"nullable true
ended_atstringrequired
format "date-time"nullable true
failure_reasonstringrequired

A safe customer-facing explanation for a failed call, or null.

nullable true
typestringrequired
enum ["status"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
transfer_idstringrequired
transferobjectrequired
View nested fields
statestringrequired
messagestringrequired
target_typestringrequired
target_valuestringrequired
can_cancelbooleanrequired

Additional properties: not allowed.

typestringrequired
enum ["transfer"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

statusstringrequired
enum ["success"]
call_control_idstringrequired
nullable false
messagestringrequired
terminated_channelsintegerrequired
idempotentbooleanoptional

Present when the call was already confirmed ended.

typestringrequired
enum ["hangup"]
okbooleanrequired
enum [true]

Additional properties: not allowed.

typestringrequired
enum ["playback", "speak", "gather", "wait", "hold", "unhold", "dtmf", "status", "transfer", "hangup"]
okbooleanrequired
enum [false]
errorstringrequired
error_codestringoptional
fieldsobjectoptional
View nested fields
review_referencestringoptional

Additional properties: not allowed.

Additional properties: not allowed.

varsvaluerequired

Saved named variables; an empty PHP collection may be returned as an empty array.

View nested fields

oneOf schema alternatives

Type: object

Array items

Type: value

errorstringoptional
error_codestringoptional
fieldsobjectoptional
View nested fields
review_referencestringoptional

Additional properties: not allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "call_control_id": {
      "type": "string",
      "nullable": false
    },
    "results": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "media": {
                "type": "string",
                "description": "Opaque, short-lived media reference valid only for this account and call."
              },
              "type": {
                "type": "string",
                "enum": [
                  "playback"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "media",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "media": {
                "type": "string",
                "description": "Opaque, short-lived media reference valid only for this account and call."
              },
              "tts_charge": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "transaction_id": {
                    "type": "string",
                    "nullable": true,
                    "pattern": "^TX-[A-F0-9]{12,24}$",
                    "description": "Public transaction reference matching your ledger, or null when no balance movement exists."
                  },
                  "product": {
                    "type": "string"
                  },
                  "characters": {
                    "type": "integer"
                  },
                  "rate_per_char_eur": {
                    "type": "number"
                  },
                  "amount_eur": {
                    "type": "number"
                  }
                },
                "required": [
                  "transaction_id",
                  "product",
                  "characters",
                  "rate_per_char_eur",
                  "amount_eur"
                ],
                "nullable": true
              },
              "type": {
                "type": "string",
                "enum": [
                  "speak"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "media",
              "tts_charge",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "input": {
                "type": "string",
                "enum": [
                  "speech",
                  "dtmf"
                ]
              },
              "transcript": {
                "type": "string"
              },
              "tts_charge": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "transaction_id": {
                    "type": "string",
                    "nullable": true,
                    "pattern": "^TX-[A-F0-9]{12,24}$",
                    "description": "Public transaction reference matching your ledger, or null when no balance movement exists."
                  },
                  "product": {
                    "type": "string"
                  },
                  "characters": {
                    "type": "integer"
                  },
                  "rate_per_char_eur": {
                    "type": "number"
                  },
                  "amount_eur": {
                    "type": "number"
                  }
                },
                "required": [
                  "transaction_id",
                  "product",
                  "characters",
                  "rate_per_char_eur",
                  "amount_eur"
                ],
                "nullable": true
              },
              "stt_charge": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "transaction_id": {
                    "type": "string",
                    "nullable": true,
                    "pattern": "^TX-[A-F0-9]{12,24}$",
                    "description": "Public transaction reference matching your ledger, or null when no balance movement exists."
                  },
                  "product": {
                    "type": "string"
                  },
                  "duration_seconds": {
                    "type": "integer"
                  },
                  "billed_minutes": {
                    "type": "integer"
                  },
                  "rate_per_min_eur": {
                    "type": "number"
                  },
                  "amount_eur": {
                    "type": "number"
                  }
                },
                "required": [
                  "transaction_id",
                  "product",
                  "duration_seconds",
                  "billed_minutes",
                  "rate_per_min_eur",
                  "amount_eur"
                ],
                "nullable": true
              },
              "digits": {
                "type": "string",
                "description": "Captured keypad digits for input dtmf."
              },
              "type": {
                "type": "string",
                "enum": [
                  "gather"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "input",
              "tts_charge",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "seconds": {
                "type": "integer"
              },
              "type": {
                "type": "string",
                "enum": [
                  "wait"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "seconds",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "music_class": {
                "type": "string",
                "nullable": true
              },
              "type": {
                "type": "string",
                "enum": [
                  "hold"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "music_class",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "type": {
                "type": "string",
                "enum": [
                  "unhold"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "digits": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "dtmf"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "digits",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false,
                "description": "Public call reference used for subsequent control requests."
              },
              "state": {
                "type": "string"
              },
              "call_status": {
                "type": "string"
              },
              "terminal": {
                "type": "boolean"
              },
              "to": {
                "type": "string"
              },
              "from": {
                "type": "string"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "answered_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "ended_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "failure_reason": {
                "type": "string",
                "nullable": true,
                "description": "A safe customer-facing explanation for a failed call, or null."
              },
              "type": {
                "type": "string",
                "enum": [
                  "status"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "state",
              "call_status",
              "terminal",
              "to",
              "from",
              "created_at",
              "answered_at",
              "ended_at",
              "failure_reason",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "transfer_id": {
                "type": "string"
              },
              "transfer": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "state": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "target_type": {
                    "type": "string"
                  },
                  "target_value": {
                    "type": "string"
                  },
                  "can_cancel": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "state",
                  "message",
                  "target_type",
                  "target_value",
                  "can_cancel"
                ]
              },
              "type": {
                "type": "string",
                "enum": [
                  "transfer"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "transfer_id",
              "transfer",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ]
              },
              "call_control_id": {
                "type": "string",
                "nullable": false
              },
              "message": {
                "type": "string"
              },
              "terminated_channels": {
                "type": "integer"
              },
              "idempotent": {
                "type": "boolean",
                "description": "Present when the call was already confirmed ended."
              },
              "type": {
                "type": "string",
                "enum": [
                  "hangup"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "status",
              "call_control_id",
              "message",
              "terminated_channels",
              "type",
              "ok"
            ]
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "type",
              "ok",
              "error"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "playback",
                  "speak",
                  "gather",
                  "wait",
                  "hold",
                  "unhold",
                  "dtmf",
                  "status",
                  "transfer",
                  "hangup"
                ]
              },
              "ok": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "error": {
                "type": "string"
              },
              "error_code": {
                "type": "string"
              },
              "fields": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "review_reference": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      }
    },
    "vars": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": {}
        },
        {
          "type": "array",
          "maxItems": 0,
          "items": {}
        }
      ],
      "description": "Saved named variables; an empty PHP collection may be returned as an empty array."
    },
    "error": {
      "type": "string"
    },
    "error_code": {
      "type": "string"
    },
    "fields": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "review_reference": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "call_control_id",
    "results",
    "vars"
  ]
}
400 The request failed validation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key or browser token is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
402 The account has insufficient available credit.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account is not allowed to perform this operation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
404 The requested owned resource was not found.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
409 The request conflicts with the current resource or operation state.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected service error occurred.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 The service is temporarily unavailable.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable, insufficient-credit, idempotency-conflict

Try this operation in Sandbox · Environment setup and limitations

List active callsGet Voice API statusCreate callAnswer inbound Voice API callPlay audioSpeak textGather DTMF or speechGet call statusWaitTransfer callGet transfer statusCancel transferHold callUnhold callSend DTMFEnd call

Search API operations, parameters, SDK and webhooks.