# Routing groups API

A routing group combines several purchased routes behind one tech prefix (444 and three digits) and chooses a route for each call or message by least cost, failover order or weighted load balancing, with optional rules per destination or caller prefix.

## List routing groups

`POST https://apiv2.telecomsxchange.com/buyers/rg/list`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#list-routing-groups

Returns all your routing groups with their tech prefix, policy, hunt-stop codes and routes (`routing_group_entries`). Voice groups also include their routing rules (`routing_rules`), each with its own routes. Every other routing-group call uses the IDs returned here. Free.

> `rg_data` is a route's position in an `order` group (1 is tried first) or its weight in a `weight` group; `lcr` groups ignore it. Routes are sorted by position for `order`, by weight (highest first) for `weight`, otherwise by seller and route name. `smpp` is 1 for SMS groups, which have no `routing_rules`. `entries` and `rules` are counts; other values are strings.

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/list"
```

### Response: Example

```json
{
  "status": "success",
  "routing_groups": [
    {
      "i_routing_group": "311",
      "name": "UK mobile blend",
      "policy": "order",
      "hunt_stop_codes": "486,404,604",
      "tech_prefix": "444517#",
      "i_customer": "1042",
      "smpp": "0",
      "created": "2026-03-04 10:12:55",
      "entries": 2,
      "seller_names": "NorthwindVoice, Anonymous",
      "rules": 1,
      "routing_group_entries": [
        {
          "name": "UK Mobile CLI",
          "rg_data": "1",
          "i_routing_group_entry": "9021",
          "connection_name": "NorthwindVoice / UK Mobile CLI",
          "i_connection": "5531",
          "created": "2026-03-04 10:14:02",
          "i_vendor": "87",
          "anonymous": "0"
        },
        {
          "name": "Premium UK",
          "rg_data": "2",
          "i_routing_group_entry": "9022",
          "connection_name": "Anonymous / Premium UK",
          "i_connection": "5610",
          "created": "2026-03-04 10:14:40",
          "anonymous": "1"
        }
      ],
      "routing_rules": [
        {
          "i_routing_group": "318",
          "name": "",
          "policy": "lcr",
          "hunt_stop_codes": "",
          "tech_prefix": "",
          "i_customer": "1042",
          "smpp": "0",
          "created": "2026-03-05 08:01:13",
          "subrule_order": "1",
          "subrule_cld_prefix": "447",
          "subrule_cli_prefix": "",
          "entries": 1,
          "seller_names": "NorthwindVoice",
          "rules": 0,
          "routing_group_entries": [
            {
              "name": "UK Mobile CLI",
              "rg_data": "1",
              "i_routing_group_entry": "9030",
              "connection_name": "NorthwindVoice / UK Mobile CLI",
              "i_connection": "5531",
              "created": "2026-03-05 08:02:40",
              "i_vendor": "87",
              "anonymous": "0"
            }
          ]
        }
      ]
    }
  ]
}
```

## Create a routing group

`POST https://apiv2.telecomsxchange.com/buyers/rg/add`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#create-a-routing-group

Creates a voice or SMS routing group and gives it a unique tech prefix: 444, three random digits and #. Send traffic with that prefix to route it through the group. Voice groups start with hunt-stop codes 486,404,604. The response returns the new group's ID; call List routing groups to read its tech prefix. Free.

> Always send one of `lcr`, `order` or `weight` as `policy`; the value is stored as sent.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `name` | string | body | yes | Group name, unique among your routing groups, up to 128 characters. Example `UK mobile blend`. |
| `policy` | string | body | yes | How a route is chosen: `lcr` cheapest first, `order` a fixed failover order, `weight` weighted load balancing. One of `lcr`, `order`, `weight`. Example `order`. |
| `smpp` | integer | body | no | 0 for a voice group, 1 for an SMS group. One of `0`, `1`. Default `0`. Example `0`. |

### Errors

| Message | When |
|---|---|
| `Please enter a name for the routing group.` | `name` is missing or blank |
| `A routing group with this name already exists - choose a different name.` | you already have a group with this name |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/add" \
  -d name='UK mobile blend' \
  -d policy=order \
  -d smpp=0
```

### Response: Example

```json
{
  "status": "success",
  "message": "Routing Group has been added",
  "i_routing_group": 311
}
```

## Update a routing group

`POST https://apiv2.telecomsxchange.com/buyers/rg/edit/{id}`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#update-a-routing-group

Renames a routing group and changes its policy and hunt-stop codes. Switching to `order` numbers the group's routes 1, 2, 3, ...; switching to `weight` sets every route's weight to 1. Free.

> Send `hunt_stop_codes` on every edit: omitting it clears the list. If `id` is a routing rule, this call behaves like Update a routing rule.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing group ID (`i_routing_group`). Example `311`. |
| `name` | string | body | yes | Group name, unique among your routing groups. Send the current name to keep it. Example `UK mobile blend`. |
| `policy` | string | body | no | New policy. A missing or unknown value keeps the current policy. One of `lcr`, `order`, `weight`. Example `weight`. |
| `hunt_stop_codes` | string | body | no | Comma-separated SIP response codes from 400 to 699 that stop failover to the next route. Other values are dropped, and the list is de-duplicated and sorted. Example `404,486,603`. |

