Dialing Services API Introduction

Welcome to the Voxtelesys Dialing Services REST API!

Base URL

All URLs referenced in this document have the following base: https://servicelayer01.voxtelesys.net:3000/api/v1

Authentication

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/authorize/login \
  -H 'authorization: Basic dXNyOnB3ZA==' \

Response: 200

{
  "status": {
    "status": "Authorized",
    "token": "6116504a-0cc2-419c-852c-442d3f3e2659",
    "account_id": "190761",
    "account_name": "voxtelesys vts"
  },
  "services": [
    {
      "short_name": "CNI",
      "full_name": "Cellular Number Identification",
      "service_id": 1
    },
    {
      "short_name": "DCLID",
      "full_name": "Dynamic Caller ID",
      "service_id": 2
    }
  ],
  "error": ""
}

Basic Authentication

Tokens are assigned via the authorize/login method. The login method utilizes HTTP basic authentication. Please signup for voice services at voxtelesys to receive a valid username and password.

GET /authorize/login

Header	Type	Required	Description	Example
Authorization	string	true	basic authentication	`Authentication: Basic dXNyOnB3ZA==`

Token Authentication

All HTTP requests to the Dialing Services REST API, with the exception of /authorize/login, are authenticated via HTTP token authentication. Once assigned the token is valid for 10 minutes, refreshing for an additional 10 minutes with subsequent successful requests. As a further layer of protection, the assigned token is only valid for the IP address from which the HTTP request was attempted. For applications making requests to the Dialing Services REST API via separate IP addresses, you must obtain unique tokens per application.

Tokens are provided to the Dialing Services REST API via HTTP headers:

Authorization: Token token={TOKEN}

Authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659

All Services

To reduce processing time, the Dialing Services REST API allows you look up the number type, DNC result, and Dynamic Caller ID result (or any combination of the services) for up to 1,000 phone numbers using a single endpoint.

Retrieve All Services

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/allservices \
  -H 'authorization: Token token=7cfd007e-2c3f-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -H 'profileid: 593' \
  -d '{  
   "cni":true,
   "dnc":true,
   "dclid":true,
   "phone_numbers":[
      {  
         "id":1,
         "number":"44 871 423 4896"
      },
      {  
         "id":2,
         "number":"14025137575"
      },
      {  
         "id":3,
         "number":"14022776383"
      },
      {
         "id":4,
         "number":"all text"
      },
      {  
         "id":5,
         "number":""
      }
   ]
}''

Response: 200

{
    "results": [
        {
            "id": 1,
            "orig_phone_number": "44 871 423 4896",
            "number_type": "Unknown",
            "callerid": "18558889768",
            "dnc": "OK",
            "cni_error": "Not a 10 digit number.",
            "dclid_error": null
        },
        {
            "id": 2,
            "orig_phone_number": "14025137575",
            "number_type": "Landline",
            "callerid": "14029999402",
            "dnc": "DNC",
            "cni_error": null,
            "dclid_error": null
        },
        {
            "id": 3,
            "orig_phone_number": "14022776383",
            "number_type": "Cellular",
            "callerid": "14029999402",
            "dnc": "OK",
            "cni_error": null,
            "dclid_error": null
        },
        {
            "id": 4,
            "orig_phone_number": "all text",
            "number_type": "Unknown",
            "callerid": "Undefined",
            "dnc": "Invalid",
            "cni_error": "Invalid input",
            "dclid_error": "Invalid input"
        },
        {
            "id": 5,
            "orig_phone_number": "",
            "number_type": "Unknown",
            "callerid": "Undefined",
            "dnc": "Invalid",
            "cni_error": "Invalid input",
            "dclid_error": "Invalid input"
        }
    ],
    "error": null
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "errors": "Please provide an array of phone numbers in the 'phone_numbers' attribute of the body."
}

Response: 500

    {
          "results": [],
         "error": "ERROR MESSAGE"
     }

This endpoint retrieves any combination of the CNI, DCLID, and DNC results (determined by the cni, dclid, and dnc attributes of the request body) for up to 1,000 phone numbers specified in the phone_numbers array. Each phone number in the phone_number array must contain a number attribute, the id attribute is optional.

