NAV Navbar
cURL Ruby Python jQuery Node.js Go Swift Java C# PHP

Overview

About

The IDT Express API is built to allow our users seamless integration into their back office systems. For v1.0 of our APIs posted here, we support phone number (DID) purchasing. With this API, you will be able to view what locations we offer, buy numbers, and manage the IDT Express numbers that you own. Additional functionality is being added monthly, so please check back often.

For access to this API, please contact your IDT Express Account Manager.

Once you have access, your API credentials will be shared and managed through the IDT Express Portal.

Environments

Once you have credentials to the API, you will be able to access both our Sandbox and Live environments.

Here are the servers for each of the environments:

Environment Server
Sandbox https://sandbox-api.idtexpress.com
Live https://api.idtexpress.com

Sandbox

The Sandbox environment is the environment that you will use when testing our APIs or developing your application.

The data used for the Sandbox environment is all fake. For example, the phone numbers returned from the Get Numbers endpoint are not your phone numbers. The orders created with the Create Order endpoint are not creating orders on your production account.

No API calls made here affect your account. The Sandbox environment is only to be used to test our APIs or develop your application.

Live

The Live environment is the real, production environment. API calls in this environment affect your production account.

For example, ordering a new phone number with the Create Order endpoint will generate an order in your production account and use the funds necessary to purchase that number.

Authentication

To access our APIs, you will need to use your account's API Key and the API Secret for the environment you are calling. Log in to the IDT Express Portal to view your account's API key and each environment's API Secret.

You will need to pass both the API Key and the environment's API Secret in the request headers.

Header Name Value
x-api-key The account's API Key
x-api-secret The environment's API Secret

Example: curl -H 'x-api-key: 1234567890' \ -H 'x-api-secret: 10987654321' \ 'https://api.idtexpress.com/v1/dids/coverage/countries'

HTTP Status Codes, Error Responses and Codes

Successful API responses will either return an HTTP status code of 200 or 201.

Application or client level errors will return 4xx codes.

Common HTTP Status Codes

Status Code Description
200 Successful response
201 Resource created
403 Access is Denied. You may no longer have access to the API or have incorrect credentials set. Reach out to your account manager
404 The endpoint you are using does not exist. Check the url that you are using
422 Validation error. The data that you are sending is incorrect. Check the response body for more details
429 You have either been throttled or you reached your request limit. Reach out to your account manager

Error object

For 4xx HTTP responses, we will return an object that will help identify what the issues are.

Some Example Responses
----------------------

A response like this would be returned if there were not enough funds available to complete what was ordered:
{
   "status":422,
   "api_request_id":"f5263b41-6935-4823-b118-72c759645dfc",
   "errors":[
      {
         "code":3001,
         "title":"Insufficient Funds",
         "detail":"Insufficient Funds (cost: 6.39, account balance: 0.31)",
         "source":"/"
      }
   ]
}

In this example, the quantity field for the order item did not pass validation:
{
   "status"=>422, 
   "api_request_id"=>"a171cfe8-a18c-49cc-be94-41511eaac645", 
   "errors"=>[
      {
         "code": 1002,
         "title": "Invalid Field", 
         "detail": "Quantity must be greater than 0", 
         "field": "quantity", 
         "source": "/order_items/0/quantity"         
      }
   ]
}
Attribute Description Required
status The HTTP status code applicable to this problem expressed as an integer Yes
errors An array of Error objects that will always have at least 1 Error object Yes
api_request_id A system generated string that can help us troubleshoot the error Yes

The Error object returned in the errors array looks like the following:

Attribute Description Required
code An application-specific code representing the type of problem encountered Yes
title A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem Yes
detail A human-readable explanation specific to this occurrence of the problem Yes
field The field or parameter name that is causing the issue. This field will only be present if applicable No
source a JSON Pointer [RFC6901] to the associated entity in the request body. This field will only be present if the request has a JSON body, and a valid pointer can be generated. Error responses from GET/DELETE requests will never return this field No

Here is a list of common errors codes that you may run into:

