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 /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:

Configure SIP trunk providers
Set technical parameters for call routing
Manage provider credentials
Define routing preferences
Monitor provider status

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

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">,
    },
    "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.
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": {},
    "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"
}

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. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
The provider’s SIP hostname (e.g., sip.telnyx.com). This is provided by the telephony service provider.
(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.

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' \
    --header 'Cookie: token=<YOUR_AUTH_TOKEN>' \
    --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

How Providers Work

Provider Configuration

Provider Types

Number Formatting

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Provider

Provider

Example

Type

Tutorial

Get list of providers

Get detail of provider

Create a new provider

Update provider

Delete provider