Route

Define call routing rules that control how inbound and outbound calls are directed to their destinations.

Overview

Note

AI Context

Complexity: Low
Cost: Free. Routes are configuration rules with no per-unit charges.
Async: No. POST /routes returns immediately with the created route.

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

Note

AI Implementation Hint

A customer_id of 00000000-0000-0000-0000-000000000001 is the system-wide default. Routes with this customer ID apply to all customers unless a customer-specific route exists. A target of "all" matches every destination. For country-specific routing, use the E.164 country code prefix (e.g., +82 for South Korea, +1 for US/Canada).

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 (UUID): The route’s unique identifier. Returned when creating via POST /routes or listing via GET /routes.
customer_id (UUID): The customer this route applies to. Obtained from GET /customers. The special value 00000000-0000-0000-0000-000000000001 means this route applies to all customers (system default).
provider_id (UUID): The provider used for outbound calls on this route. Obtained from the id field of GET /providers.
priority (Integer): Route priority for failover ordering. Lower values are attempted first (1 = highest priority). Multiple routes with different priorities enable automatic failover.
target (String): Target country code prefix for destination matching (e.g., +82, +1). Set to "all" to match every destination.
tm_create (string, ISO 8601): Timestamp when the route was created.
tm_update (string, ISO 8601): Timestamp of the last update to any route property.
tm_delete (string, ISO 8601): Timestamp when the route 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 route has not been deleted.

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

Before working with routes, you need:

An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
A provider ID (UUID). Obtain from GET /providers or create one via POST /providers.
A customer ID (UUID). Obtain from GET /customers. Use 00000000-0000-0000-0000-000000000001 for system-wide default routes.

Note

AI Implementation Hint

Routes are evaluated by priority (lower number = higher priority). To set up failover, create multiple routes for the same customer_id and target with different provider_id values and incrementing priority values (e.g., 1, 2, 3). If the first provider fails, VoIPBIN automatically tries the next route.

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/routes/b972b61c-59d2-4217-8fbb-a32304be5c3b?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": 2,
        "target": "+82"
    }'

{
    "id": "b972b61c-59d2-4217-8fbb-a32304be5c3b",
    "customer_id": "00000000-0000-0000-0000-000000000001",
    "provider_id": "4dbeabd6-f397-4375-95d2-a38411e07ed1",
    "priority": 2,
    "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