### Errors

| Message | When |
|---|---|
| `Routing Group not found` | `id` is not one of your routing groups or rules |
| `Please enter a name for the routing group.` | `name` is missing or blank |
| `A routing group with this name already exists — choose a different name.` | another of your groups has this name |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/edit/311" \
  -d name='UK mobile blend' \
  -d policy=weight \
  -d hunt_stop_codes='404,486,603'
```

### Response: Example

```json
{
  "status": "success",
  "message": "Routing group updated successfully"
}
```

## Add a routing rule

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/add_rule`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#add-a-routing-rule

Adds a routing rule to a voice routing group. A rule matches calls by destination (CLD) prefix, caller (CLI) prefix or both, and routes them through its own routes and policy. Rules are checked in order and a new rule goes to the bottom. It starts with policy `lcr` and no routes; add routes with Add a route to a group, using the rule's ID. Free.

> The returned `i_routing_group` is the new rule's ID. Use it as `{id}` when adding routes to the rule and in Update a routing rule.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | ID of the parent voice routing group. Example `311`. |
| `subrule_cld_prefix` | string | body | no | Destination prefix to match, digits only, up to 15. Send at least one of the two prefixes. Example `447`. |
| `subrule_cli_prefix` | string | body | no | Caller ID prefix to match, digits only, up to 15, or `EMPTY` to match calls that have no caller ID. |

### Errors

| Message | When |
|---|---|
| `Routing Group not found` | `id` is not one of your voice routing groups (SMS groups and rules can't have rules) |
| `Enter at least one prefix: CLD (destination) or CLI (caller).` | both prefixes are missing or empty |
| `CLD prefix may contain digits only.` | `subrule_cld_prefix` contains a non-digit |
| `CLI prefix may contain digits only, or the special value EMPTY.` | `subrule_cli_prefix` is neither digits nor EMPTY |
| `A prefix can be at most 15 digits.` | either prefix is longer than 15 characters |
| `A rule with this CLD/CLI prefix already exists in this group.` | the group already has a rule with the same CLD and CLI pair |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/add_rule" \
  -d subrule_cld_prefix=447 \
  -d subrule_cli_prefix=''
```

### Response: Example

```json
{
  "status": "success",
  "message": "Routing Rule has been added",
  "i_routing_group": 318
}
```

## Update a routing rule

`POST https://apiv2.telecomsxchange.com/buyers/rg/rule/{id}/edit`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#update-a-routing-rule

Changes a routing rule's CLD and CLI prefixes, policy and hunt-stop codes. Switching to `order` numbers the rule's routes 1, 2, 3, ...; switching to `weight` sets their weights to 1. Free.

> Send both prefixes and `hunt_stop_codes` on every edit: any of them you omit is cleared. If `id` is a top-level group, this call behaves like Update a routing group and requires `name`.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing rule ID. Example `318`. |
| `subrule_cld_prefix` | string | body | no | Destination prefix, digits only, up to 15. Send at least one of the two prefixes. Example `4477`. |
| `subrule_cli_prefix` | string | body | no | Caller ID prefix, digits only or `EMPTY`, up to 15. |
| `policy` | string | body | no | New policy. A missing or unknown value keeps the current policy. One of `lcr`, `order`, `weight`. Example `order`. |
| `hunt_stop_codes` | string | body | no | Comma-separated SIP response codes from 400 to 699 that stop failover. |

### Errors

| Message | When |
|---|---|
| `Routing Group not found` | `id` is not one of your rules or groups |
| `Enter at least one prefix: CLD (destination) or CLI (caller).` | both prefixes are missing or empty |
| `CLD prefix may contain digits only.` | `subrule_cld_prefix` contains a non-digit |
| `CLI prefix may contain digits only, or the special value EMPTY.` | `subrule_cli_prefix` is neither digits nor EMPTY |
| `A prefix can be at most 15 digits.` | either prefix is longer than 15 characters |
| `A rule with this CLD/CLI prefix already exists in this group.` | another rule in the same group has this CLD and CLI pair |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/rule/318/edit" \
  -d subrule_cld_prefix=4477 \
  -d subrule_cli_prefix='' \
  -d policy=order
```

### Response: Example

```json
{
  "status": "success",
  "message": "Routing Rule updated successfully"
}
```

## Delete a routing rule

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/rule/{rule_id}/delete`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#delete-a-routing-rule

Deletes a routing rule and its route list, and moves the rules below it up one place. Your purchased routes are not affected. Free.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Parent routing group ID. Example `311`. |
| `rule_id` | integer | path | yes | ID of the rule to delete. Example `318`. |

### Errors

| Message | When |
|---|---|
| `Rule not found` | `rule_id` is not one of your rules in group `id` |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/rule/318/delete"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Rule has been deleted"
}
```

## Move a routing rule up

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/rule/{rule_id}/up`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#move-a-routing-rule-up

