IVR Flows

Push a lead (place an IVR call)

Places one outbound call that runs the published version of the flow, with data as the lead. Calls go out on your VoiceLink connection. The call is placed asynchronously: a 202 means it was accepted, not that it was answered. When the flow has Fetch blocks right after Start, they run before dialing; if one fails the number is never dialed and the call ends as failed with ivr.failure = "prefetch_failed" on session.completed. Track the call with call.status.updated webhooks or GET /calls/{id}, and read the result from the ivr block of session.completed.

Rate limited per account with the same per-minute call quota as POST /calls/start, and counted against the same concurrent call limit. A call needs enough balance for one minute at your IVR price for the voice model of the flow’s published version (Standard or Premium) to start; it is billed per pulse of answered time at that price.

POST

ivr-flows

{flowId}

calls

Push a lead (place an IVR call)

curl --request POST \
  --url https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+919876543210",
  "data": {
    "loan_id": "L-88231",
    "amount_due": 30000,
    "due_date": "2026-06-04"
  },
  "client_reference_id": "lead-88231-attempt-1"
}
'

import requests

url = "https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls"

payload = {
    "to": "+919876543210",
    "data": {
        "loan_id": "L-88231",
        "amount_due": 30000,
        "due_date": "2026-06-04"
    },
    "client_reference_id": "lead-88231-attempt-1"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to: '+919876543210',
    data: {loan_id: 'L-88231', amount_due: 30000, due_date: '2026-06-04'},
    client_reference_id: 'lead-88231-attempt-1'
  })
};

fetch('https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls', 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.vocobase.com/api/v2/ivr-flows/{flowId}/calls",
  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([
    'to' => '+919876543210',
    'data' => [
        'loan_id' => 'L-88231',
        'amount_due' => 30000,
        'due_date' => '2026-06-04'
    ],
    'client_reference_id' => 'lead-88231-attempt-1'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.vocobase.com/api/v2/ivr-flows/{flowId}/calls"

	payload := strings.NewReader("{\n  \"to\": \"+919876543210\",\n  \"data\": {\n    \"loan_id\": \"L-88231\",\n    \"amount_due\": 30000,\n    \"due_date\": \"2026-06-04\"\n  },\n  \"client_reference_id\": \"lead-88231-attempt-1\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.vocobase.com/api/v2/ivr-flows/{flowId}/calls")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": \"+919876543210\",\n  \"data\": {\n    \"loan_id\": \"L-88231\",\n    \"amount_due\": 30000,\n    \"due_date\": \"2026-06-04\"\n  },\n  \"client_reference_id\": \"lead-88231-attempt-1\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to\": \"+919876543210\",\n  \"data\": {\n    \"loan_id\": \"L-88231\",\n    \"amount_due\": 30000,\n    \"due_date\": \"2026-06-04\"\n  },\n  \"client_reference_id\": \"lead-88231-attempt-1\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "completed",
    "from_number": "+917969008446",
    "to_number": "+919876543210",
    "flow_id": "f1234567-abcd-1234-abcd-123456789012",
    "client_reference_id": "lead-88231-attempt-1",
    "idempotent_replay": true
  }
}

Authorizations

Authorization

string

header

required

API key in format: rg_live_xxxx. Pass as a Bearer token in the Authorization header.

Path Parameters

flowId

string<uuid>

required

IVR flow ID, from GET /ivr-flows or the flow page in the dashboard.

Body

application/json

string

required

Destination phone number in E.164 format.

Example:

"+919876543210"

from

string

Optional caller ID in E.164 format. Must be an active phone number on the selected VoiceLink connection; an unknown number returns 400 VALIDATION_ERROR. When omitted, the connection default is used.

Example:

"+917969008446"

connection_id

string<uuid>

VoiceLink connection to place the call on. Required when the account has more than one active VoiceLink connection.

data

object

Lead values, keyed by the field names from GET /ivr-flows/{flowId}. Every required field must be present and non-empty; keys the flow does not declare are refused. See IvrLeadField.type for how each type must be sent.

Example:

{
  "loan_id": "L-88231",
  "amount_due": 30000,
  "due_date": "2026-06-04"
}

client_reference_id

string

Your idempotency key, at most 128 characters. A repeat returns the original call with idempotent_replay: true and places no new call. The key space is shared with POST /calls/start on the same account.

Maximum string length: 128

Example:

"lead-88231-attempt-1"

Response

Replay: this client_reference_id was used before. The original call is returned and no new call is placed.

success

boolean

data

object

The call originally created with this client_reference_id.

Show child attributes

Push a lead (place an IVR call)

curl --request POST \
  --url https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+919876543210",
  "data": {
    "loan_id": "L-88231",
    "amount_due": 30000,
    "due_date": "2026-06-04"
  },
  "client_reference_id": "lead-88231-attempt-1"
}
'

import requests

url = "https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls"

payload = {
    "to": "+919876543210",
    "data": {
        "loan_id": "L-88231",
        "amount_due": 30000,
        "due_date": "2026-06-04"
    },
    "client_reference_id": "lead-88231-attempt-1"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to: '+919876543210',
    data: {loan_id: 'L-88231', amount_due: 30000, due_date: '2026-06-04'},
    client_reference_id: 'lead-88231-attempt-1'
  })
};

fetch('https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls', 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.vocobase.com/api/v2/ivr-flows/{flowId}/calls",
  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([
    'to' => '+919876543210',
    'data' => [
        'loan_id' => 'L-88231',
        'amount_due' => 30000,
        'due_date' => '2026-06-04'
    ],
    'client_reference_id' => 'lead-88231-attempt-1'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.vocobase.com/api/v2/ivr-flows/{flowId}/calls"

	payload := strings.NewReader("{\n  \"to\": \"+919876543210\",\n  \"data\": {\n    \"loan_id\": \"L-88231\",\n    \"amount_due\": 30000,\n    \"due_date\": \"2026-06-04\"\n  },\n  \"client_reference_id\": \"lead-88231-attempt-1\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.vocobase.com/api/v2/ivr-flows/{flowId}/calls")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": \"+919876543210\",\n  \"data\": {\n    \"loan_id\": \"L-88231\",\n    \"amount_due\": 30000,\n    \"due_date\": \"2026-06-04\"\n  },\n  \"client_reference_id\": \"lead-88231-attempt-1\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocobase.com/api/v2/ivr-flows/{flowId}/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to\": \"+919876543210\",\n  \"data\": {\n    \"loan_id\": \"L-88231\",\n    \"amount_due\": 30000,\n    \"due_date\": \"2026-06-04\"\n  },\n  \"client_reference_id\": \"lead-88231-attempt-1\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "completed",
    "from_number": "+917969008446",
    "to_number": "+919876543210",
    "flow_id": "f1234567-abcd-1234-abcd-123456789012",
    "client_reference_id": "lead-88231-attempt-1",
    "idempotent_replay": true
  }
}

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Push a lead (place an IVR call)

Authorizations

Path Parameters

Body

Response