HTTP Request

POST /allservices

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
PROFILEID	string	false	profile id to used to look up the dynamic caller id, requried only if the dclid flag in the request body is set to true	`PROFILEID: 544`
SUBACCOUNT	integer	false	ID of sub account	`SUBACCOUNT: 1000`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
cni	bool	true	A flag indicating whether or not to look up the number type of each phone number	`true`
dclid	bool	true	A flag indicating whether or not to look up the Dynamic Caller ID result of each phone number	`true`
dnc	bool	true	A flag indicating whether or not to look up the DNC result of each phone number	`true`
phone_numbers	array	true	array of phone numbers, with options	`["number":"14022776383", ... ]`
phone_numbers.id	int	string	false	custom ID returned with results
phone_numbers.number	string	true	phone number to lookup	`14029999402`
phone_numbers.profile_id	int	false	override PROFILEID	`565`
phone_numbers.prefix	string	false	use prefix mapping, if found	`TAG01`

Cellular Number Identification

To assist with TCPA compliance, the Dialing Services REST API allows you to determine if a phone number is a cellular number.

Retrieve Number Type

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/cni/phonenumber \
  -H 'authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659' \
  -H 'phonenumber: 4022776383' \

Response: 200

{
    "number_type": "Cellular",
    "orig_phone_number": "4022776383",
    "error": ""
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 500

{
  "number_type": "Unknown",
   "orig_phone_number": "phonenumber",
  "error": "ERROR MESSAGE"
}

This endpoint retrieves the number type a single phone number specified in the PHONENUMBER HTTP header. Possilble results include : Landline, Cellular, VoIP, Unknown, and Pager.

HTTP Request

GET /cni/phonenumber

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
PHONENUMBER	string	true	phone number to look up	`PHONENUMBER: 402-277-6383`

Bulk Retrieve Number Type

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/cni/phonenumber \
  -H 'authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659' \
  -H 'content-type: application/json' \
  -d '{  
       "phone_numbers":[
      {  
         "number":"44 871 423 4896"
      },
      {  
         "number":"14025137575"
      },
      {  
         "number":"14022776383"
      },
      {  
         "number":"all text"
      },
      {  
         "number":""
      }
   ]
}'

Response: 200

{
    "results": [
        {
            "number_type": "Unknown",
            "orig_phone_number": "44 871 423 4896",
            "cni_error": "Not a 10 digit number."
        },
        {
            "number_type": "Landline",
            "orig_phone_number": "14025137575",
            "cni_error": null
        },
        {
            "number_type": "Cellular",
            "orig_phone_number": "14022776383",
            "cni_error": null
        },
        {
            "number_type": "Unknown",
            "orig_phone_number": "all text",
            "cni_error": "Invalid input"
        },
        {
            "number_type": "Unknown",
            "orig_phone_number": "",
            "cni_error": "Invalid input"
        }
    ],
    "error": null
}

Response: 401

{
    "error": "Not Authorized"
}

Response: 422

{
   "errors": "Please provide an array of phone numbers in the 'phone_numbers' attribute of the body."
}

Response: 500

{
     "results": [],
     "error": "ERROR MESSAGE"
 }

This endpoint retrieves the number types of up to 1,000 phone numbers specified in the body of the request. Possible results include : Landline, Cellular, VoIP, Unknown, and Pager.

HTTP Request

POST /cni/phonenumber

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
phone_numbers	array	true	array of phone numbers	`[{"number":"14022776383"}, ... ]`

Do-Not-Call

Voxtelesys offers full Do-Not-Call (DNC) list integration, at both the national and customer (local) level.

Retrieve DNC

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dnc/dnclookup \
  -H 'authorization: Token token=5c9d273c-2bb1-11e8-a906-ac162d79d11c' \
  -H 'phonenumber: 14022776383' \

Response: 200

