Provider

A provider represents a telephony carrier configuration (e.g., Telnyx, Twilio) that supplies SIP trunking and phone number services to the VoIPBIN platform.

API Reference: Provider endpoints

Overview

Note

AI Context

Complexity: Low
Cost: Free. Providers are configuration records. Costs are incurred when calls are routed through the configured provider, not when creating the provider entry.
Async: No. POST https://api.voipbin.net/v1.0/providers returns immediately with the created provider.

VoIPBIN’s Provider API enables management of telecommunication service providers that handle external call routing. Providers are SIP trunking services that connect VoIPBIN to the PSTN (Public Switched Telephone Network) and other external networks.

With the Provider API you can:

Set up a carrier-backed SIP trunk in one step via POST /providers/setup
Configure SIP trunk providers manually
Set technical parameters for call routing
Manage provider credentials
Define routing preferences
Monitor provider status

Easy Provider Setup

POST https://api.voipbin.net/v1.0/providers/setup lets a ProjectSuperAdmin submit a carrier API key and have VoIPBIN automatically validate the key, create the carrier-side SIP credential connection, and create the VoIPBin provider record — all in a single request.

Supported carriers: telnyx

How it works:

+--------------------------------------------+
|  POST /providers/setup                     |
|                                            |
|  1. Validate carrier API key               |
|  2. Create carrier SIP credential conn.    |
|  3. Create VoIPBIN provider record         |
|  Returns: provider (id, hostname, …)       |
+--------------------------------------------+

Note

AI Implementation Hint

Use POST /providers/setup instead of POST /providers when you have a carrier API key and want the platform to handle the SIP trunk creation automatically. If the API key is invalid or lacks the required permissions, the endpoint returns 422 Unprocessable Entity. On success, the returned provider id can immediately be referenced in POST /routes to enable outbound call routing.

How Providers Work

Providers connect VoIPBIN to external telephone networks.

Provider Architecture

+-----------------------------------------------------------------------+
|                         Provider System                               |
+-----------------------------------------------------------------------+

VoIPBIN                         Provider                    External
   |                               |                           |
   | Outbound call                 |                           |
   +------------------------------>|                           |
   |                               | Route to PSTN             |
   |                               +-------------------------->|
   |                               |                           |
   |                               |        Call connects      |
   |<------------------------------|<--------------------------+
   |                               |                           |

+-------------------+        +-------------------+        +-----------+
|    VoIPBIN        |        |     Provider      |        |   PSTN    |
|    Platform       |<------>|   (SIP Trunk)     |<------>|  Network  |
+-------------------+        +-------------------+        +-----------+
                                    |
                          +---------+---------+
                          |                   |
                          v                   v
                    +---------+         +---------+
                    | Telnyx  |         | Twilio  |
                    +---------+         +---------+

Key Components

Provider: A SIP trunk service for external call routing
Hostname: The SIP server address
Tech Prefix/Postfix: Number formatting rules
Tech Headers: Custom SIP headers for authentication

Provider Configuration

Configure providers with technical parameters.

Provider Properties

Property	Description
id	Unique identifier for the provider
name	Display name of the provider
type	Protocol type (e.g., “sip”)
hostname	SIP server address (e.g., sip.telnyx.com)
tech_prefix	Prefix to add to dialed numbers
tech_postfix	Suffix to add to dialed numbers
tech_headers	Custom SIP headers for the provider

Example Provider Configuration

{
    "id": "provider-uuid-123",
    "name": "Telnyx Production",
    "type": "sip",
    "hostname": "sip.telnyx.com",
    "tech_prefix": "",
    "tech_postfix": "",
    "tech_headers": {
        "X-Custom-Header": "value"
    },
    "tm_create": "2024-01-01T00:00:00Z"
}

Note

AI Implementation Hint

Providers are typically managed by platform administrators. The tech_prefix and tech_postfix fields modify the dialed number before sending to the provider. Most providers do not require these fields (leave as empty strings). The tech_headers field is an object of custom SIP headers sent with every call to this provider – use it for provider-specific authentication tokens or routing hints.

Provider Types

VoIPBIN supports various provider configurations.

SIP Provider

+--------------------------------------------+
| SIP Provider                               |
+--------------------------------------------+
| Protocol: SIP (Session Initiation Protocol)|
| Used for: Voice calls                      |
| Example: Telnyx, Twilio, Bandwidth         |
+--------------------------------------------+

Outbound Call Flow:
VoIPBIN -> SIP INVITE -> Provider -> PSTN

Number Formatting

Providers may require specific number formats.

Tech Prefix/Postfix Usage

Original Number: +15551234567

With Prefix "1":
+--------------------------------------------+
| Dialed: 1+15551234567                      |
+--------------------------------------------+

With Postfix "@provider.com":
+--------------------------------------------+
| Dialed: +15551234567@provider.com          |
+--------------------------------------------+

With Both:
+--------------------------------------------+
| Dialed: 1+15551234567@provider.com         |
+--------------------------------------------+

