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, in service, and not linked to another app or attached to an SF trunk
Linking a number that is already linked to this app returns the existing link instead of an error
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
JavaScript
TypeScript
Python

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"}'

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

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);

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`	`Invalid voip_number: <number>`	The number is not a valid phone number
`400`	`VoIP number not found or does not belong to this org`	The phone number doesn't exist in your organization's inventory
`404`	`SFVoPI app not found`	The specified `app_id` doesn't exist or doesn't belong to your organization
`409`	`VoIP number is already attached to an SF trunk: <number>`	The number is attached to an SF trunk. Detach it from the trunk first.
`409`	`VoIP number is already linked to another SFVoPI app`	The phone number is already linked to a different SFVoPI app. Unlink it first.
`409`	`VoIP number is already linked to this SFVoPI app but the link is inactive; unlink it and link it again`	The number is linked to this app, but the link is inactive
`409`	`VoIP number is not in a serviceable state: <number>`	The number is not in service, for example on hold or refunded. Email hello@superfone.in
`401`	`UnAuthorized, Please Provide Valid API Key`	Missing or invalid `X-API-Key` header
`500`	`Failed to link number. Please try again later.`	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

Authentication​

Endpoint​

Path Parameters​

Request Body​

Code Examples​

Success Response​

Response Fields​

Error Responses​

Phone Number Format (E.164)​

Notes​

Next Steps​