{
    "orig_phone_number": "14022776383",
    "result": "OK",
    "errors": ""
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 500

{
  "orig_phone_number": "14022776383",
  "result": "Invalid",
  "errors": "Error message."
}

This endpoint retrieves the DNC result of a single phone number specified in the PHONENUMBER HTTP header.

HTTP Request

GET /dnc/dnclookup

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
PHONENUMBER	string	true	phone number to lookup	`PHONENUMBER: 402-277-6383`

Bulk Retrieve DNC

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dnc/dnclookup \
  -H 'authorization: Token token=5c9d273c-2bb1-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{  
       "phone_numbers":[
      {  
         "number":"44 871 423 4896"
      },
      {  
         "number":"14025137575"
      },
      {  
         "number":"14022776383"
      },
      {  
         "number":"all text"
      },
      {  
         "number":""
      }
   ]
}''

Response: 200

{
    "results": [
        {
            "orig_phone_number": "44 871 423 4896",
            "result": "OK"
        },
        {
            "orig_phone_number": "14025137575",
            "result": "DNC"
        },
        {
            "orig_phone_number": "14022776383",
            "result": "OK"
        },
        {
            "orig_phone_number": "all text",
            "result": "Invalid"
        },
        {
            "orig_phone_number": "",
            "result": "Invalid"
        }
    ],
    "errors": null
}

Response: 401

{
    "error": "Not Authorized"
}

Response: 422

{
   "errors": "Please provide an array of phone numbers in the 'phone_numbers' attribute of the body."
}

Response: 500

{
     "results": [],
     "error": "ERROR MESSAGE"
 }

This endpoint retrieves the DNC lookup results for of up to 1,000 phone numbers specified in the body of the request.

HTTP Request

POST dnc/dnclookup

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
phone_numbers	array	true	array of phone numbers	`[{"number":"14022776383"}, ... ]`

Retrieve DNC List

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dnc/customer_lists \
  -H 'authorization: Token token=7a48aca7-2bae-11e8-a906-ac162d79d11c' \
  -H 'phonenumber: 14022776383' \

Response: 200

{
  "customer_lists": [
    {
      "id": 27,
      "account_id": 190761,
      "subaccount": null,
      "ndc": 14024034435,
      "created_at": "2016-11-09T18:17:48.000Z"
    },
    {
      "id": 28,
      "account_id": 190761,
      "subaccount": null,
      "ndc": 14022770000,
      "created_at": "2016-11-09T18:17:48.000Z"
    }
  ]
}

This endpoint retrieves the local DNC list associated with the account. If the SUBACCOUNT header is provided, then the DNC list associated with both the account and sub account will be retrieved. Please note that only the local DNC list will be retrieved, not the National DNC list.

HTTP Request

GET /dnc/customer_lists

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
SUBACCOUNT	integer	false	ID of sub account	`SUBACCOUNT: 1000`

HTTP Request

GET /dnc/customer_lists/{id}

URL Parameter	Type	Required	Description	Example
id	integer	true	ID associated with DNC record	`27`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
SUBACCOUNT	integer	false	ID of sub account	`SUBACCOUNT: 1000`

Create DNC Entry

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dnc/customer_lists \
  -H 'authorization: Token token=5c9d273c-2bb1-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -H 'subaccount: 1000' \
  -d '{
      "account_code": 190761,
      "ndc": 14022776383
    }'

Response:

{
    "dnc_customer_list": {
        "id": 125,
        "account_id": 190761,
        "subaccount": 1000,
        "ndc": 14022776383,
        "created_at": "2018-03-19T20:17:30.000Z"
    }
}

This endpoint creates a new DNC entry for the provided ndc (phone number). If the SUBACCOUNT header is provided, then the entry will be associated with the provided sub account. Please note that the entry is only created in the local DNC list, not the National DNC list.

HTTP Request

POST /dnc/customer_lists

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
SUBACCOUNT	integer	false	ID of sub account	`SUBACCOUNT: 1000`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
ndc	integer	true	valid phone number	`14024034435`
account_id	integer	true	The account ID associated to the DNC list	`190761`

Delete DNC Entry

Request:

curl -X DELETE \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dnc/customer_lists/125 \
  -H 'authorization: Token token=5c9d273c-2bb1-11e8-a906-ac162d79d11c' \
  -H 'subaccount: 1000'

Response: 200

This endpoint deletes a DNC entry. If the SUBACCOUNT header is provided, then the entry will be removed from the DNC list associated with the provided sub account. Please note that the entry is only deleted from the local DNC list, not the National DNC list.

