Trunks, Channels, and DIDs

This guide introduces the concepts of Trunks, Channels, and DIDs. You should first read through the Overview to ensure you understand how to use our API.

Trunks and Channels

Before you can order a DID you must have a Trunk to assign it to. A Trunk holds the default settings for any DIDs assigned to it—such as the SIP endpoint incoming calls are sent to—and also how many Channels are available. The number of Channels available determines how many concurrent phone calls can be made to the DIDs in a Trunk.

Many customers prefer to buy and configure Trunks manually through the Magic Telecom website and to just use the API for managing DIDs. However, you have full control over your account’s Trunks through the API as outlined below.

Trunk Zones

There are several different Trunk Zones available. You can assign a DID from any country to a World Wide Trunk, but these Trunks are generally more expensive. You may be able to save money by ordering a Trunk in a different Zone.

To see the different types of Trunks and their pricing use the /dids/products/trunks endpoint:

curl --include --get \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  https://sandbox.api.magictelecom.com/dids/products/trunks

{
  "data" : {
    "results" : [
      {
        "name" : "World",
        "handle" : "WORLD_WIDE",
        "trunk_zone_handle" : "WORLD_WIDE",
        "_rates" : {
          "initial_cost" : "22.00",
          "monthly_cost" : "17.20"
        }
      },
      ...
    ],
    "total" : 4,
    "limit" : 10,
    "page" : 1
  },
  "code" : 200
}

To see which countries a Trunk Zone can handle DIDs in, use the /dids/products/trunks/countries endpoint. You can use the country_iso2 or trunk_handle filters to limit your search:

curl --include --get \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  --data 'filter=country_iso2::SG'
  https://sandbox.api.magictelecom.com/dids/products/trunks/countries

{
  "data" : {
    "results" : [
      {
        "_country" : {
          "dial_code" : 65,
          "handle" : "SINGAPORE",
          "iso2" : "SG",
          "iso3" : "SGP",
          "name" : "Singapore"
        },
        "_trunk_zone" : {
          "handle" : "WORLD_WIDE",
          "name" : "World Wide"
        }
      },
      {
        "_country" : {
          "dial_code" : 65,
          "handle" : "SINGAPORE",
          "iso2" : "SG",
          "iso3" : "SGP",
          "name" : "Singapore"
        },
        "_trunk_zone" : {
          "handle" : "ZONE_C",
          "name" : "Zone C"
        }
      }
    ],
    "total" : 2,
    "limit" : 10,
    "page" : 1
  },
  "code" : 200
}

In the above example you can see that you must have a World Wide or Zone C Trunk available to buy Singapore DIDs.

Ordering a Trunk

To order a Trunk you will first need to create a cart. You will need your account number which you can get using the /accounts endpoint, which you can then use in a POST to the /accounts/{account_number}/carts endpoint:

curl --include --request POST \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  https://sandbox.api.magictelecom.com/accounts//carts

{
  "cart_id" : "114007",
  "cart_items" : [],
  "cart_status_handle" : "OPEN",
  "created" : "2016-12-14T20:53:13+0000",
  "recurring_cost" : 0,
  "total_cost" : 0,
  "total_items" : 0
  }
}

Next, create a TRUNK order item using the cart_id from the previous request with a POST to the /accounts/{account_number}/carts/{cart_id}/items endpoint:

curl --include --request POST \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "item" : {
      "item_type" : "TRUNK",
      "channels" : 2,
      "trunk_handle" : "WORLD_WIDE",
      "sip_uri" : "1.2.3.4"
    }
  }' \
  https://sandbox.api.magictelecom.com/accounts//carts/CART_ID/items

Now that your cart is populated, submit it to checkout using a POST to the /accounts/{account_number}/carts/{cart_id}/checkout endpoint. You will need to provide a unique external_order_reference value which is your own order ID for tracking in your system:

curl --include --request POST \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "checkout" : {
      "external_order_reference" : "123456"
    }
  }' \
  https://sandbox.api.magictelecom.com/accounts//carts/CART_ID/checkout

{
  "_items" : [
    {
      "channels" : 2,
      "item_id" : "575",
      "item_type" : "TRUNK",
      "sip_uri" : "1.2.3.4",
      "status" : "COMPLETE",
      "trunk_handle" : "WORLD_WIDE",
      "trunk_id" : 1
    }
  ],
  "account_number" : "77",
  "created" : "2016-12-14T21:27:31+0000",
  "external_order_reference" : "123456",
  "order_id" : "573",
  "status" : "COMPLETE"
}

Listing Your Trunks

To list your existing Trunks use a GET request to the /accounts/{account_number}/trunks endpoint:

curl --include --get \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  https://sandbox.api.magictelecom.com/accounts//trunks

{
  "data" : {
    "results" : [
      {
        "_routing_logic" : {
          "logic" : "single-endpoint"
        },
        "active" : true,
        "channels" : 2,
        "default" : true,
        "description" : "",
        "did_active" : 0,
        "did_inactive" : 0,
        "id" : 1,
        "sip_endpoint_uri" : "1.2.3.4",
        "trunk_handle" : "WORLD_WIDE",
        "trunk_name" : "World Wide"
      }
    ],
    "total" : 1,
    "limit" : 10,
    "page" : 1
  },
  "code" : 200
}

Notes

Once you have a Trunk, either ordered through the API or purchased through the Magic Telecom website, you are ready to start buying DIDs. Check our How to Order DIDs guide for more information.

API Documentation

How to Guides

Resources