Common Scenarios

Scenario 1: Primary Provider Setup

Configure main outbound provider.

Provider: "Main Carrier"
+--------------------------------------------+
| name: "Telnyx Production"                  |
| hostname: "sip.telnyx.com"                 |
| type: "sip"                                |
|                                            |
| Used for: All outbound calls               |
+--------------------------------------------+

Scenario 2: Multi-Provider Configuration

Configure multiple providers for failover.

Primary Provider: "Telnyx"
+--------------------------------------------+
| hostname: "sip.telnyx.com"                 |
| Priority: 1 (first choice)                 |
+--------------------------------------------+

Secondary Provider: "Twilio"
+--------------------------------------------+
| hostname: "sip.twilio.com"                 |
| Priority: 2 (failover)                     |
+--------------------------------------------+

Routing Logic:
1. Try primary provider
2. If failed -> try secondary

Scenario 3: Regional Providers

Use different providers for different regions.

US Provider: "Telnyx US"
+--------------------------------------------+
| For numbers: +1xxx                         |
| Optimal routing for US calls               |
+--------------------------------------------+

EU Provider: "Telnyx EU"
+--------------------------------------------+
| For numbers: +44, +49, +33...             |
| Optimal routing for EU calls               |
+--------------------------------------------+

Best Practices

1. Provider Selection

Choose providers with good coverage for your regions
Consider pricing, quality, and reliability
Test providers before production use

2. Configuration

Keep provider credentials secure
Document provider-specific requirements
Test number formatting thoroughly

3. Failover

Configure multiple providers
Set up proper failover routing
Monitor provider health

4. Monitoring

Track call success rates per provider
Monitor latency and quality
Set up alerts for provider issues

Troubleshooting

Setup Endpoint Errors

HTTP Status	Cause and Fix
422 Unprocessable Entity	The carrier API key is invalid or lacks sufficient permissions. Verify the key in the carrier’s dashboard and try again.
400 Bad Request	Missing required fields (`carrier`, `name`, `detail`, `credentials.api_key`) or unsupported carrier name.

Connection Issues

Symptom	Solution
Calls not connecting	Verify hostname is correct; check provider credentials; test network connectivity
Authentication failures	Check tech_headers for auth info; verify credentials with provider

Routing Issues

Symptom	Solution
Wrong number format	Check tech_prefix and tech_postfix; verify provider requirements
Provider rejecting calls	Check account status with provider; verify number is allowed

Provider