HTTP Request

DELETE /dnc/customer_lists/{id}

URL Parameter	Type	Required	Description	Example
id	integer	true	ID associated with DNC record	`125`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
SUBACCOUNT	integer	false	ID of sub account	`SUBACCOUNT: 1000`

Dynamic Caller ID

The Dialing Services REST API offers the ability to achieve local presence by retrieving a local caller ID given an outbound phone number and a profile. The mappings of caller IDs to specific regions are defined in the account profile.

The Dialing Services REST API also offers profile management, allowing you to define specific mappings between caller IDs and NPAs, States and Countries. It offers the flexibility to create a profile and automatically assign a list of caller IDs to their associated State or NPA a single web service call.

Retrieve Dynamic Caller ID

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/dynamiccallerid \
  -H 'authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659' \
  -H 'phonenumber: 402-277-6383' \
  -H 'profileid: 544'

Response: 200

{
    "orig_phone_number": "402-277-6383",
    "callerid": "14025137575",
    "errors": ""
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "errors": "Profile does not belong to account or does not exist."
}

Response: 500

{
  "orig_phone_number": null,
  "callerid": "Undefined",
  "errors": "ERROR MESSAGE"
}

This endpoint retrieves the Dynamic Caller ID result based on the profile and phone number specified in the PROFILEID and PHONENUMBER headers respectively. If a profile id is not specified, the account's default profile will be used, if one exists.

HTTP Request

GET /dclid/dynamiccallerid

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
PHONENUMBER	string	true	phone number to lookup	`PHONENUMBER: 402-277-6383`
PROFILEID	string	true	profile id to use to look up the dynamic caller ID	`PROFILEID: 544`

Bulk Retrieve Dynamic Caller ID

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/dynamiccallerid \
  -H 'authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659' \
  -H 'content-type: application/json' \
  -H 'profileid: 544' \
  -d '{  
       "phone_numbers":[
      {  
         "number":"44 871 423 4896"
      },
      {  
         "number":"14025137575"
      },
      {  
         "number":"14022776383"
      },
      {  
         "number":"all text"
      },
      {  
         "number":""
      }
   ]
}'

Response: 200

   {
       "results": [
           {
               "orig_phone_number": "44 871 423 4896",
               "callerid": "18005555555",
               "dclid_error": null
           },
           {
               "orig_phone_number": "14025137575",
               "callerid": "14025555555",
               "dclid_error": null
           },
           {
               "orig_phone_number": "14022776383",
               "callerid": "14025555555",
               "dclid_error": null
           },
           {
               "orig_phone_number": "all text",
               "callerid": "Undefined",
               "dclid_error": "Invalid input"
           },
           {
               "orig_phone_number": "",
               "callerid": "Undefined",
               "dclid_error": "Invalid input"
           }
       ],
       "errors": null
   }

Response: 401

{
    "error": "Not Authorized"
}

Response: 422

{
    "errors": "Please provide an array of phone numbers in the 'phone_numbers' attribute of the body."
}

This endpoint retrieves the Dynamic Caller ID results for up to 1,000 phone numbers specified in the phone_numbers array of the request body. The results are based on the profile specified in the PROFILEID header. If a profile id is not specified, the account's default profile will be used, if one exists.

HTTP Request

POST /dclid/dynamiccallerid

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
PROFILEID	string	true	profile id to use to look up the Dynamic Caller ID	`PROFILEID: 544`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
phone_numbers	array	true	array of phone numbers, with options	`["number":"14022776383", ... ]`
phone_numbers.number	string	true	phone number to lookup	`14029999402`
phone_numbers.profile_id	int	false	override PROFILEID	`565`
phone_numbers.prefix	string	false	use prefix mapping, if found	`TAG01`

Dynamic Caller ID Profiles

The Dialing Services REST API also offers methods for profile management, allowing you to define specific mappings between caller IDs and NPAs, States and Countries. It offers the flexibility to create a profile and automatically assign a list of caller IDs to their associated State or NPA in a single web service call.

Retrieve Profiles

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles \
  -H 'authorization: Token token=9d69035d-29fb-11e8-a906-ac162d79d11c' \

