Route

Overview

VoIPBIN’s Route API provides intelligent SIP routing with automatic failover capabilities. Routes determine which provider handles outbound calls and define fallback strategies when primary routes fail.

With the Route API you can:

Define routing rules for outbound calls
Configure provider failover sequences
Set conditions for route selection
Customize routing per customer
Optimize call delivery success rates

How Routes Work

Routes determine which provider handles each outbound call.

Route Architecture

+-----------------------------------------------------------------------+
|                         Routing System                                |
+-----------------------------------------------------------------------+

Outbound Call Request
      |
      v
+-------------------+
|   Route Engine    |
+--------+----------+
         |
         | Evaluate routes
         v
+--------+----------+--------+----------+
|                   |                   |
v                   v                   v
+----------+   +----------+   +----------+
| Route 1  |   | Route 2  |   | Route 3  |
| Priority |   | Priority |   | Priority |
|    1     |   |    2     |   |    3     |
+----+-----+   +----+-----+   +----+-----+
     |              |              |
     v              v              v
+---------+    +---------+    +---------+
|Provider |    |Provider |    |Provider |
|    A    |    |    B    |    |    C    |
+---------+    +---------+    +---------+

Key Components

Route: A rule that maps calls to providers
Priority: Order in which routes are attempted
Failover: Automatic retry with different provider on failure
Conditions: Criteria for route selection

Route Failover

Routes support automatic failover when providers fail.

Failover Flow

Outbound Call
      |
      v
+-------------------+
| Try Route 1       |
| (Provider A)      |
+--------+----------+
         |
         +--------> Success? --> Call connected
         |
         v Failure (4xx, 5xx, 6xx)
+-------------------+
| Try Route 2       |
| (Provider B)      |
+--------+----------+
         |
         +--------> Success? --> Call connected
         |
         v Failure
+-------------------+
| Try Route 3       |
| (Provider C)      |
+--------+----------+
         |
         +--------> Success? --> Call connected
         |
         v All failed
+-------------------+
| Return error      |
| to caller         |
+-------------------+

Failover Triggers

SIP Response	Description
404	Number not found - try alternate provider
5xx	Server error - provider issue, try backup
6xx	Global failure - try different route

Dynamic Routing Decisions

Routes can be selected based on various criteria.

Routing Criteria

+-------------------+
| Incoming Call     |
| Destination: +1...|
+--------+----------+
         |
         v
+-------------------+
| Check criteria:   |
| o Destination     |
| o Customer        |
| o Time of day     |
| o Cost            |
+--------+----------+
         |
         v
+-------------------+
| Select best route |
+-------------------+

Routing Options

Criteria	Description
Default Route	Applied to all calls unless overridden
Customer Route	Specific routes for individual customers
Destination Route	Routes based on called number prefix

Route Configuration

Configure routes with priorities and providers.

Create a Route

$ curl -X POST 'https://api.voipbin.net/v1.0/routes?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "US Primary Route",
        "provider_id": "provider-uuid-123",
        "priority": 1,
        "detail": "Primary route for US outbound calls"
    }'

Route Configuration Example

Route: "US Outbound"
+--------------------------------------------+
| name: "US Primary Route"                   |
| provider_id: provider-uuid-telnyx          |
| priority: 1                                |
+--------------------------------------------+

Route: "US Backup"
+--------------------------------------------+
| name: "US Backup Route"                    |
| provider_id: provider-uuid-twilio          |
| priority: 2                                |
+--------------------------------------------+

Common Scenarios

Scenario 1: Simple Failover

Two providers with automatic failover.

Route Configuration:
+--------------------------------------------+
| Route 1: Telnyx (priority 1)               |
|   -> Primary for all calls                 |
|                                            |
| Route 2: Twilio (priority 2)               |
|   -> Used if Telnyx fails                  |
+--------------------------------------------+

Call Flow:
1. Call attempt via Telnyx
2. If Telnyx returns 503 -> try Twilio
3. If Twilio succeeds -> call connected

Scenario 2: Cost-Based Routing

Route based on destination for cost optimization.

Route Configuration:
+--------------------------------------------+
| US Calls (+1):                             |
|   Provider A (lowest US rates)             |
|                                            |
| EU Calls (+44, +49, +33):                  |
|   Provider B (best EU coverage)            |
|                                            |
| Default:                                   |
|   Provider C (global coverage)             |
+--------------------------------------------+

