API Overview

This page covers the fundamental conventions and patterns used across the SFVoPI API.

Base URL

All API requests are made to:

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

Example endpoint:

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

Request Format

Content Type

All requests with a body must use JSON format with the Content-Type: application/json header.

Example:

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 App","answer_url":"https://example.com/answer"}'

Authentication

Every request requires the X-API-Key header. See Authentication for details.

Response Format

All API responses follow a consistent envelope structure.

Success Response

Successful requests return a 200 OK or 201 Created status with this format:

{
  "data": {
    // Actual response data (object, array, or primitive)
  },
  "message": "success"
}

Example (Create App):

{
  "data": {
    "app_id": "app_abc123xyz",
    "org_id": 42,
    "name": "My Voice App",
    "answer_url": "https://example.com/answer",
    "answer_method": "POST",
    "status": "ACTIVE",
    "created_at": "2026-02-02T10:30:00.000Z"
  },
  "message": "success"
}

Example (List Apps):

{
  "data": [
    {
      "app_id": "app_abc123",
      "name": "App 1",
      "status": "ACTIVE"
    },
    {
      "app_id": "app_def456",
      "name": "App 2",
      "status": "ACTIVE"
    }
  ],
  "message": "success"
}

Error Response

Failed requests return an appropriate HTTP status code with this format:

{
  "message": "Error description"
}

Example (401 Unauthorized):

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

Example (400 Bad Request):

{
  "message": "Invalid phone number"
}

Example (404 Not Found):

{
  "message": "App not found"
}

info

All examples in this documentation show the full response envelope ({ data, message } for success, { message } for errors).

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Meaning	Description
200 OK	Success	Request succeeded (GET, PUT, DELETE)
201 Created	Created	Resource created successfully (POST)
400 Bad Request	Client Error	Validation failed or invalid request parameters
401 Unauthorized	Auth Error	Missing or invalid API key
404 Not Found	Not Found	Requested resource doesn't exist
409 Conflict	Conflict	Resource conflict (e.g., duplicate number link)
500 Internal Server Error	Server Error	Unexpected server error occurred
502 Bad Gateway	Gateway Error	Webhook failed or unreachable

Phone Number Format

All phone numbers in the API use E.164 format:

• International format with + prefix
• Country code + subscriber number
• No spaces, dashes, or parentheses

Valid examples:

• +918000000001 (India)
• +14155552671 (USA)
• +442071234567 (UK)

Invalid examples:

• 8000000001 (missing country code)
• +91 80000 00001 (contains spaces)
• +91-8000000001 (contains dashes)

tip

The API automatically validates and normalizes phone numbers. If you provide an invalid number, you'll receive a 400 Bad Request error with message "Invalid phone number".

Pagination

Currently, pagination is not available on list endpoints. All list endpoints return the complete set of results.

Example (List Apps):

GET /sfvopi/apps
# Returns ALL apps for your organization

info

Pagination support is planned for a future release. For now, list endpoints return all matching records.

Rate Limiting

Rate limiting is not currently enforced on the API.

info

Rate limits will be introduced in a future release to ensure fair usage and platform stability. We'll provide advance notice before implementing limits.

Idempotency

The API does not currently support idempotency keys. Retrying a failed POST request may create duplicate resources.

Best practice: Implement retry logic with exponential backoff and check for existing resources before creating new ones.

Timestamps

All timestamps in API responses use ISO 8601 format with UTC timezone:

2026-02-02T10:30:00.000Z

Fields:

• created_at — When the resource was created
• updated_at — When the resource was last modified
• answered_at — When a call was answered
• ended_at — When a call ended

Error Handling Best Practices

When consuming the API:

1. Always check HTTP status codes before parsing response body
2. Handle 401 errors by verifying your API key
3. Handle 400 errors by validating input before sending requests
4. Handle 502 errors by ensuring your webhook URLs are accessible
5. Implement retry logic with exponential backoff for 500 errors
6. Log error messages from the message field for debugging

Example (JavaScript):

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

if (!response.ok) {
  const error = await response.json();
  console.error(`API Error (${response.status}):`, error.message);
  throw new Error(error.message);
}

const { data } = await response.json();
console.log('App created:', data);

Next Steps

Now that you understand the API conventions:

• Apps API — Create and manage voice applications
• Numbers API — Link phone numbers to apps
• Calls API — Initiate and manage calls
• Webhooks — Handle call events