Response: 200

{
  "profiles": [
    {
      "id": 118,
      "profile_name": "State Mappings",
      "default_callerid": "12544010502",
      "account_id": 190062
    },
    {
      "id": 119,
      "profile_name": "NPA Mappings",
      "default_callerid": "16823074396",
      "account_id": 190062
    },
    {
      "id": 120,
      "profile_name": "Blank Profile",
      "default_callerid": "13345571883",
      "account_id": 190062
    }
  ]
}

Response: 401

{
  "error": "Not Authorized"
}

This endpoint retrieves the list of profiles associated to the account.

HTTP Request

GET /dclid/profiles

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

HTTP Request

GET /dclid/profiles/{id}

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Create Profile

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles \
  -H 'authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659' \
  -H 'content-type: application/json' \
  -d '{
      "profile_name": "New Blank Profile",      
      "default_callerid": "14025137575",
      "account_id": 190761,
      "default_profile": false

}'

Response: 200

{
    "profile": {
        "id": 578,
        "profile_name": "New Blank Profile",
        "default_callerid": "14025137575",
        "account_id": 190761,
        "use_lrn": "b'1'",
        "default_profile": false
    }
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Caller ID does not belong to the account."
}

This endpoint allows you to create a new profile with no mappings. You must define a profile name and default Caller ID. Mappings can be added to the profile using the /dclid/mappings endpoints.

HTTP Request

POST /dclid/profiles

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
profile_name	string	true	The name that will be associated the new profile.	`New Blank Profile`
default_caller_id	string	true	The phone number associated to your account that will returned as the caller ID if the phone number does not match any mapping.	`14025137575`
account_id	int	true	The account id associated to the new profile.	`190761`
default_profile	bool	false	Optional parameter that specifies wheter or not the new profile should be the default profile. If a value is not provided, the default value is false.	`false`

Create Profile with NPA Mappings

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/npa \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -H 'default-clid: 8557858400' \
  -H 'profile-name: NPA Mapping Profile' \
  -d '{
    "default_profile": true,
  "dids" :
    [
      {"did":2167162398},
      {"did":3056990856},
      {"did":4016486767},
      {"did":4022778569},
      {"did":4157675225}
    ]
}'

Response: 200

{
    "status": "Created profile 1 records and profile_callerid 5 records.",
    "profile_id": "590",
    "error": ""
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "status": "error",
  "errors": "DID [did] does not belong to the account."
}

This endpoint allows you to create a new profile with NPA mappings that are automatically created using the list of DIDs in the body of the request. You must define a profile name and default Caller ID. Additional mappings can be added to the profile using the /dclid/mappings endpoints.

HTTP Request

POST /dclid/profiles/npa

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`
profile-name	string	true	The name that will be associated the new profile.	`New Blank Profile`
default-clid	string	true	The phone number associated to your account that will returned as the caller ID if the phone number does not match any mapping.	`14025137575`

Body Param	Type	Required	Description	Example
default_profile	bool	false	Optional parameter that specifies wheter or not the new profile should be the default profile. If not value is provided, the default value is false.	`false`
dids	array	true	The list of DIDs that will be automatically mapped to their associated NPA and added to the profile.	`"dids" :[ {"did":2167162398},...]`

Create Profile with State Mappings

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/state \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -H 'default-clid: 8557858400' \
  -H 'profile-name: State Mapping Profile' \
  -d '{
    "default_profile": true,
  "dids" :
    [
      {"did":2167162398},
      {"did":3056990856},
      {"did":4016486767},
      {"did":4022778569},
      {"did":4157675225}
    ]
}'

Response: 200

{
    "status": "Created profile 1 records and profile_callerid 5 records.",
    "profile_id": "593",
    "error": ""
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "status": "error",
  "errors": "DID [did] does not belong to the account."
}

This endpoint allows you to create a new profile with State mapping that are automatically created using the list of DIDs in the body of the request. You must define a profile name and default caller id. Additional mappings can be added to the profile using the /dclid/mappings endpoints.

HTTP Request

POST /dclid/profiles/state

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`
profile-name	string	true	The name that will be associated the new profile.	`New Blank Profile`
default-clid	string	true	The phone number associated to your account that will returned as the caller ID if the phone number does not match any mapping.	`14025137575`