Code Title Description
1000 Invalid Request Used when we have not defined a more specific error code
1001 Required Field Missing A required field or parameter is missing
1002 Invalid Field A validation error on a field or parameter
1003 Resource Not Found A request to a resource or endpoint that does not exist
2000 Access Denied Request access is denied
2001 Quota Exceeded Quota exceeded allotment for your account. Please contact your Account Manager for more information
2002 Throttled Throttling request limit exceeded for your account. Please contact your Account Manager for more information
3000 DIDs Feature Not Enabled Your account no longer has access to purchase DIDs/numbers
3001 Insufficient Funds Insufficient funds available on the account to complete the requested order
4000 Toll-Free Number Not Offered A request to browse Toll-Free numbers was not allowed because Toll-Free numbers are not available in the Region or Country
4001 Number Not Found A action was attemped on a number that does not belong to the Account or the number is not found
4002 Region Not Offered A request to browse for DID Groups in a region that is not offered
4003 Country Not Offered A request to browse for DID Groups in a country that is not offered
4004 Invalid DID Group A request to order from a DID Group that is not offered

API Reference

This section lists all of the endpoints for the IDT Express API.

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

You can replace **** with the your API Key and environment's API Secret in all examples.

Get Countries

Retrieves all of the countries that you can purchase phone numbers from.

Code samples

