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.

Get directories
Remove a directory
Get a directory
Get directory as PDF

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.