Body Param	Type	Required	Description	Example
default_profile	bool	false	Optional parameter that specifies whether or not the new profile should be the default profile. If a value is not provided the default value is false.	`false`
dids	array	true	The list of DIDs that will be automatically mapped to their associated State and added to the profile.	`"dids" :[ {"did":2167162398},...]`

Update Profile

Request:

curl -X PUT \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593 \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{
      "profile_name": "Updated NPA Profile",      
      "default_callerid": "8558889768",
      "account_id": 190761,
      "default_profile": true
}'

Response: 200

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Caller ID does not belong to the account."
}

This endpoint allows you to update the default Caller ID, profile name of an existing profile and specify if the profile should be marked as the default profile for the account.

HTTP Request

PUT /dclid/profiles/{id}

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Body Param	Type	Required	Description	Example
profile_name	string	true	The name that will be associated the new profile.	`New Blank Profile`
default_callerid	string	true	The phone number associated to your account that will returned as the caller ID if the phone number does not match any mapping.	`14025137575`
account_id	int	true	The account id associated to the new profile.	`190761`
default_profile	bool	false	Optional parameter that specifies wheter or not the profile should be the default profile. If a value is not provided the default value is false.	`false`

Delete Profile

Request:

curl -X DELETE \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/591 \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c'

Response: 200

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "errors": "Profile does not belong to account or does not exist."
}

This endpoint allows you to delete a profile.

HTTP Request

DELETE /dclid/profiles/{id}

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

Copy Profile

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/copy \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c'

Response: 200

{
    "profile": {
        "id": 594,
        "profile_name": "Updated NPA Profile",
        "default_callerid": "18558889768",
        "account_id": 190761,
        "use_lrn": "b'1'",
        "default_profile": false
    }
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Profile does not belong to account."
}

This endpoint allows you create a new profile with the same settings and mappings as an existing profile.

HTTP Request

