Initiate Call

Start an outbound call to a customer that plays a pre-configured IVR menu — greeting, DTMF options, and transfer to an agent if the customer requests one.

This call is placed on behalf of your organization's own trunk number. The menu (ivr_uuid) must already exist.

Authentication Required

Requires the x-api-key header. See Overview for details.

HTTP Request

POST /api/ivr/initiate-call

Request Body

Field	Type	Required	Description
ivr_uuid	string (UUID)	Yes	The outbound IVR menu to play, identified by its UUID.
phone_number	string	Yes	The customer's phone number to call, in E.164 format (e.g. +918000000001).

Notes on behavior

• The trunk number and provider used to place the call are your organization's own configured VOIP number — not something you specify per request.
• A successful response means the call was queued to be placed, not that it connected or that anyone answered. Use request_id from the response to look up the call's outcome afterward via your call-history/CDR tooling.
• If your account has Event Notifications set up, an ALL_CALLS (or MISSED_CALL, if unanswered) notification fires automatically once the call completes — no separate action needed on this endpoint. Its payload includes ivr_inputs and dtmf_digits (what the customer pressed in the menu) alongside the usual call fields — see the payload reference.
• Creating or managing outbound IVR menus isn't self-service — it's a request-based feature. Contact the Superfone team at hello@superfone.in to get a menu created or updated.

Try it

Loading playground…

Code Examples

cURL

curl -X POST https://prod-api.superfone.co.in/superfone/api/ivr/initiate-call \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ivr_uuid": "2f8a1c3e-9b7d-4a2e-8c1f-6d4e5a9b0c1d",
    "phone_number": "+918000000001"
  }'

JavaScript

const response = await fetch(
  'https://prod-api.superfone.co.in/superfone/api/ivr/initiate-call',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SF_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ivr_uuid: '2f8a1c3e-9b7d-4a2e-8c1f-6d4e5a9b0c1d',
      phone_number: '+918000000001'
    })
  }
);

const result = await response.json();
console.log(result);

TypeScript

interface InitiateCallRequest {
  ivr_uuid: string;
  phone_number: string;
}

interface InitiateCallResponse {
  data: {
    request_id: string;
    status: 'queued';
  };
  message: string;
}

async function initiateOutboundIvrCall(payload: InitiateCallRequest): Promise<InitiateCallResponse> {
  const response = await fetch(
    'https://prod-api.superfone.co.in/superfone/api/ivr/initiate-call',
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.SF_API_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.message || `HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

const result = await initiateOutboundIvrCall({
  ivr_uuid: '2f8a1c3e-9b7d-4a2e-8c1f-6d4e5a9b0c1d',
  phone_number: '+918000000001'
});
console.log('Queued:', result.data.request_id);

Python

import os
import requests

url = 'https://prod-api.superfone.co.in/superfone/api/ivr/initiate-call'
headers = {
    'x-api-key': os.environ['SF_API_KEY'],
    'Content-Type': 'application/json'
}
payload = {
    'ivr_uuid': '2f8a1c3e-9b7d-4a2e-8c1f-6d4e5a9b0c1d',
    'phone_number': '+918000000001'
}

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

Success Response

Status Code: 200 OK

{
  "data": {
    "request_id": "ivr_ob_req_a1b2c3d4e5f6",
    "status": "queued"
  },
  "message": "success"
}

Field	Type	Description
data.request_id	string	Unique identifier for this call attempt. Use it to correlate against your call-history/CDR records once the call completes.
data.status	string	Always "queued" on success — the call has been handed off to be placed, not yet answered or connected.
message	string	Status message indicating the result.

Error Responses

Status	Message	When it occurs
400	Invalid phone number	phone_number is not a valid, parseable phone number
400	(validation message)	ivr_uuid is missing or not a valid UUID, phone_number is missing, or the body contains an unrecognized field
401	UnAuthorized, Please Provide API Key	Missing x-api-key header
401	UnAuthorized, Please Provide Valid API Key	x-api-key doesn't match any organization
403	This call is blocked by outbound calling policy.	The destination number is blocked by outbound calling compliance rules
404	Outbound IVR menu not found	ivr_uuid doesn't exist, doesn't belong to your organization, or isn't an outbound-type menu
404	No VOIP number found for this organization	Your organization has no active trunk/VOIP number configured
429	Your channel limit is reached, please try again after sometime	Your organization's concurrent outbound channel limit is exhausted — retry shortly
500	Failed to initiate call. / Failed to initiate call. Service temporarily unavailable.	An unexpected or transient failure occurred while placing the call — safe to retry

Example error

{
  "message": "Outbound IVR menu not found"
}