Initiate Outbound Call

Initiate an outbound call from a phone number linked to your SFVoPI app. The call is placed asynchronously — the API returns immediately with a request_uuid and queued status. You'll receive webhook callbacks as the call progresses through its lifecycle.

Asynchronous Operation

This endpoint returns immediately after queuing the call. Use the request_uuid to correlate webhook callbacks (ring_url, answer_url, hangup_url) that notify you of call state changes.

Authentication

Requires X-API-Key header. See Authentication for details.

Endpoint

POST /sfvopi/calls

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

Request Body

All fields are validated and phone numbers are automatically normalized to E.164 format.

Field	Type	Required	Default	Description	Validation
from	string	Yes	-	Your phone number (must be linked to an active SFVoPI app)	E.164 format (e.g., +918000000003)
to	string	Yes	-	Destination phone number to call	E.164 format (e.g., +918000000001)
answer_url	string	Yes	-	Webhook URL called when callee answers	Valid HTTPS/HTTP URL
answer_method	string	No	POST	HTTP method for answer webhook	POST or GET
ring_url	string	No	-	Webhook URL called when phone starts ringing	Valid HTTPS/HTTP URL
ring_method	string	No	POST	HTTP method for ring webhook	POST or GET
hangup_url	string	No	-	Webhook URL called when call ends	Valid HTTPS/HTTP URL
hangup_method	string	No	POST	HTTP method for hangup webhook	POST or GET
call_time_limit	number	No	14400	Maximum call duration in seconds (4 hours default)	Min: 1, Max: 86400 (24 hours)
ring_timeout	number	No	60	Maximum ring duration in seconds before giving up	Min: 1, Max: 600 (10 minutes)

From Number Must Be Linked

The from number MUST be linked to an active SFVoPI app in your organization. If not, you'll receive a 400 error. Use the Link Number endpoint to link numbers first.

Webhook URL Overrides

Webhooks specified in this request override the app's default webhook URLs for this specific call only. This allows per-call customization without modifying your app configuration.

Code Examples

cURL

curl -X POST https://prod-api.superfone.co.in/superfone/sfvopi/calls \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+918000000003",
    "to": "+918000000001",
    "answer_url": "https://example.com/webhook/answer",
    "answer_method": "POST",
    "ring_url": "https://example.com/webhook/ring",
    "ring_method": "POST",
    "hangup_url": "https://example.com/webhook/hangup",
    "hangup_method": "POST",
    "call_time_limit": 300,
    "ring_timeout": 30
  }'

JavaScript

const response = await fetch('https://prod-api.superfone.co.in/superfone/sfvopi/calls', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+918000000003',
    to: '+918000000001',
    answer_url: 'https://example.com/webhook/answer',
    answer_method: 'POST',
    ring_url: 'https://example.com/webhook/ring',
    ring_method: 'POST',
    hangup_url: 'https://example.com/webhook/hangup',
    hangup_method: 'POST',
    call_time_limit: 300,
    ring_timeout: 30
  })
});

const result = await response.json();
console.log('Request UUID:', result.data.request_uuid);
console.log('Status:', result.data.status);

TypeScript

interface InitiateCallRequest {
  from: string;
  to: string;
  answer_url: string;
  answer_method?: 'POST' | 'GET';
  ring_url?: string;
  ring_method?: 'POST' | 'GET';
  hangup_url?: string;
  hangup_method?: 'POST' | 'GET';
  call_time_limit?: number;
  ring_timeout?: number;
}

interface InitiateCallResponse {
  data: {
    request_uuid: string;
    status: string;
  };
  message: string;
}

const response = await fetch('https://prod-api.superfone.co.in/superfone/sfvopi/calls', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+918000000003',
    to: '+918000000001',
    answer_url: 'https://example.com/webhook/answer',
    answer_method: 'POST',
    ring_url: 'https://example.com/webhook/ring',
    ring_method: 'POST',
    hangup_url: 'https://example.com/webhook/hangup',
    hangup_method: 'POST',
    call_time_limit: 300,
    ring_timeout: 30
  } as InitiateCallRequest)
});