POST /dclid/profiles/{id}/copy

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile to copy	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`Authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

Add NPA Mapping

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/npa \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{
    "mappings" :
    [
        {
            "callerid":7012648100 ,
            "npa":701
        }
    ]
}'

Response: 200

{
    "id": 19714,
    "profile_id": 593,
    "account_id": 190761,
    "iso2": null,
    "state_province": null,
    "npa": "701",
    "callerid": "17012648100",
    "prefix": null
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "status": "error",
  "errors": "Profile does not belong to account."
}

This endpoint allows you to add a single NPA mapping to a profile. A list of valid NPAs can be obtained using the GET /dclid/iso3s endpoint.

HTTP Request

POST /dclid/profiles/{id}/npa

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
mappings	array	true	Mapping array with a single element specifying the new NPA mapping.	`[{"callerid":4029999402 ,"npa":402 }]`

Add State Mapping

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/state \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{
    "mappings":[  
   {  
      "callerid":4029999402,
      "state_province":"SD"
   }
]
}'

Response: 200

{
    "id": 19715,
    "profile_id": 593,
    "account_id": 190761,
    "iso2": null,
    "state_province": "SD",
    "npa": null,
    "callerid": "14029999402",
    "prefix": null
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Not a valid state/province."
}

This endpoint allows you to add a single state mapping to a profile. A list of valid states can be obtained using the GET /dclid/iso3s endpoint.

HTTP Request

POST /dclid/profiles/{id}/state

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
mappings	array	true	Mapping array with a single element specifying the new state mapping.	`[{"callerid":4029999402 ,"state_province":"SD" }]`

Add Country Mapping

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/iso2 \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{
    "mappings":[  
   {  
      "callerid":4029999402,
      "iso2":"US"
   }
]
}'

Response: 200

{
    "id": 19716,
    "profile_id": 593,
    "account_id": 190761,
    "iso2": "US",
    "state_province": null,
    "npa": null,
    "callerid": "14029999402",
    "prefix": null
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Not a valid ISO2"
}

This endpoint allows you to add a single country mapping to a profile. A list of valid countries (IOS2s) can be obtained using the GET /dclid/iso3s endpoint.

HTTP Request

POST /dclid/profiles/{id}/iso2

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
mappings	array	true	Mapping array with a single element specifying the new country (ISO2) mapping.	`[{"callerid":4029999402 ,"iso2":"US" }]`

Add Prefix Mapping

Request:

curl -X POST \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/prefix \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{
    "mappings":[  
   {  
      "callerid":"4029999402",
      "prefix":"TAG01"
   }
]
}'

Response: 200

{
    "id": 28507,
    "profile_id": 593,
    "account_id": 190761,
    "iso2": null,
    "state_province": null,
    "npa": null,
    "callerid": "4029999402",
    "prefix": "TAG01"
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Please provide a prefix."
}

This endpoint allows you to add a single prefix mapping to a profile.

HTTP Request

POST /dclid/profiles/{id}/prefix

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
mappings	array	true	Mapping array with a single element specifying the new prefix mapping.	`[{"callerid":4029999402 ,"prefix":"TAG01" }]`

Retrieve Profile Mappings

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/mappings \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' 
'

Response: 200

{
    "mappings": [
        {
            "id": 19708,
            "profile_id": 593,
            "account_id": 190761,
            "iso2": null,
            "state_province": "OH",
            "npa": null,
            "callerid": "12167162398",
            "prefix": null
        },
        {
            "id": 19714,
            "profile_id": 593,
            "account_id": 190761,
            "iso2": null,
            "state_province": null,
            "npa": "402",
            "callerid": "14029999402",
            "prefix": null
        },
        {
            "id": 19715,
            "profile_id": 593,
            "account_id": 190761,
            "iso2": null,
            "state_province": "SD",
            "npa": null,
            "callerid": "14029999402",
            "prefix": null
        },
        {
            "id": 19716,
            "profile_id": 593,
            "account_id": 190761,
            "iso2": "US",
            "state_province": null,
            "npa": null,
            "callerid": "14029999402",
            "prefix": null
        }
    ]
}

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
    "status": "error",
    "errors": "Profile does not belong to account."
}

This endpoint allows you to retrieve the list of caller ID mappings associated to a profile.

HTTP Request

GET /dclid/profiles/{id}/mappings

URL Parameter	Type	Required	Description	Example
id	integer	true	ID of the profile	`593`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

Update Profile Mapping

Request:

curl -X PUT \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/mappings/19708 \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c' \
  -H 'content-type: application/json' \
  -d '{
    "mappings":[  
   {  
      "callerid":4029999402,
      "state_province":"NY"
   }
]
}'

Response: 200

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "errors": "Mapping does not belong to profile."
}

This endpoint allows you to update a profile mapping.

HTTP Request

PUT /dclid/profiles/{profile_id}/mappings/{mapping_id}

URL Parameter	Type	Required	Description	Example
profile_id	integer	true	ID of the profile	`593`
mapping_id	integer	true	ID of the mapping	`19708`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`
Content-Type	string	true	must be application/json	`Content-Type: application/json`

Body Param	Type	Required	Description	Example
mappings	array	true	Mapping array with a single element specifying the updated mapping.	`[{"callerid":4029999402 ,"state_province":"NY" }]`

Delete a Profile Mapping

Request:

curl -X DELETE \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/profiles/593/mappings/19708 \
  -H 'authorization: Token token=732d16da-2b75-11e8-a906-ac162d79d11c'

Response: 200

Response: 401

{
  "error": "Not Authorized"
}

Response: 422

{
  "errors": "Mapping does not belong to profile."
}

This endpoint allows you to delete a profile mapping.

HTTP Request

DELETE /dclid/profiles/{profile_id}/mappings/{mapping_id}

URL Parameter	Type	Required	Description	Example
profile_id	integer	true	ID of the profile	`593`
mapping_id	integer	true	ID of the mapping	`19708`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

DIDs

The Dialing Services REST API allows provides endpoints for you to determine the DIDs associated to your account.

Retrieve DIDs

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/dids \
  -H 'authorization: Token token=b523c2fa-2b82-11e8-a906-ac162d79d11c' \

Response: 200

