Navbar
shell
  • Dialing Services API Introduction
  • Authentication
  • All Services
  • Cellular Number Identification
  • Do-Not-Call
  • Dynamic Caller ID
  • Dynamic Caller ID Profiles
  • DIDs
  • ISO3s
  • Errors
  • 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.

    Login Request

    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.