{
    "id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "type": "<string>",
    "hostname": "<string>",
    "tech_prefix": "<string">,
    "tech_postfix": "<string>",
    "tech_headers": {
        "<string>": "<string">,
    },
    "metadata": {},
    "health_status": "<string>",
    "health_checked_at": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The provider’s unique identifier. Returned when creating via POST /providers or listing via GET /providers.
name (String): A human-readable label for the provider. Free-form text for organizational use.
detail (String): A longer description of the provider’s purpose or configuration notes.
type (enum string): The provider’s protocol type. See Type.
hostname (String): The SIP server address for the provider (e.g., sip.telnyx.com). Used as the destination for outbound SIP INVITE messages.
tech_prefix (String): Prefix attached to the beginning of the dialed destination number. Valid only for type sip. Leave as empty string if not required.
tech_postfix (String): Postfix attached to the end of the dialed destination number. Valid only for type sip. Leave as empty string if not required.
tech_headers (Object): Key/value pairs of custom SIP headers sent with outbound calls. Valid only for type sip. Use empty object {} if not required.
metadata (Object): Carrier-specific resource identifiers stored during automated setup. For Telnyx providers created via POST /providers/setup, contains telnyx_profile_id, telnyx_connection_id, and telnyx_ip_ids. Read-only — populated automatically by the setup endpoint. Empty object {} if the provider was created manually via POST /providers.
health_status (enum string): The result of the most recent SIP OPTIONS health check. See Health Status.
health_checked_at (string, ISO 8601 or null): Timestamp of the last completed health check. null if no check has been performed yet. Resets to null when hostname is updated.
tm_create (string, ISO 8601): Timestamp when the provider was created.
tm_update (string, ISO 8601): Timestamp of the last update to any provider property.
tm_delete (string, ISO 8601): Timestamp when the provider was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Note

AI Implementation Hint

Timestamps set to 9999-01-01 00:00:00.000000 indicate the event has not yet occurred. For example, tm_delete with this value means the provider has not been deleted.

Example

{
    "id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "type": "sip",
    "hostname": "sip.telnyx.com",
    "tech_prefix": "",
    "tech_postfix": "",
    "tech_headers": {},
    "metadata": {
        "telnyx_profile_id": "2944757397136082899",
        "telnyx_connection_id": "2944757397198982899",
        "telnyx_ip_ids": ["2944757397261882899"]
    },
    "health_status": "healthy",
    "health_checked_at": "2026-04-20 03:15:00.000000",
    "name": "telnyx basic",
    "detail": "telnyx basic",
    "tm_create": "2022-10-22 16:16:16.874761",
    "tm_update": "2022-10-24 04:53:14.171374",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Health Status

Reflects the result of the most recent SIP OPTIONS health check sent from the Kamailio VM.

Health Status	Description
unknown	No health check has been performed yet. Initial state for all new providers and after the `hostname` field is updated.
healthy	The provider responded to a SIP OPTIONS request within the timeout window. Any SIP response code is considered healthy.
unhealthy	No SIP response was received within the timeout (default 5 seconds), or the hostname could not be resolved.

Note

AI Implementation Hint

health_status is read-only. It is set automatically by the background health check goroutine and cannot be set via the API. When hostname is updated on a provider, health_status resets to unknown and health_checked_at resets to null until the next health check cycle completes.

Type

Defines types of provider.

Type	Description
sip	SIP service provider. Uses Session Initiation Protocol for voice call routing to the PSTN. Examples: Telnyx, Twilio, Bandwidth.

Tutorial

Before working with providers, you need:

An authentication token with ProjectSuperAdmin permission. Obtain one via POST /auth/login.
The provider’s SIP hostname (e.g., sip.telnyx.com), or a carrier API key if using POST /providers/setup.
(Optional) Any custom SIP headers or number formatting rules required by the provider.

Note

AI Implementation Hint

Providers are typically managed by platform administrators. After creating a provider, you must create at least one route (via POST /routes) that references the provider’s id before outbound calls can use it. The provider alone does not enable call routing.

Set up a provider via carrier API key

POST /providers/setup validates your carrier API key, creates the carrier-side SIP trunk, and returns a ready-to-use VoIPBIN provider record — all in one call. Requires ProjectSuperAdmin permission.

Supported carriers: telnyx

Request

$ curl --location --request POST 'https://api.voipbin.net/v1.0/providers/setup?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "carrier": "telnyx",
        "name": "My Telnyx Trunk",
        "detail": "Primary outbound Telnyx SIP trunk",
        "credentials": {
            "api_key": "KEY_01234567890abcdef"
        }
    }'

Response (200 OK)

{
    "id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "type": "sip",
    "hostname": "sip.telnyx.com",
    "tech_prefix": "",
    "tech_postfix": "",
    "tech_headers": {},
    "name": "My Telnyx Trunk",
    "detail": "Primary outbound Telnyx SIP trunk",
    "tm_create": "2026-04-23T10:00:00.000000Z",
    "tm_update": "2026-04-23T10:00:00.000000Z",
    "tm_delete": "9999-01-01T00:00:00.000000Z"
}

Note

AI Implementation Hint

Save the returned id field (UUID). You will need it when creating a route via POST /routes to enable outbound calling through this provider. If the API key is invalid or lacks the required permissions, the endpoint returns 422 Unprocessable Entity — verify the key in the Telnyx portal and retry.

Get list of providers

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/providers?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
            "type": "sip",
            "hostname": "sip.telnyx.com",
            "tech_prefix": "",
            "tech_postfix": "",
            "tech_headers": {},
            "name": "telnyx basic",
            "detail": "telnyx basic",
            "tm_create": "2022-10-22 16:16:16.874761",
            "tm_update": "2022-10-24 04:53:14.171374",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
        ...
    ],
    "next_page_token": "2022-10-22 16:16:16.874761"
}

Get detail of provider

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/providers/4dbeabd6-f397-4375-95d2-a38411e07ed1?token=<YOUR_AUTH_TOKEN>'

{
    "id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "type": "sip",
    "hostname": "sip.telnyx.com",
    "tech_prefix": "",
    "tech_postfix": "",
    "tech_headers": {},
    "name": "telnyx basic",
    "detail": "telnyx basic",
    "tm_create": "2022-10-22 16:16:16.874761",
    "tm_update": "2022-10-24 04:53:14.171374",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Create a new provider

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/providers?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "type": "sip",
        "hostname": "test.com",
        "tech_prefix": "",
        "tech_postfix": "",
        "tech_headers": {},
        "name": "test domain",
        "detail": "test domain creation"
    }'

Update provider

Example

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/providers/4dbeabd6-f397-4375-95d2-a38411e07ed1?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "type": "sip",
        "hostname": "sip.telnyx.com",
        "tech_prefix": "",
        "tech_postfix": "",
        "tech_headers": {},
        "name": "telnyx basic",
        "detail": "telnyx basic"
    }'

Delete provider

Example

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/providers/7efc9379-2d3e-4e54-9d36-23cff676a83e?token=<YOUR_AUTH_TOKEN>'

Provider

Overview

Easy Provider Setup

How Providers Work

Provider Configuration

Provider Types

Number Formatting

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Provider

Provider

Example

Health Status

Type

Tutorial

Set up a provider via carrier API key

Get list of providers

Get detail of provider

Create a new provider

Update provider

Delete provider