{
    "dids": [

        {
            "did": "8444869747",
            "description": null,
            "trunk_group_id": 80989,
            "account_id": 190761
        },
        {
            "did": "8447577283",
            "description": "Main TFN",
            "trunk_group_id": 80989,
            "account_id": 190761
        },
        {
            "did": "8557858400",
            "description": "3CX Conf Bridge 2998",
            "trunk_group_id": 80989,
            "account_id": 190761
        }
    ]
}

Response: 401

{
  "error": "Not Authorized"
}

This endpoint retrieves the list of DIDs associated to the account.

HTTP Request

GET /dclid/dids

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

HTTP Request

GET /dclid/dids/{did}

URL Parameter	Type	Required	Description	Example
did	integer	true	The phone number assocaited to the account	`4029999402`

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

ISO3s

To assist with profile management, The Dialing Services REST API provides an endpoint that lists all the valid dialcodes, states and countries to be used for profile mappings.

Retrieve ISO3s

Request:

curl -X GET \
  https://servicelayer01.voxtelesys.net:3000/api/v1/dclid/iso3s \
  -H 'authorization: Token token=c19b690b-2bab-11e8-a906-ac162d79d11c'

Response: 200

{
  "iso3s": [
      {
        "dialcode": 7,
        "iso3": "EEU",
        "iso2": "RU",
        "nanp": 0,
        "state_province": null
      },
      {
        "dialcode": 20,
        "iso3": "AFF",
        "iso2": "EG",
        "nanp": 0,
        "state_province": null
      },
      {
        "dialcode": 27,
        "iso3": "AFF",
        "iso2": "ZA",
        "nanp": 0,
        "state_province": null
      },
      {
        "dialcode": 1209,
        "iso3": "USA",
        "iso2": "US",
        "nanp": 1,
        "state_province": "CA"
      }
  ]  
}

Response: 401

{
  "error": "Not Authorized"
}

This endpoint retrieves the full list of valid NPAs (dialcodes), states (state_provinces) and countries (ISO2s) that can be used to specify profile mappings.

HTTP Request

GET /dclid/iso2s

Header	Type	Required	Description	Example
Authorization	string	true	Token from authorization request	`authorization: Token token=6116504a-0cc2-419c-852c-442d3f3e2659`

Errors

The Dialer REST API uses the following HTTP error codes:

Code	Description
401	Unauthorized -- The provided token, request IP, and/or account are not valid. Use the `/authorize/login` to obtain a valid token.
404	Not Found -- The request URL and/or HTTP method is not valid.
422	Unprocessable Entity -- The request data and/or parameters are not valid.
500	Internal Server Error -- An error occurred within the server. Please contact Voxtelesys with the provided `error_id` to resolve this error.

Dialing Services API Introduction

Base URL

Authentication

Basic Authentication

Login Request

Token Authentication

All Services

Retrieve All Services

HTTP Request

Cellular Number Identification

Retrieve Number Type

HTTP Request

Bulk Retrieve Number Type

HTTP Request

Do-Not-Call

Retrieve DNC

HTTP Request

Bulk Retrieve DNC

HTTP Request

Retrieve DNC List

HTTP Request

HTTP Request

Create DNC Entry

HTTP Request

Delete DNC Entry

HTTP Request

Dynamic Caller ID

Retrieve Dynamic Caller ID

HTTP Request

Bulk Retrieve Dynamic Caller ID

HTTP Request

Dynamic Caller ID Profiles

Retrieve Profiles

HTTP Request

HTTP Request

Create Profile

HTTP Request

Create Profile with NPA Mappings

HTTP Request

Create Profile with State Mappings

HTTP Request

Update Profile

HTTP Request

Delete Profile

HTTP Request

Copy Profile

HTTP Request

Add NPA Mapping

HTTP Request

Add State Mapping

HTTP Request

Add Country Mapping

HTTP Request

Add Prefix Mapping

HTTP Request

Retrieve Profile Mappings

HTTP Request

Update Profile Mapping

HTTP Request

Delete a Profile Mapping

HTTP Request

DIDs

Retrieve DIDs

HTTP Request

HTTP Request

ISO3s

Retrieve ISO3s

HTTP Request

Errors