The Directories service provides the ability to perform various directory-related operations:
directoryID property from an associated directory metadata subscription response. Directory subscriptions provide a way to retrieve contact entries that are associated with the specified directory, as well as the ability to watch for contact additions, changes, and removals for the directory.See Event Subscriptions and Messaging for information on how to work with subscriptions.
See Session Requests for information on the parameters necessary to perform Session Requests.
Jump to a section that describes each area of the directories API:
The directory metadata subscription provides the ability to retrieve information about the directories in the IC System that the logged in user has access to. The URI pattern to start a directory metadata subscription is:
PUT /icws/{sessionId}/messaging/subscriptions/directoriesThere are no other parameters needed for this request. A 204 HTTP status code with an empty response body will be returned if the directory metadata subscription was successfully started.
After starting a directory metadata subscription, the ICWS-based application must watch for the urn:inin.com:directories:directoriesMessage message type in order to retrieve the associated directory metadata changes. This message type will contain information for the directory metadata such as directoriesAdded, directoriesChanged, and directoriesRemoved.
To remove a directory subscription, use the following URI pattern:
DELETE /icws/{sessionId}/messaging/subscriptions/directoriesThere are no other parameters needed for this request. A 204 HTTP status code with an empty response body will be returned if the directory metadata subscription was successfully removed.
Directory subscriptions provide the ability to retrieve information about the objects that are contained within specified IC System directories. The URI pattern to start a directory subscription is:
PUT /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}The {subscriptionId} can be assigned arbitrarily and should be managed by the ICWS-based application
There are a few request parameters that can be used when starting a directory subscription to tailor the results to what is needed, including count, filterItems, index, sortItems, and directoryId. The only required parameter of these is directoryId, which can be obtained from the directoryId property from the urn:inin.com:directories:directoriesMessage message type's representation that comes from a directory metadata subscription. For example, to get the first 100 contacts for a directory with the ID of "companyDirectory", the ICWS-based application would need to send the following request:
PUT /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}
{
"__type" : "urn:inin.com:directories:directorySubscriptionParameters",
"count" : 100,
"directoryId" : "companyDirectory"
}In order to return the first 100 directory contacts from the "companyDirectory" that are in the "Development" or "Support" departments, sorted ascending by lastName, the ICWS-based application would need to send the following request:
PUT /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}
{
"__type" : "urn:inin.com:directories:directorySubscriptionParameters",
"count" : 100,
"directoryId" : "companyDirectory",
"filterItems" : [{
"contactProperty" : 5,
"filterType" : 0,
"filterExpressions" : ["Development", "Support"]
}
],
"sortItems" : [{
"contactProperty" : 2,
"sortDirection" : 0
}
]
}A 204 HTTP status code with an empty response body will be returned if the directory subscription was successfully started.
After starting a directory subscription, the ICWS-based application must watch for the urn:inin.com:directories:directoryMessage message type in order to retrieve the associated directory changes. This message type will contain information for the directory such as contactsAdded, contactsChanged, and contactsRemoved.
To remove a directory subscription, use the following URI pattern:
DELETE /icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}In the previous snippet, {subscriptionId} will be the same subscriptionId that the ICWS-based application assigned in the PUT request.
A 204 HTTP status code with an empty response body will be returned if the directory subscription was successfully removed.
Lookup entries provide the ability to search IC System directories for objects based on supplied query parameters. The URI pattern to perform a lookup entry search is:
POST /icws/{sessionId}/directories/lookup-entriesThe logged in user must have the appropriate search rights configured in Interaction Administrator for results to be included. These search rights can be found in the Access Control container under the Search column.
Additionally, when specifying AttendantProfile (lookupEntryType value 5), attendant profiles can only be included in the lookup results if the logged in user has the sufficient search rights assigned. From within Interaction Administrator, the logged in user must have the search rights for the appropriate Email/Inbound/Operator/Outbound profiles set in the Access Control container. Additionally, the attendant profile must also be setup to be a transfer target from within Interaction Attendant.
There are a few request parameters that must be used when requesting lookup entries including lookupEntryTypes, lookupEntryProperties, lookupComparisonType, lookupString, and maxEntries. All of these parameters are required. The following requests the first 100 Users or Workgroups with an extension, businessPhone1, or businessPhone2 that contains "5555":
POST /icws/{sessionId}/directories/lookup-entries
{
"lookupEntryTypes" : [1, 6],
"lookupEntryProperties" : [6, 11, 12],
"lookupComparisonType" : 3,
"lookupString" : "5555",
"maxEntries" : 100
}A 200 HTTP status code will be returned with the lookup entry results in the message body if the lookup entry request was successful. The lookup entry results will have lookupEntriesList, moreEntriesMatched, and phoneNumber properties that represent the search results.