Outbound IVR

Outbound IVR lets you trigger a call to a customer that plays a pre-configured IVR menu — a greeting, DTMF options, and a transfer to an agent if the customer requests one — instead of connecting them straight to a person.

The menu itself (greeting audio, DTMF options, which agents to transfer to) is configured ahead of time. This API only starts a call against an existing menu — it doesn't create or edit menus. Creating or managing a menu isn't self-service — it's a request-based feature; contact the Superfone team at hello@superfone.in to get one set up.

After call: Purchase the post call webhook add-on to get complete details of what happened on the call and the customer's choice selection with call recording and AI summary. More details

Authentication Required

All endpoints require an x-api-key header, generated from your Superfone dashboard. Campaign Manager is not enabled by default — contact the Superfone team at hello@superfone.in to get it turned on for your account.

Important points & limitations

1. You can have mutliple active Outbound IVR campaigns on at the same time. Simply pass the IVR id when you initiate the call to invoke that one of the specific call
2. Configuration and modification requires you to contact us. We will soon release a self serve mechanism
3. Number of concurrent calls is dependent on your account allowance and almost always equal to the number of team member seats. Contact us if you want to purchase additional capacity.
4. You can configure an audio greeting, multiple choices with each level have its own message and eventually choose the right action for the end leaf node such as transferring to a particular set of human and Superfone AI agents (arranged in any ringing order of your choice) or to play a message and end the call
5. Outbound IVR campaigns and configurations do not affect the configured incoming IVR or incoming call ringing pattern on your account
6. All pricing and policies around this feature are to be discussed with the team by emailing hello@superfone.in

Base URL

All requests are made to:

https://prod-api.superfone.co.in/superfone

For example, the initiate-call endpoint is:

POST https://prod-api.superfone.co.in/superfone/api/ivr/initiate-call

Authentication

Every request must include the x-api-key header:

x-api-key: your_api_key_here

A missing or invalid key returns 401 Unauthorized:

{
  "message": "UnAuthorized, Please Provide API Key"
}

Response Format

All responses use the standard envelope.

Success:

{
  "data": {
    /* ... */
  },
  "message": "success"
}

Error:

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

Endpoints

Method	Path	Description
POST	/api/ivr/initiate-call	Initiate an outbound IVR call to a customer

Conventions

Phone number format

phone_number should be in E.164 format (international, with + prefix). Examples: +918000000001, +14155552671.

The IVR menu itself

ivr_uuid identifies a menu already configured for your organization — this API doesn't accept inline menu content, and this endpoint only starts a call against an existing menu. Creating or editing a menu isn't self-service — it's a request-based feature; contact the Superfone team at hello@superfone.in to get one set up.

Rate/capacity limits

Each organization has a configured limit on concurrent outbound channels for a trunk. If you're triggering calls in a tight burst (e.g. the opening wave of a campaign), you may hit 429 Your channel limit is reached — back off and retry rather than hammering the endpoint.

After the call ends

If your account has Event Notifications set up, an ALL_CALLS (or MISSED_CALL) notification fires automatically once the call completes — no polling required on your end. Its payload includes ivr_inputs and dtmf_digits (what the customer pressed in the menu), not the full transfer/outcome detail — see the payload reference for the exact shape.

HTTP Status Codes

Status	Meaning
200 OK	Call was successfully queued
400 Bad Request	Validation failed (missing/invalid ivr_uuid or phone_number)
401 Unauthorized	Missing or invalid API key
403 Forbidden	Blocked by outbound calling policy
404 Not Found	IVR menu not found, or no VOIP number configured for your org
429 Too Many Requests	Outbound channel limit reached — retry after a short delay
500 Internal Server Error	Unexpected server error, or the call couldn't be placed right now