curl -v \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/coverage/countries"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/coverage/countries")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("GET", "/v1/dids/coverage/countries", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/coverage/countries",
   "method": "GET",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'GET',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/coverage/countries',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/coverage/countries"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/coverage/countries")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/coverage/countries")
   .method("GET", null)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/coverage/countries");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/coverage/countries",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

GET /v1/dids/coverage/countries

Example responses

200 Response

{
  "countries": [
    {
      "name": "Poland",
      "iso": "PL",
      "has_regions": false,
      "supports_toll_free": false
    },
    {
      "name": "Puerto Rico",
      "iso": "PR",
      "has_regions": false,
      "supports_toll_free": false
    },
    {
      "name": "USA",
      "iso": "US",
      "has_regions": true,
      "supports_toll_free": true
    }
  ],
  "meta": {
    "total": 3
  }
}

Response Schema

Status Code 200

  • countries array of objects

    • countries[].name boolean

      Country name

    • countries[].iso string

      2 character ISO 3166-1 alpha-2 country code

    • countries[].has_regions boolean

      Flag to indicate if the country supports regions

    • countries[].supports_toll_free boolean

      Flag to indicate if the country supports toll-free numbers


  • meta object

    • meta.total integer

      The total number of countries returned

Get Regions

Returns all the regions for a specific country. Currently this endpoint only supports US and Canada.

Code samples

curl -v \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("GET", "/v1/dids/coverage/countries/CA/regions", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions",
   "method": "GET",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'GET',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/coverage/countries/CA/regions',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions")
   .method("GET", null)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/coverage/countries/CA/regions",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

GET /v1/dids/coverage/countries/{country_iso}/regions

Parameters

Name In Type Required Description
country_iso path string true 2 letter country code. See Get Countries

Example responses

200 Response

{
  "regions": [
    {
      "name": "Alberta",
      "code": "CA-AB"
    },
    {
      "name": "British Columbia",
      "code": "CA-BC"
    },
    {
      "name": "Manitoba",
      "code": "CA-MB"
    },
    {
      "name": "Newfoundland and Labrador",
      "code": "CA-NF"
    },
    {
      "name": "Nova Scotia",
      "code": "CA-NS"
    },
    {
      "name": "Ontario",
      "code": "CA-ON"
    },
    {
      "name": "Quebec",
      "code": "CA-QC"
    }
  ],
  "meta": {
    "total": 7
  }
}

Response Schema

Status Code 200

  • regions array of objects

    • regions[].name string

      The name of the region

    • regions[].code string

      The ISO 3166-2 code that uniquely identifies the region

  • meta object

    • meta.total integer

      The total number of regions returned

Get DID Groups

Returns a list of DID Groups that are available based on the given query parameters.

All phone numbers in our system are associated with a DID Group. A DID Group is the location, region, and country that the number belongs to.

This endpoint also returns the pricing information for each DID Group, such as monthly and setup fees.

You will need to use the DID Group ID to order phone numbers in Create Order.

Code samples

curl -v \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("GET", "/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK",
   "method": "GET",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'GET',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK")
   .method("GET", null)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/coverage/did_groups?country_iso=US&region_code=US-AK",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

GET /v1/dids/coverage/did_groups

Parameters

Name In Type Required Description
country_iso query string true 2 letter country code. See Get Countries
region_code query string false Region code (example format: "US-AK"). This field is required for countries that support regions, such as US and CA. Exception: DO NOT include region code if you are browsing for Toll-Free numbers. See Get Regions
toll_free query boolean false Indicates if you are looking for Toll-Free numbers. If you are looking for Toll-Free numbers in US or Canada, do not pass in the region code

Example responses

200 Response

{
   "did_groups":[
      {
         "id":2992,
         "name":"FANWOOD (908) 312",
         "country_calling_code":"1",
         "area_code":"908",
         "nxx":"312",
         "toll_free":false,
         "country":{
            "name":"USA",
            "iso":"US",
            "has_regions":true,
            "supports_toll_free":true
         },
         "region":{
            "name":"Alaska",
            "code":"US-AK"
         },
         "fees":{
            "setup_fee":"0.00",
            "monthly_fee":"5.00",
            "per_minute_rate":"4.7354"
         }
      },
      {
         "id":4884,
         "name":"Monroe (318) 450",
         "country_calling_code":"1",
         "area_code":"318",
         "nxx":"450",
         "toll_free":false,
         "country":{
            "name":"USA",
            "iso":"US",
            "has_regions":true,
            "supports_toll_free":true
         },
         "region":{
            "name":"Alaska",
            "code":"US-AK"
         },
         "fees":{
            "setup_fee":"0.00",
            "monthly_fee":"5.00",
            "per_minute_rate":"4.7354"
         }
      }
   ],
   "meta":{
      "total":2
   }
}

Response Schema

Status Code 200

  • did_groups array of objects

    • did_groups[].id string

      The unique identifier for the DID Group. Use this when placing an order

    • did_groups[].name string

      The name of DID Group

    • did_groups[].country_calling_code string

      The international calling code

    • did_groups[].area_code string

      The area code/NPA

    • did_groups[].nxx string

      The NXX. Only applicable for North American numbers

    • did_groups[].toll_free boolean

      Indicates if the DID Group is Toll-Free

    • did_groups[].country object

      Object representing the country the DID Group belongs to

      • did_groups[].country.name boolean

        Country name

      • did_groups[].country.iso string

        2 character ISO 3166-1 alpha-2 country code

      • did_groups[].country.has_regions boolean

        Flag to indicate if the country supports regions

      • did_groups[].country.supports_toll_free boolean

        Flag to indicate if the country supports toll-free numbers


    • did_groups[].region object

      Object representing the region the DID Group belongs to. This will only be present if there is a region

      • did_groups[].region.name string

        The name of the region

      • did_groups[].region.code string

        The ISO 3166-2 code that uniquely identifies the region

    • did_groups[].fees object

      Fees associated with this DID Group. These values are in currency of your account

      • did_groups[].fees.setup_fee string

        Setup fee

      • did_groups[].fees.monthly_fee string

        The number's monthly fee

      • did_groups[].fees.per_minute_rate string

        The per minute rate

  • meta object

    • meta.total integer

      The total number of DID Groups returned

Create Order

Creates an order for phone numbers. Currently, we only support placing an order by DID Group ID and quantity. You can get the DID Group ID from Get DID Groups.

To create an order, add an order item with a value for did_group_id and quantity to the order items array.

For Example: { "order_items": [ { "did_group_id": 16847, "quantity": 3 } ]}

We currently only support 1 order item per order. Passing more than 1 order item will result in an error.

Numbers are not added to the account until the order starts processing.

Order Status

An order has a status field and it can be one of the following statuses:

Order Item Status

You can get more details on the status of an order by looking at an order item's status. Here is a list of possible order item statuses:

Order Item Status Description Cancelable
Preview This status is only used when passing the preview flag as "true" into Create Order
Received The order item has been received and is getting ready to be processed No
Processing We started processing the order item No
Fulfilled - Complete We successfully fulfilled the item No
Partially Fulfilled – Complete We were only able to partially fulfill your item No
Backordered The order item is on backorder Yes
Backorder Canceled The backorder was canceled No
Partially Fulfilled – Backordered We partially fulfilled your order item, and put the remaining quantity on backorder Yes
Partially Fulfilled – Backorder Canceled The backorder was canceled No
Canceled – Insufficient Funds There were not enough funds to complete this order item No
Canceled – Insufficient Inventory There were not enough DIDs in inventory to fulfill the order item No
Partially Fulfilled – Insufficient Funds We were only able to partially fulfill the item because your account ran out of funds No

Use Get Order to check the status of the order.

The API currently does not support canceling an order item, but it will be added soon. In the meantime, canceling the item can be done in the IDT Express Portal.

Code samples

curl -v \
-X POST "https://api.idtexpress.com/v1/dids/orders" \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{ "order_items": [ { "did_group_id": 16847, "quantity": 3 } ]}'
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/orders")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"
request["Content-Type"] = "application/json; charset=utf-8"
request.body = "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}"
headers = {
   'x-api-key': '****',
   'x-api-secret': '****',
   'Content-Type': 'application/json; charset=utf-8'
}
conn.request("POST", "/v1/dids/orders", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/orders",
   "method": "POST",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****",
      "Content-Type": "application/json; charset=utf-8"
   },
   "data": "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}",
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'POST',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/orders',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****',
      'Content-Type': 'application/json; charset=utf-8'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

var postData =  "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}";

req.write(postData);

req.end();
package main

import (
   "fmt"
   "strings"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/orders"
   method := "POST"

   payload := strings.NewReader("{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}")

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, payload)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")
   req.Header.Add("Content-Type", "application/json; charset=utf-8")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/orders")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")
request.addValue("application/json; charset=utf-8", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
RequestBody body = RequestBody.create(mediaType, "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}");
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/orders")
   .method("POST", body)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .addHeader("Content-Type", "application/json; charset=utf-8")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/orders");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
request.AddHeader("Content-Type", "application/json; charset=utf-8");
request.AddParameter("application/json; charset=utf-8", "{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/orders",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "POST",
   CURLOPT_POSTFIELDS =>"{ \"order_items\": [ { \"did_group_id\": 16847, \"quantity\": 3 } ]}",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****",
      "Content-Type: application/json; charset=utf-8"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

POST /v1/dids/orders

Parameters

Name In Type Required Description
preview json body boolean true If the value is true then the call does not create an order, but it still goes through all validations such as checking if the account has sufficient funds to process the order. The default value is false
order_items json body [Object] true The request needs 1 order item to be successful
order_items[].did_group_id json body integer true The DID Group that you want to order. Use a DID Group ID from Get DID Groups
order_items[].quantity json body integer true The amount of numbers that you want to order. The maximum amount of numbers that can be ordered is 100

Example responses

200 Response

{
   "order":{
      "id":"f52-6d9-261b",
      "created_at":"2020-06-26T11:01:16.000Z",
      "status":"Created",
      "ordered": {
         "quantity": 3
      },
      "fulfilled": {
         "quantity": 0
      },
      "order_items":[
         {
            "id":162455,
            "status":"Processing",
            "order_item_type":"quantity",
            "ordered": {
               "quantity": 3
            },
            "fulfilled": {
               "quantity": 0
            },
            "cancelable":false,
            "did_group":{
               "id":16847,
               "name":"SALVADOR ",
               "country_calling_code":"55",
               "area_code":"71",
               "nxx":null,
               "toll_free":false,
               "country":{
                  "name":"BRAZIL",
                  "iso":"BR",
                  "has_regions":false
               },
               "fees":{
                  "setup_fee":"0.00",
                  "monthly_fee":"3.00"                  
               }
            },
            "numbers":[

            ]
         }
      ]
   },
   "meta":{

   }
}

Response Schema

Status Code 200

  • order object

    • order.id integer

      The order's unique identifier

    • order.created_at string

      Date/Time that the order was created in ISO 8601 format

    • order.status string

      The status of the order. See Order Status

    • order.ordered object

      Object representing the quantity of what was ordered

      • order.quantity integer

        The amount of numbers that were requested. Please note that we may not be able to fulfill all of the numbers that were requested

    • order.fulfilled object

      Object representing the quantity of what was fulfilled

      • order.quantity integer

        This is total amount of numbers we were able to fulfill

    • order.order_items array of objects

      • order.order_items[].id integer

        Unique identifier for the order item

      • order.order_items[].status string

        The status of this order item. See Order Item Status

      • order.order_items[].order_item_type string

        The type of order item. This is a system generated value that is based on what is passed into the order item in Create Order. The value will be quantity if the order was by DID Group ID and quantity. In the future, we will support different types of order items

      • order.order_items[].ordered object

        Object representing the quantity of what was ordered for this order item

        • order.order_items[].quantity integer

          The amount of numbers that were requested for this order item. Please note that we may not be able to fulfill all of the numbers that were requested

      • order.order_items[].fulfilled object

        Object representing the quantity of what was fulfilled for this order item

        • order.order_items[].quantity integer

          This is amount of numbers we were able to fulfill for this order item

      • order.order_items[].cancelable boolean

        Indicates if this order item can be canceled. Canceling an order item is not supported by the API at this time.

        To cancel an order item, log into the IDT Express Portal

      • order.order_items[].did_group object
        The DID Group that was ordered. Please note that the fees here represent the fees at the time of ordering. The current fees may be different.

        You can use Get DID Groups to find out the current fees

        • order.order_items[].did_group.id string

          The unique identifier for the DID Group. Use this when placing an order

        • order.order_items[].did_group.name string

          The name of DID Group

        • order.order_items[].did_group.country_calling_code string

          The international calling code

        • order.order_items[].did_group.area_code string

          The area code/NPA

        • order.order_items[].did_group.nxx string

          The NXX. Only applicable for North American numbers

        • order.order_items[].did_group.toll_free boolean

          Indicates if the DID Group is Toll-Free

        • order.order_items[].did_group.country object

          Object representing the country the DID Group belongs to

          • order.order_items[].did_group.country.name boolean

            Country name

          • order.order_items[].did_group.country.iso string

            2 character ISO 3166-1 alpha-2 country code

          • order.order_items[].did_group.country.has_regions boolean

            Flag to indicate if the country supports regions

        • order.order_items[].did_group.region object

          Object representing the region the DID Group belongs to. This will only be present if there is a region

          • order.order_items[].did_group.region.name string

            The name of the region

          • order.order_items[].did_group.region.code string

            The ISO 3166-2 code that uniquely identifies the region

        • order.order_items[].did_group.fees object

          Fees associated with this DID Group. These values are in currency of your account

          • order.order_items[].did_group.fees.setup_fee string

            Setup fee

          • order.order_items[].did_group.fees.monthly_fee string

            The number's monthly fee

          • order.order_items[].did_group.fees.per_minute_rate string

            The per minute rate

      • order.order_items[].numbers array of objects

        Any numbers that were added to the account as part of this order item. Please note that an empty array will be returned when creating an order

        • order.dids[].number string

          A number that was added

Get Order

Gets the details of an order, including any DIDs that were purchased.

Code samples

curl -v \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("GET", "/v1/dids/orders/9c2-2e2-4b6f", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f",
   "method": "GET",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'GET',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/orders/9c2-2e2-4b6f',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f")
   .method("GET", null)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/orders/9c2-2e2-4b6f",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

GET /v1/dids/orders/{order_id}

Parameters

Name In Type Required Description
order_id path string true The id returned in Create Order

Example responses

200 Response

{
   "order":{
      "id":"9c2-2e2-4b6f",
      "created_at":"2020-06-25T13:47:00.000Z",
      "status":"complete",
      "ordered": {
         "quantity": 1
      },
      "fulfilled": {
         "quantity": 1
      },
      "order_items":[
         {
            "id":162336,
            "status":"Fulfilled – Complete",
            "order_item_type":"quantity",
            "ordered": {
               "quantity": 1
            },
            "fulfilled": {
               "quantity": 1
            },
            "cancelable":false,
            "did_group":{
               "id":19500,
               "name":"PIOTRKOW TRYBUNALSKI",
               "country_calling_code":"48",
               "area_code":"44",
               "nxx":null,
               "toll_free":false,
               "country":{
                  "name":"POLAND",
                  "iso":"PL",
                  "has_regions":false
               },
               "fees":{
                  "setup_fee":"0.00",
                  "monthly_fee":"2.50"
               }
            },
            "numbers":[
               {
                  "number":"01148448881015"
               }
            ]
         }
      ]
   },
   "meta":{

   }
}

Response Schema

Status Code 200

  • order object

    • order.id integer

      The order's unique identifier

    • order.created_at string

      Date/Time that the order was created in ISO 8601 format

    • order.status string

      The status of the order. See Order Status

    • order.ordered object

      Object representing the quantity of what was ordered

      • order.quantity integer

        The amount of numbers that were requested. Please note that we may not be able to fulfill all of the numbers that were requested

    • order.fulfilled object

      Object representing the quantity of what was fulfilled

      • order.quantity integer

        This is total amount of numbers we were able to fulfill

    • order.order_items array of objects

      • order.order_items[].id integer

        Unique identifier for the order item

      • order.order_items[].status string

        The status of this order item. See Order Item Status

      • order.order_items[].order_item_type string

        The type of order item. This is a system generated value that is based on what is passed into the order item in Create Order. The value will be quantity if the order was by DID Group ID and quantity. In the future, we will support different types of order items

      • order.order_items[].ordered object

        Object representing the quantity of what was ordered for this order item

        • order.order_items[].quantity integer

          The amount of numbers that were requested for this order item. Please note that we may not be able to fulfill all of the numbers that were requested

      • order.order_items[].fulfilled object

        Object representing the quantity of what was fulfilled for this order item

        • order.order_items[].quantity integer

          This is amount of numbers we were able to fulfill for this order item

      • order.order_items[].cancelable boolean

        Indicates if this order item can be canceled. Canceling an order item is not supported by the API at this time.

        To cancel an order item, log into the IDT Express Portal

      • order.order_items[].did_group object
        The DID Group that was ordered. Please note that the fees here represent the fees at the time of ordering. The current fees may be different.

        You can use Get DID Groups to find out the current fees

        • order.order_items[].did_group.id string

          The unique identifier for the DID Group. Use this when placing an order

        • order.order_items[].did_group.name string

          The name of DID Group

        • order.order_items[].did_group.country_calling_code string

          The international calling code

        • order.order_items[].did_group.area_code string

          The area code/NPA

        • order.order_items[].did_group.nxx string

          The NXX. Only applicable for North American numbers

        • order.order_items[].did_group.toll_free boolean

          Indicates if the DID Group is Toll-Free

        • order.order_items[].did_group.country object

          Object representing the country the DID Group belongs to

          • order.order_items[].did_group.country.name boolean

            Country name

          • order.order_items[].did_group.country.iso string

            2 character ISO 3166-1 alpha-2 country code

          • order.order_items[].did_group.country.has_regions boolean

            Flag to indicate if the country supports regions

        • order.order_items[].did_group.region object

          Object representing the region the DID Group belongs to. This will only be present if there is a region

          • order.order_items[].did_group.region.name string

            The name of the region

          • order.order_items[].did_group.region.code string

            The ISO 3166-2 code that uniquely identifies the region

        • order.order_items[].did_group.fees object

          Fees associated with this DID Group. These values are in currency of your account

          • order.order_items[].did_group.fees.setup_fee string

            Setup fee

          • order.order_items[].did_group.fees.monthly_fee string

            The number's monthly fee

          • order.order_items[].did_group.fees.per_minute_rate string

            The per minute rate

      • order.order_items[].numbers array of objects

        Any numbers that were added to the account as part of this order item. Please note that an empty array will be returned when creating an order

        • order.dids[].number string

          A number that was added

  • meta object

Get Orders

Returns a summary of all the orders on your account, or filtered by order status.

Code samples

curl -v \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("GET", "/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete",
   "method": "GET",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'GET',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete")
   .method("GET", null)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/orders?page=1&page_size=10&filter_by_status=Complete",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

GET /v1/dids/orders

Parameters

Name In Type Required Description
page query integer false The current page. The default is page 1
page_size query integer false The current page size. The default is a page size of 100
filter_by_status query string false Filter orders by order status

List all DID Orders

Example responses

200 Response

{
    "orders": [
        {
            "id": "710-1be-a8d7",
            "created_at": "2020-07-05T22:58:23.000Z",
            "status": "Processing",
            "ordered": {
                "quantity": 2               
            },
            "fulfilled": {
                "quantity": 0
            }
        },
        {
            "id": "929-bcc-ed00",
            "created_at": "2020-07-05T22:48:31.000Z",
            "status": "Complete",
            "ordered": {
                "quantity": 17               
            },
            "fulfilled": {
                "quantity": 17
            }            
        },
        {
            "id": "018-7cb-5832",
            "created_at": "2020-07-05T10:29:51.000Z",
            "status": "Complete",
            "ordered": {
                "quantity": 2
            },
            "fulfilled": {
                "quantity": 0
            },
            "currency": "USD"
        }

    ],
    "meta": {
        "page": 1,
        "page_size": 100,
        "total": 3
    }
}

Responses

  • orders array of objects

    • orders[].id string

      The order's unique identifier

    • orders[].created_at string

      Date/Time that the order was created in ISO 8601 format

    • orders[].status string

      The status of the order. See Order Status

    • orders[].ordered object

      Object representing the quantity of what was ordered

      • orders[].ordered.quantity integer

        The amount of numbers that were requested. Please note that we may not be able to fulfill all of the numbers that were requested


    • orders[].fulfilled object

      Object representing the quantity of what was fulfilled

      • orders[].fulfilled.quantity integer

        This is total amount of numbers we were able to fulfill

  • meta object

    • meta.page integer

      The current page number

    • meta.page_size integer

      The current page size

    • meta.total integer

      This will either be the total number of orders on the account, or the total number of orders that match the filters

Get Numbers

Returns all of the active and recently removed numbers on your account.

Code samples

curl -v \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("GET", "/v1/dids/numbers?page=1&page_size=10", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10",
   "method": "GET",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'GET',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/numbers?page=1&page_size=10',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10"
   method := "GET"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10")
   .method("GET", null)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/numbers?page=1&page_size=10",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

GET /v1/dids/numbers?page={page}&page_size={page_size}

Parameters

Name In Type Required Description
page query integer false The current page. The default is page 1
page_size query integer false The current page size. The default is a page size of 100

Example responses

200 Response

{
   "numbers":[
      {
         "number":"0115117304800",
         "status":"active",
         "added_at":"2020-06-24T19:02:30.000Z",
         "did_group":{
            "name":"LIMA",
            "id":11895,
            "country_calling_code":"51",
            "area_code":"1",
            "nxx":null,
            "toll_free":false,
            "country":{
               "name":"PERU",
               "iso":"PE",
               "has_regions":false,
               "supports_toll_free":false
            },
            "fees":{
               "setup_fee":"0.00",
               "monthly_fee":"5.25",
               "per_minute_rate":"4.7354"
            }
         }
      },
      {
         "number":"011557135001442",
         "status":"active",
         "added_at":"2020-06-24T19:02:51.000Z",
         "did_group":{
            "name":"SALVADOR ",
            "id":16847,
            "country_calling_code":"55",
            "area_code":"71",
            "nxx":null,
            "toll_free":false,
            "country":{
               "name":"BRAZIL",
               "iso":"BR",
               "has_regions":false,
               "supports_toll_free":true
            },
            "fees":{
               "setup_fee":"0.00",
               "monthly_fee":"3.00",
               "per_minute_rate":"4.7354"
            }
         }
      },
      {
         "number":"011557135001540",
         "status":"active",
         "added_at":"2020-06-26T07:01:28.000Z",
         "did_group":{
            "name":"SALVADOR ",
            "id":16847,
            "country_calling_code":"55",
            "area_code":"71",
            "nxx":null,
            "toll_free":false,
            "country":{
               "name":"BRAZIL",
               "iso":"BR",
               "has_regions":false,
               "supports_toll_free":true
            },
            "fees":{
               "setup_fee":"0.00",
               "monthly_fee":"3.00",
               "per_minute_rate":"4.7354"
            }
         }
      },
      {
         "number":"011557135001580",
         "status":"active",
         "added_at":"2020-06-26T07:01:28.000Z",
         "did_group":{
            "name":"SALVADOR",
            "id":16847,
            "country_calling_code":"55",
            "area_code":"71",
            "nxx":null,
            "toll_free":false,
            "country":{
               "name":"BRAZIL",
               "iso":"BR",
               "has_regions":false,
               "supports_toll_free":true
            },
            "fees":{
               "setup_fee":"0.00",
               "monthly_fee":"3.00",
               "per_minute_rate":"4.7354"
            }
         }
      }
   ],
   "meta":{
      "page":1,
      "page_size":100,
      "total":4
   }
}

Response Schema

Status Code 200

  • numbers array of objects

    • numbers[].number string

      The number

    • numbers[].status string

      The status of the number. It can be active or removed

    • numbers[].added_at string

      Date/Time in ISO 8601 format that the number was added to the account

    • numbers[].removed_at string

      Date/Time in ISO 8601 format that the number was removed to the account. This will only be present if that status is removed

    • numbers[].did_group object

      The DID Group that the number belongs to

      • numbers[].did_group.id string

        The unique identifier for the DID Group. Use this when placing an order

      • numbers[].did_group.name string

        The name of DID Group

      • numbers[].did_group.country_calling_code string

        The international calling code

      • numbers[].did_group.area_code string

        The area code/NPA

      • numbers[].did_group.nxx string

        The NXX. Only applicable for North American numbers

      • numbers[].did_group.toll_free boolean

        Indicates if the DID Group is Toll-Free

      • numbers[].did_group.country object

        Object representing the country the DID Group belongs to

        • numbers[].did_group.country.name boolean

          Country name

        • numbers[].did_group.country.iso string

          2 character ISO 3166-1 alpha-2 country code

        • numbers[].did_group.country.has_regions boolean

          Flag to indicate if the country supports regions

        • numbers[].did_group.country.supports_toll_free boolean

          Flag to indicate if the country supports toll-free numbers


      • numbers[].did_group.region object

        Object representing the region the DID Group belongs to. This will only be present if there is a region

        • numbers[].did_group.region.name string

          The name of the region

        • numbers[].did_group.region.code string

          The ISO 3166-2 code that uniquely identifies the region

      • numbers[].did_group.fees object

        Fees associated with this DID Group. These values are in currency of your account

        • numbers[].did_group.fees.setup_fee string

          Setup fee

        • numbers[].did_group.fees.monthly_fee string

          The number's monthly fee

        • numbers[].did_group.fees.per_minute_rate string

          The per minute rate

  • meta object

    • meta.page integer

      The current page number

    • meta.page_size integer

      The current page size

    • meta.total integer

      The total amount of numbers on the account

Delete Number

Removes a number from your account.

Code samples

curl -v \
-X DELETE \
-H "x-api-key: ****" \
-H "x-api-secret: ****" \
"https://api.idtexpress.com/v1/dids/numbers/01133975182372"
require "uri"
require "net/http"

url = URI("https://api.idtexpress.com/v1/dids/numbers/01133975182372")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["x-api-key"] = "****"
request["x-api-secret"] = "****"

response = https.request(request)
puts response.read_body

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api.idtexpress.com")
payload = ''
headers = {
   'x-api-key': '****',
   'x-api-secret': '****'
}
conn.request("DELETE", "/v1/dids/numbers/01133975182372", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var settings = {
   "url": "https://api.idtexpress.com/v1/dids/numbers/01133975182372",
   "method": "DELETE",
   "timeout": 0,
   "headers": {
      "x-api-key": "****",
      "x-api-secret": "****"
   },
};

$.ajax(settings).done(function (response) {
   console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
   'method': 'DELETE',
   'hostname': 'api.idtexpress.com',
   'path': '/v1/dids/numbers/01133975182372',
   'headers': {
      'x-api-key': '****',
      'x-api-secret': '****'
   },
   'maxRedirects': 20
};

var req = https.request(options, function (res) {
   var chunks = [];

   res.on("data", function (chunk) {
      chunks.push(chunk);
   });

   res.on("end", function (chunk) {
      var body = Buffer.concat(chunks);
      console.log(body.toString());
   });

   res.on("error", function (error) {
      console.error(error);
   });
});

req.end();
package main

import (
   "fmt"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "https://api.idtexpress.com/v1/dids/numbers/01133975182372"
   method := "DELETE"

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, nil)

   if err != nil {
      fmt.Println(err)
   }
   req.Header.Add("x-api-key", "****")
   req.Header.Add("x-api-secret", "****")

   res, err := client.Do(req)
   defer res.Body.Close()
   body, err := ioutil.ReadAll(res.Body)

   fmt.Println(string(body))
}
import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.idtexpress.com/v1/dids/numbers/01133975182372")!,timeoutInterval: Double.infinity)
request.addValue("****", forHTTPHeaderField: "x-api-key")
request.addValue("****", forHTTPHeaderField: "x-api-secret")

request.httpMethod = "DELETE"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
   guard let data = data else {
      print(String(describing: error))
      return
   }
   print(String(data: data, encoding: .utf8)!)
   semaphore.signal()
}

task.resume()
semaphore.wait()

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
   .url("https://api.idtexpress.com/v1/dids/numbers/01133975182372")
   .method("DELETE", body)
   .addHeader("x-api-key", "****")
   .addHeader("x-api-secret", "****")
   .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.idtexpress.com/v1/dids/numbers/01133975182372");
client.Timeout = -1;
var request = new RestRequest(Method.DELETE);
request.AddHeader("x-api-key", "****");
request.AddHeader("x-api-secret", "****");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://api.idtexpress.com/v1/dids/numbers/01133975182372",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "DELETE",
   CURLOPT_HTTPHEADER => array(
      "x-api-key: ****",
      "x-api-secret: ****"
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Endpoint

DELETE /v1/dids/numbers/{number}

Parameters

Name In Type Required Description
number path string true A number returned from Get Numbers

Example responses

200 Response

{
  "number":"01133975182372",
  "status":"removed"
}

Response Schema

Status Code 200

  • number string

    The number that was removed

  • status string

    The new status which will be removed