How to Order DIDs

This guide describes how to place an order. You should first read through the Overview to ensure you understand how to use our API.

Choosing a Location

To place your order you will need a location handle where you wish to order DIDs. For more information see the Checking Our Stock guide.

Assigning DIDs to a Trunk

When ordering DIDs you need to provide an ID for the Trunk they are to be assigned to. For more information see our Trunks, Channels, and DIDs guide.

Creating a Cart

The first step is to create a cart for your order. You will need to know your account number which you can get using the /accounts endpoint. You can then issue 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/ACCOUNT_NUMBER/carts

{
  "cart_id" : "114009",
  "cart_items" : [],
  "cart_status_handle" : "OPEN",
  "created" : "2016-12-15T16:48:03+0000",
  "recurring_cost" : 0,
  "total_cost" : 0,
  "total_items" : 0
  }
}

Creating Order Items

Next you will use the cart_id returned from the previous request to create one or more order items with the /accounts/{account_number}/carts/{cart_id}/items endpoint, providing a location handle.

Note: On sandbox only orders for DIDs in the following locations will complete successfully: MEXICO_CITY_MX, MEXICALI_686_MX, SAO_PAULO_BR, SANTOS_BR, BELO_HORIZONTE_BR, CORRIENTES_3794_AR

curl --include --request POST \
  --header 'Accept: application/json' \
  --header 'X-Auth-Token: YOUR_SANDBOX_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "item" : {
      "item_type" : "LOCATION",
      "location_handle" : "MEXICO_CITY_MX",
      "did_type_handle" : "STANDARD",
      "trunk_id" : 1,
      "quantity" : 1
    }
  }' \
  https://sandbox.api.magictelecom.com/accounts/ACCOUNT_NUMBER/carts/CART_ID/items

Submitting Your Order

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" : "1234567"
    }
  }' \
  https://sandbox.api.magictelecom.com/accounts/ACCOUNT_NUMBER/carts/CART_ID/checkout

{
  "_items" : [
    {
      "_caller_location" : {
        "address" : "6314 Kingspointe Parkway",
        "city" : "Orlando",
        "country" : "US",
        "name" : "Magic Telecom",
        "postal_code" : "32819",
        "region" : "FL",
        "unit_number" : "1",
        "unit_type" : "SUIT"
      },
      "country_code" : "MX",
      "did_type_handle" : "STANDARD",
      "item_id" : "577",
      "item_type" : "LOCATION",
      "location_handle" : "MEXICO_CITY_MX",
      "quantity" : 1,
      "region_code" : "",
      "status" : "FULFILL_ORDER",
      "trunk_id" : 1,
      "trunk_number" : 1
    },
    {
      "_caller_location" : {
        "address" : "6314 Kingspointe Parkway",
        "city" : "Orlando",
        "country" : "US",
        "name" : "Magic Telecom",
        "postal_code" : "32819",
        "region" : "FL",
        "unit_number" : "1",
        "unit_type" : "SUIT"
      },
      "_phone_number" : "52551174342",
      "did_type_handle" : "STANDARD",
      "item_id" : "579",
      "item_type" : "DID",
      "status" : "FULFILL_ORDER",
      "trunk_id" : 1,
      "trunk_number" : 1
    }
  ],
  "account_number" : "77",
  "created" : "2016-12-15T17:07:31+0000",
  "external_order_reference" : "1234567",
  "order_id" : "575",
  "status" : "PROCESSING"
}

Checking the Status of Your Order

You can use the order_id from the previous request to check on the status of your order using the /accounts/{account_number}/orders/{order_id} endpoint:

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

{
  "code" : 200,
  "data" : {
    "_items" : [
      {
        "_caller_location" : {
          "address" : "6314 Kingspointe Parkway",
          "city" : "Orlando",
          "country" : "US",
          "name" : "Magic Telecom",
          "postal_code" : "32819",
          "region" : "FL",
          "unit_number" : "1",
          "unit_type" : "SUIT"
        },
        "_phone_number" : [
          "52553492768"
        ],
        "country_code" : "MX",
        "did_type_handle" : "STANDARD",
        "item_id" : "577",
        "item_type" : "LOCATION",
        "location_handle" : "MEXICO_CITY_MX",
        "quantity" : 1,
        "region_code" : "",
        "status" : "COMPLETE",
        "trunk_id" : 1,
        "trunk_number" : 1
      }
    ],
    "account_number" : "77",
    "created" : "2016-12-15T17:07:31+0000",
    "external_order_reference" : "1234567",
    "order_id" : "575",
    "status" : "COMPLETE"
  }
}

Here you can see that the order by location has completed and we were assigned the number 52553492768.

Listing Your DIDs

To list the DIDs on your account use the /accounts/{account_number}/dids endpoint:

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

{
  "code" : 200,
  "data" : {
    "limit" : 10,
    "page" : 1,
    "results" : [
      {
        "_country" : {
          "dial_code" : 52,
          "handle" : "MEXICO",
          "iso2" : "MX",
          "iso3" : "MEX",
          "name" : "Mexico"
        },
        "_rates" : {
          "STANDARD" : {
            "initial_cost" : "5.00",
            "monthly_cost" : "5.00"
          }
        },
        "_routing_logic" : {
          "logic" : "single-endpoint"
        },
        "_status" : {
          "handle" : "ASSIGNED"
        },
        "active" : true,
        "channels" : 2,
        "location_handle" : "MEXICO_CITY_MX",
        "location_name" : "Mexico City",
        "order_ref" : "1234567",
        "phone_number" : "52553492768",
        "prefix" : "5255",
        "sip_endpoint_uri" : "1.2.3.4",
        "trunk_id" : 1
      }
    ],
    "total" : 1
  }
}