Link Number to App

Link a phone number to a SFVoPI application. Once linked, incoming calls to this number will be routed to the app's configured answer_url.

Important

• A phone number can only be linked to one SFVoPI app at a time
• The number must be owned by your organization and not currently linked to another app
• Phone numbers are automatically normalized to E.164 format (e.g., +918000000001)

Authentication

Requires X-API-Key header with a valid API key. See Authentication for details.

Endpoint

POST /sfvopi/apps/:app_id/numbers

Path Parameters

Parameter	Type	Required	Description
app_id	string	Yes	The unique identifier of the SFVoPI app

Request Body

Field	Type	Required	Default	Description	Validation
voip_number	string	Yes	-	Phone number to link to the app	Must be a valid phone number. Automatically normalized to E.164 format with country code (e.g., +918000000001)

Code Examples

cURL

curl -X POST https://prod-api.superfone.co.in/superfone/sfvopi/apps/app_abc123/numbers \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"voip_number":"+918000000001"}'

JavaScript

const appId = 'app_abc123';
const response = await fetch(`https://prod-api.superfone.co.in/superfone/sfvopi/apps/${appId}/numbers`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    voip_number: '+918000000001'
  })
});

const data = await response.json();
console.log(data.data); // Linked number object

TypeScript

interface LinkNumberRequest {
  voip_number: string;
}

interface SfvopiAppNumber {
  app_id: string;
  voip_number: string;
  org_id: number;
  status: string;
  created_at: string;
  updated_at: string | null;
}

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

const appId = 'app_abc123';
const response = await fetch(`https://prod-api.superfone.co.in/superfone/sfvopi/apps/${appId}/numbers`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    voip_number: '+918000000001'
  } as LinkNumberRequest)
});

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

Python

import requests

app_id = 'app_abc123'
url = f'https://prod-api.superfone.co.in/superfone/sfvopi/apps/{app_id}/numbers'
headers = {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
payload = {
    'voip_number': '+918000000001'
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data['data'])  # Linked number object

Success Response

Status Code: 200 OK

{
  "data": {
    "app_id": "app_abc123",
    "voip_number": "+918000000001",
    "org_id": 456,
    "status": "ACTIVE",
    "created_at": "2026-02-02T10:30:00.000Z",
    "updated_at": null
  },
  "message": "success"
}

Response Fields

Field	Type	Description
data	object	The linked number object
data.app_id	string	The SFVoPI app ID this number is linked to
data.voip_number	string	The phone number in E.164 format
data.org_id	number	Your organization ID
data.status	string	Link status (typically ACTIVE)
data.created_at	string	ISO 8601 timestamp when the link was created
data.updated_at	string | null	ISO 8601 timestamp of last update, or null if never updated
message	string	Response message (always "success" on success)

Error Responses

Status Code	Message	When It Occurs
400	Invalid request body	Request body validation failed (invalid phone number format)
400	Number not found or not owned by organization	The phone number doesn't exist in your organization's inventory
404	App not found	The specified app_id doesn't exist or doesn't belong to your organization
409	Number already linked to another app	The phone number is already linked to a different SFVoPI app. Unlink it first.
401	UnAuthorized, Please Provide Valid API Key	Missing or invalid X-API-Key header
500	Failed to link number: <error>	Server error while linking the number

Phone Number Format (E.164)

Phone numbers are automatically normalized to E.164 format with country code:

• Input: 8000000001 or +918000000001 or +91 80000 00001
• Stored as: +918000000001

E.164 format rules:

• Starts with + followed by country code
• No spaces, dashes, or parentheses
• Maximum 15 digits (including country code)

Notes

• One number, one app: A phone number can only be linked to one SFVoPI app at a time
• Automatic normalization: Phone numbers are automatically converted to E.164 format
• Ownership validation: The API verifies that the number belongs to your organization before linking
• Unlinking required: To link a number to a different app, you must first unlink it from the current app

Next Steps

• List Numbers — View all numbers linked to an app
• Unlink Number — Remove a number from an app
• Get Available Numbers — Find numbers available to link
• Update App — Modify app webhook URLs