const result: InitiateCallResponse = await response.json();
console.log('Request UUID:', result.data.request_uuid);
console.log('Status:', result.data.status);

Python

import requests

url = 'https://prod-api.superfone.co.in/superfone/sfvopi/calls'
headers = {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
payload = {
    'from': '+918000000003',
    'to': '+918000000001',
    'answer_url': 'https://example.com/webhook/answer',
    'answer_method': 'POST',
    'ring_url': 'https://example.com/webhook/ring',
    'ring_method': 'POST',
    'hangup_url': 'https://example.com/webhook/hangup',
    'hangup_method': 'POST',
    'call_time_limit': 300,
    'ring_timeout': 30
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print('Request UUID:', result['data']['request_uuid'])
print('Status:', result['data']['status'])

Success Response

Status Code: 200 OK

{
  "data": {
    "request_uuid": "sfv_ob_req_a8k3m2x9p1z0",
    "status": "queued"
  },
  "message": "success"
}

Response Fields

Field	Type	Description
request_uuid	string	Unique identifier for this call request (format: sfv_ob_req_xxxxxxxxxxxx)
status	string	Call status — always queued on successful initiation

Error Responses

Status Code	Message	When It Occurs
400	VoIP number {from} is not linked to any SFVoPI app for this org	The from number is not linked to an active SFVoPI app in your organization
400	Invalid request body	Request body validation failed (invalid phone format, missing required fields, out-of-range values)
401	UnAuthorized, Please Provide Valid API Key	Missing or invalid X-API-Key header
500	Failed to initiate outbound call	Service temporarily unavailable. Retry after a few seconds or contact support.
500	Failed to initiate outbound call: {error}	Unexpected server error

Call Lifecycle

After initiating a call, it progresses through the following states:

State Descriptions

State	Description	Webhook Called
queued	Call request accepted, being placed	None
ringing	Phone is ringing	ring_url (if provided)
answered	Callee answered the call	answer_url
in_progress	Audio streaming active	None
completed	Call ended normally	hangup_url (if provided)
failed	Call failed (network issue, unreachable)	hangup_url (if provided)
no_answer	Callee didn't answer within ring_timeout	hangup_url (if provided)
busy	Callee was busy	hangup_url (if provided)
canceled	Call canceled before being answered	hangup_url (if provided)

Call Flow Diagram

Notes

• Asynchronous Operation: The API returns immediately with queued status. The actual call placement happens asynchronously. Monitor webhooks for real-time call state updates.

• Request UUID: Use the request_uuid to correlate webhook callbacks with this specific call request. All webhooks for this call will include this identifier.

• Phone Number Normalization: Input phone numbers are automatically normalized to E.164 format. You can provide numbers with or without country code, spaces, or dashes — they'll be validated and standardized.

• Webhook Overrides: Webhooks specified in this request (ring_url, answer_url, hangup_url) override the app's default webhook URLs for this call only. If not provided, the app's defaults are used.

• Call Time Limits: The call_time_limit enforces maximum call duration. Calls exceeding this limit are automatically terminated. The ring_timeout limits how long the phone rings before giving up.

• Error Handling: In rare cases, the service may be temporarily unavailable and return a 500 error. Retry after a few seconds or contact support if it persists.

Related Endpoints

• Create App — Create a SFVoPI app to handle calls
• Link Number — Link a phone number to your app
• Answer Webhook — Handle the answer callback
• Hangup Webhook — Handle the hangup callback
• Audio Streaming — Stream audio during calls

Next Steps

• Webhooks Overview — Learn how to handle webhook callbacks
• Audio Streaming — Stream audio to/from calls
• Quickstart Tutorial — Build your first voice app