Moves a routing rule one place up in its group's evaluation order, swapping it with the rule above. Free.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Parent routing group ID. Example `311`. |
| `rule_id` | integer | path | yes | ID of the rule to move. Example `319`. |

### Errors

| Message | When |
|---|---|
| `This rule is on top` | the rule is already first |
| `Rule not found` | `rule_id` is not one of your rules in group `id` |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/rule/319/up"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Routing Rule moved up"
}
```

## Move a routing rule down

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/rule/{rule_id}/down`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#move-a-routing-rule-down

Moves a routing rule one place down in its group's evaluation order, swapping it with the rule below. Free.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Parent routing group ID. Example `311`. |
| `rule_id` | integer | path | yes | ID of the rule to move. Example `318`. |

### Errors

| Message | When |
|---|---|
| `This rule is on the bottom` | the rule is already last |
| `Rule not found` | `rule_id` is not one of your rules in group `id` |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/rule/318/down"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Routing Rule moved down"
}
```

## Add a route to a group

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/entry/add/{i_connection}`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#add-a-route-to-a-group

Adds one of your purchased routes to a routing group or rule. In an `order` group the route goes to the end of the failover list; in a `weight` group it starts with weight 1. Returns the new entry ID, used by the remove, move and set-weight calls. Adding a route to a group costs nothing.

> Add voice routes to voice groups and SMS routes to SMS groups; the route type is not checked. If `id` is not one of your groups or rules, the response is empty.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing group or routing rule ID. Example `311`. |
| `i_connection` | integer | path | yes | ID of a route purchased on any of your accounts, from List interconnects. Example `5531`. |

### Errors

| Message | When |
|---|---|
| `i_connection expects integer` | the route ID is not a number |
| `You can only add routes you have purchased in the Market.` | the route is not purchased on any of your accounts |
| `This route is already in this group.` | the route is already in this group or rule |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/entry/add/5531"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Route added to this group",
  "i_routing_group_entry": 9021
}
```

## Remove a route from a group

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/entry/{entry_id}/remove`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#remove-a-route-from-a-group

Removes a route from a routing group or rule. In an `order` group, the routes below it move up one place. Your purchased route is not affected. Free.

> Pass the group or rule that contains the entry as `id`; the entry is removed even if it belongs to another of your groups. If `id` is not one of your groups or rules, the response is empty.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing group or routing rule ID that contains the entry. Example `311`. |
| `entry_id` | integer | path | yes | Entry ID (`i_routing_group_entry`), from List routing groups. Example `9022`. |

### Errors

| Message | When |
|---|---|
| `Entry not found` | `entry_id` is not an entry in any of your routing groups |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/entry/9022/remove"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Route removed from this group"
}
```

## Move a route up

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/entry/{entry_id}/up`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#move-a-route-up

Moves a route one place up in the failover order of an `order` group or rule, swapping it with the route above. Free.

> If `id` is not one of your groups or rules, the response is empty.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing group or routing rule ID. Example `311`. |
| `entry_id` | integer | path | yes | Entry ID to move. Example `9022`. |

### Errors

| Message | When |
|---|---|
| `up action only supported for ordered policy` | the group's policy is not `order` |
| `This rule is on top` | the route is already first |
| `entry not found` | `entry_id` is not an entry in your routing groups |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/entry/9022/up"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Route moved up"
}
```

## Move a route down

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/entry/{entry_id}/down`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#move-a-route-down

Moves a route one place down in the failover order of an `order` group or rule, swapping it with the route below. Free.

> If `id` is not one of your groups or rules, the response is empty.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing group or routing rule ID. Example `311`. |
| `entry_id` | integer | path | yes | Entry ID to move. Example `9021`. |

### Errors

| Message | When |
|---|---|
| `down action only supported for ordered policy` | the group's policy is not `order` |
| `This entry is on the bottom` | the route is already last |
| `entry not found` | `entry_id` is not an entry in your routing groups |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/entry/9021/down"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Route moved down"
}
```

## Set a route's weight

`POST https://apiv2.telecomsxchange.com/buyers/rg/{id}/entry/{entry_id}/set_weight/{weight}`

Reference: https://help.telecomsxchange.com/reference/routing-groups/#set-a-route-s-weight

Sets the load-balancing weight of a route in a `weight` group or rule. Each route receives a share of traffic equal to its weight divided by the sum of all weights in the group. Free.

> If `id` is not one of your groups or rules, the response is empty.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | Routing group or routing rule ID. Example `311`. |
| `entry_id` | integer | path | yes | Entry ID (`i_routing_group_entry`). Example `9021`. |
| `weight` | integer | path | yes | Whole number from 1 to 100. Example `70`. |

### Errors

| Message | When |
|---|---|
| `Weight must be a whole number between 1 and 100.` | `weight` is not a whole number from 1 to 100 |
| `set_weight action only supported for weighted policy` | the group's policy is not `weight` |
| `entry not found` | `entry_id` is not an entry of group `id` |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/rg/311/entry/9021/set_weight/70"
```

### Response: Example

```json
{
  "status": "success",
  "message": "Weight updated successfully"
}
```