Scenario 3: Customer-Specific Routes

Different routes for different customers.

Customer A: Enterprise (priority routing)
+--------------------------------------------+
| Primary: Premium Provider (quality focus)  |
| Backup: Standard Provider                  |
+--------------------------------------------+

Customer B: Startup (cost-focused)
+--------------------------------------------+
| Primary: Budget Provider (cost focus)      |
| Backup: Standard Provider                  |
+--------------------------------------------+

Best Practices

1. Failover Configuration

Always configure at least 2 routes
Order routes by reliability, then cost
Test failover regularly

2. Provider Selection

Choose providers with complementary coverage
Consider quality vs. cost tradeoffs
Monitor success rates per provider

3. Route Organization

Use descriptive route names
Document routing logic
Review and optimize periodically

4. Monitoring

Track route usage and success rates
Set up alerts for high failure rates
Analyze failover patterns

Troubleshooting

Routing Issues

Symptom	Solution
Calls not routing	Check route exists; verify provider is configured; check priority order
Wrong provider selected	Review route priorities; check for customer- specific overrides
Failover not working	Verify backup routes exist; check failover conditions are met

Provider Issues

Symptom	Solution
All routes failing	Check provider status; verify credentials; test network connectivity
High failover rate	Check primary provider health; consider changing route priorities

Route

{
    "id": "<string>",
    "customer_id": "<string>",
    "provider_id": "<string>",
    "priority": <integer>,
    "target": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id: Provider’s id.
customer_id: Customer’s id. If the customer id is “00000000-0000-0000-0000-000000000001”, then it used for every customer.
provider_id: Provider’s id.
priority: Route priority.
target: Target country code. If it set to “all”, it used for every destination target.

example

{
    "id": "491b6858-5357-11ed-b753-8fd49cd36340",
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 1,
    "target": "all",
    "tm_create": "2022-10-22 16:16:16.874761",
    "tm_update": "2022-10-22 16:16:16.874761",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Tutorial

Get list of routes

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/routes?customer_id=00000000-0000-0000-0000-000000000001&token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "491b6858-5357-11ed-b753-8fd49cd36340",
            "customer_id": "00000000-0000-0000-0000-000000000001",
            "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
            "priority": 1,
            "target": "all",
            "tm_create": "2022-10-22 16:16:16.874761",
            "tm_update": "2022-10-22 16:16:16.874761",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ],
    "next_page_token": "2022-10-22 16:16:16.874761"
}

Get detail of route

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/routes/dccfd81b-5f11-4c49-8e3f-70730ef1a4d3?token=<YOUR_AUTH_TOKEN>'

{
    "id": "dccfd81b-5f11-4c49-8e3f-70730ef1a4d3",
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 1,
    "target": "+82",
    "tm_create": "2022-10-26 11:41:18.124909",
    "tm_update": "2022-10-29 14:50:33.477405",
    "tm_delete": "2022-10-29 14:50:33.477405"
}

Create a new route

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/routes?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 1,
    "target": "+82"
}'

{
    "id": "b972b61c-59d2-4217-8fbb-a32304be5c3b",
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 1,
    "target": "+82",
    "tm_create": "2022-11-02 15:36:32.174346",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Update route

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

{
    "id": "b972b61c-59d2-4217-8fbb-a32304be5c3b",
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 1,
    "target": "+82",
    "tm_create": "2022-11-02 15:36:32.174346",
    "tm_update": "2022-11-02 15:43:09.190169",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Delete route

Example

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/routes/b972b61c-59d2-4217-8fbb-a32304be5c3b?token=<YOUR_AUTH_TOKEN>'

{
    "id": "b972b61c-59d2-4217-8fbb-a32304be5c3b",
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 1,
    "target": "+82",
    "tm_create": "2022-11-02 15:36:32.174346",
    "tm_update": "2022-11-02 15:44:09.686612",
    "tm_delete": "2022-11-02 15:44:09.686612"
}

Route

Overview

How Routes Work

Route Failover

Dynamic Routing Decisions

Route Configuration

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Route

Route

example

Tutorial

Get list of routes

Get detail of route

Create a new route

Update route

Delete route