Create App

Create a new SFVoPI application. An app defines the webhook URLs that will be called when calls are answered or hung up, and can be linked to phone numbers to handle inbound calls.

Authentication Required

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

HTTP Request

POST /sfvopi/apps

Request Body

Field	Type	Required	Default	Description	Validation
name	string	Yes	-	Human-readable name for the app	1-100 characters
answer_url	string	Yes	-	Webhook URL called when a call is answered	Valid URL
answer_method	string	No	POST	HTTP method for answer webhook	POST or GET
hangup_url	string	No	null	Webhook URL called when a call ends	Valid URL or omit
hangup_method	string	No	POST	HTTP method for hangup webhook	POST or GET
fallback_answer_url	string	No	null	Fallback URL if answer_url fails	Valid URL or omit
fallback_answer_method	string	No	POST	HTTP method for fallback webhook	POST or GET

Code Examples

cURL

curl -X POST https://prod-api.superfone.co.in/superfone/sfvopi/apps \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Voice App",
    "answer_url": "https://example.com/webhook/answer",
    "answer_method": "POST",
    "hangup_url": "https://example.com/webhook/hangup",
    "hangup_method": "POST"
  }'

JavaScript

const response = await fetch('https://prod-api.superfone.co.in/superfone/sfvopi/apps', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Voice App',
    answer_url: 'https://example.com/webhook/answer',
    answer_method: 'POST',
    hangup_url: 'https://example.com/webhook/hangup',
    hangup_method: 'POST'
  })
});

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

TypeScript

interface CreateAppRequest {
  name: string;
  answer_url: string;
  answer_method?: 'POST' | 'GET';
  hangup_url?: string;
  hangup_method?: 'POST' | 'GET';
  fallback_answer_url?: string;
  fallback_answer_method?: 'POST' | 'GET';
}

interface SfvopiApp {
  app_id: string;
  org_id: number;
  name: string;
  answer_url: string;
  answer_method: 'POST' | 'GET';
  hangup_url: string | null;
  hangup_method: 'POST' | 'GET';
  fallback_answer_url: string | null;
  fallback_answer_method: 'POST' | 'GET';
  status: 'ACTIVE' | 'INACTIVE';
  concurrent_limit: number | null;
  cps_limit: number | null;
  cps_burst: number | null;
  created_by: number | null;
  created_at: string;
  updated_at: string | null;
}

interface ApiResponse<T> {
  data: T;
  message: string;
}

const response = await fetch('https://prod-api.superfone.co.in/superfone/sfvopi/apps', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Voice App',
    answer_url: 'https://example.com/webhook/answer',
    answer_method: 'POST',
    hangup_url: 'https://example.com/webhook/hangup',
    hangup_method: 'POST'
  } as CreateAppRequest)
});

const result: ApiResponse<SfvopiApp> = await response.json();
console.log(result.data);

Python

import requests

url = 'https://prod-api.superfone.co.in/superfone/sfvopi/apps'
headers = {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
payload = {
    'name': 'My Voice App',
    'answer_url': 'https://example.com/webhook/answer',
    'answer_method': 'POST',
    'hangup_url': 'https://example.com/webhook/hangup',
    'hangup_method': 'POST'
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result['data'])

Success Response

Status Code: 200 OK

{
  "data": {
    "app_id": "sfv_app_abc123xyz456",
    "org_id": 12345,
    "name": "My Voice App",
    "answer_url": "https://example.com/webhook/answer",
    "answer_method": "POST",
    "hangup_url": "https://example.com/webhook/hangup",
    "hangup_method": "POST",
    "fallback_answer_url": null,
    "fallback_answer_method": "POST",
    "status": "ACTIVE",
    "concurrent_limit": null,
    "cps_limit": null,
    "cps_burst": null,
    "created_by": 67890,
    "created_at": "2026-02-02T10:30:00.000Z",
    "updated_at": null
  },
  "message": "success"
}

Response Fields

Org-limits release

App call limits ship with the org-limits release. A new app has no limits of its own, so only your organization's limits apply. Set app limits with Update App. See Call Limits.

Field	Type	Description
app_id	string	Unique identifier for the app (format: sfv_app_xxxxxxxxxxxx)
org_id	number	Organization ID that owns this app
name	string	App name
answer_url	string	Webhook URL for answered calls
answer_method	string	HTTP method for answer webhook (POST or GET)
hangup_url	string | null	Webhook URL for call hangup events
hangup_method	string	HTTP method for hangup webhook
fallback_answer_url	string | null	Fallback webhook URL
fallback_answer_method	string	HTTP method for fallback webhook
status	string	App status (ACTIVE or INACTIVE)
concurrent_limit	number | null	The app's own limit on calls in progress at once. null means only your organization's limit applies
cps_limit	number | null	The app's own limit on new calls per second. null means only your organization's limit applies
cps_burst	number | null	The app's own peak CPS. null means only your organization's limit applies
created_by	number | null	User ID who created the app
created_at	string	ISO 8601 timestamp of creation
updated_at	string | null	ISO 8601 timestamp of last update

Error Responses

Status Code	Message	When It Occurs
400	Invalid request body	Request body fails validation (missing required fields, invalid URL format, name too long, invalid HTTP method)
401	UnAuthorized, Please Provide Valid API Key	Missing or invalid X-API-Key header
500	Failed to create SFVoPI app: {error}	Server error during app creation

Example Error Response

{
  "message": "Invalid request body"
}

Next Steps

After creating an app:

1. Link a phone number to handle inbound calls
2. Implement webhook handlers for answer and hangup events
3. Set up audio streaming to process call audio in real-time

Related Endpoints

• List Apps — Get all apps for your organization
• Get App — Retrieve a specific app by ID
• Update App — Modify app configuration
• Delete App — Remove an app