Directories API

Directories enable callers to use a directory to search for a user or device by name, instead of by extension or direct dial number. They can enter digits (DTMF) that represent the first or last name of the person they are trying to reach and then route their call accordingly. Use the Directories API to manage directories on the account.

API calls

Click on each call to view the endpoint, method, and request example.

Parameters

The table shows the possible parameters available for directories requests.

Key Description Type Options/Min/Max/Default
name Required. The name of the directory string (1..)
confirm_match When one match is found, require caller to confirm the match before connecting. boolean The default is true.
flags.[] Specific flags. string
flags Flags set by external applications. array
max_dtmf Caps the number of DTMF characters collected from a caller. integer The default is 0 for unlimited characters.
min_dtmf Specficies many DTMF characters to collect from a caller as least before processing the directory. integer
sort_by Specifies which field to sort on in matching documents when a caller enters characters. string first_name, last_name The default is last_name.
users.[] Specific users. string
users The list of users associated with this directory. array

Get directories

Returns a list of directories in the account.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/directories

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": [
          {
              "id": "77dfb38ff2353624e35bf4df91acda94",
              "name": "SmartPBX Directory"
          }
      ],
      "page_size": 1,
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }

Remove a directory

Removes a directory from the account.

Method and endpoint

DELETE /v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

Get a directory

Returns a specific directory.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories/77dfb38ff2353624e35bf4df91acda94

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "confirm_match": false,
        "id": "77dfb38ff2353624e35bf4df91acda94",
        "max_dtmf": 0,
        "min_dtmf": 3,
        "name": "SmartPBX Directory",
        "sort_by": "last_name",
        "ui_metadata": {
            "origin": "voip",
            "ui": "monster-ui",
            "version": "3.23"
        },
        "users": []
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Get directory as PDF

Streams back the directory as a PDF document for download (such as a company directory, a sales department directory, and so on).

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Accept: application/pdf"
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

NOTE: If your client does not support setting the Accept header, you can append ?accept=pdf to the URI and the API pretends that you sent the proper Accept header.