Interaction Center Web Services (ICWS)

/icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}

Feature	Version	Obsolete Version
directories	4

PUT

/icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}

Creates or updates a subscription to a directory.

Feature	Version	Obsolete Version
directories	4

Request

Parameters

Type

Name

Comments

Header

ININ-ICWS-CSRF-Token

Required

The ININ session token necessary for all calls that require a security or user context.

Header

Required

The session cookie. With the exception of the connection request, all requests must provide a session cookie.

Template

sessionId

Required

The ININ session ID necessary for all calls that require a security or user context.

Template

subscriptionId

Required

The subscription ID.

Representations

directorySubscriptionParameters

Expand All Collapse All

Property

Value

Comments

__type

"urn:inin.com:directories:directorySubscriptionParameters"

Required

The JSON type representing this option.

count

Int

The count of contact entries to retrieve. The default is 25 if not specified as part of the request. The maximum value for count is 300. ICWS uses the MaxDirectoryStatusWatches and ClientDirectoryPageSize server parameters in calculating how many contacts to send back. If count is less than or equal to MaxDirectoryStatusWatches, ICWS will not consider ClientDirectoryPageSize, and return the number of contact entries requested. If count is greater than the than MaxDirectoryStatusWatches, or if MaxDirectoryStatusWatches doesn't exist, ICWS will return a number of contact entries equal to ClientDirectoryPageSize. If ClientDirectoryPageSize doesn't exist, ICWS will return a number of contact entries equal to the lesser of 25 (the default for count when it is not part of the request) and the number of contact entries requested.

Note

In directory version 8 new server parameters MaxSpeedDialPageSize and DefaultSpeedDialPageSize are added for calculating how many contacts to send back for Speed-Dial Directory. The behaviour remains the same but use "MaxSpeedDialPageSize" instead of "MaxDirectoryStatusWatches" and use "DefaultSpeedDialPageSize" instead of "ClientDirectoryPageSize" for Speed Dial Directory.

filterItems

List [1,*]: Complex Type: contactFilterItem

The list of filter items.

contactProperty

Enumeration: contactProperty

Required

The property to filter on.

entryID

Represents the entryID property.

firstName

Represents the firstName property.

lastName

Represents the lastName property.

extension

Represents the extension property.

userID

Represents the userID property.

department

Represents the department property.

company

Represents the company property.

title

Represents the title property.

businessAddress

Represents the businessAddress property.

businessCity

Represents the businessCity property.

businessState

Represents the businessState property.

businessZipCode

Represents the businessZipCode property.

businessCountry

Represents the businessCountry property.

businessEmail

Represents the businessEmail property.

assistant

Represents the assistant property.

homeCountry

Represents the homeCountry property.

homeEmail

Represents the homeEmail property.

businessPhone

Represents the businessPhone property.

businessPhone2

Represents the businessPhone2 property.

homePhone2

Represents the homePhone2 property.

mobilePhone

Represents the mobilePhone property.

fax

Represents the fax property.

pager

Represents the pager property.

assistantPhone

Represents the assistantPhone property.

primaryNumberDesignation

Represents the primaryNumberDesignation property.

notes

Represents the notes property.

displayName

Represents the displayName property.

homeAddress

Represents the homeAddress property.

homeCity

Represents the homeCity property.

homeState

Represents the homeState property.

homeZipCode

Represents the homeZipCode property.

homePhone

Represents the homePhone property.

voicemailLocation

Represents the voicemailLocation property.

workgroups

Represents the workgroups property.

ownerID

Represents the ownerID property.

alias

Represents the alias property.

accessRights

Represents the accessRights property.

trackerData

Represents the trackerData property.

statusURI

Represents the statusURI property.

externalPresenceProviders

Represents the externalPresenceProviders property.

contactSources

Represents the contactSources property.

externalContactEntries

Represents the externalContactEntries property.

skills

Represents the skills property.

statusMessage

Represents status message ID property.

Feature	Version	Obsolete Version
directories	12

statusLoggedIn

Represents logged in property.

Feature	Version	Obsolete Version
directories	12

statusOnPhone

Represents on the phone property.

Feature	Version	Obsolete Version
directories	12

statusNotes

Represents status notes property.

Feature	Version	Obsolete Version
directories	12

statusForwardNumber

Represents forward number property.

Feature	Version	Obsolete Version
directories	12

statusUntil

Represents status until time property.

Feature	Version	Obsolete Version
directories	12

statusDuration

Represents time in status property.

Feature	Version	Obsolete Version
directories	12

statusActivated

Represents status activated property.

Feature	Version	Obsolete Version
directories	12

filterType

Enumeration: contactFilterType

Required

The type of filter.

exact

The filter matches a property exactly.

prefix

The filter matches the prefix of a property's value.

exists

The filter matches if the property exists. That is it has a non-empty value.

empty

The filter matches if the property value is empty. That is it does not have a value.

wildcards

The filter matches using a expression that contains wildcards. The filter expression may contain wildcard symbols. A "*" will match zero or more characters. A "?" will match any single character. For example "Dev*" would match "Developers", "Development-Asia", and "Devices". "T?m" would match "Tim" and "Tom" but not "Team". This filter type is not allowed for the accessRights property.

filterExpressions

List [1,*]: String

Required

The string expressions for this filter.

index

Int

The zero-based entry index to start retrieving.

sortItems

List [1,*]: Complex Type: contactSortItem

The list of sort items.

contactProperty

Enumeration: contactProperty

Required

The property to sort on.

entryID

Represents the entryID property.

firstName

Represents the firstName property.

lastName

Represents the lastName property.

extension

Represents the extension property.

userID

Represents the userID property.

department

Represents the department property.

company

Represents the company property.

title

Represents the title property.

businessAddress

Represents the businessAddress property.

businessCity

Represents the businessCity property.

businessState

Represents the businessState property.

businessZipCode

Represents the businessZipCode property.

businessCountry

Represents the businessCountry property.

businessEmail

Represents the businessEmail property.

assistant

Represents the assistant property.

homeCountry

Represents the homeCountry property.

homeEmail

Represents the homeEmail property.

businessPhone

Represents the businessPhone property.

businessPhone2

Represents the businessPhone2 property.

homePhone2

Represents the homePhone2 property.

mobilePhone

Represents the mobilePhone property.

fax

Represents the fax property.

pager

Represents the pager property.

assistantPhone

Represents the assistantPhone property.

primaryNumberDesignation

Represents the primaryNumberDesignation property.

notes

Represents the notes property.

displayName

Represents the displayName property.

homeAddress

Represents the homeAddress property.

homeCity

Represents the homeCity property.

homeState

Represents the homeState property.

homeZipCode

Represents the homeZipCode property.

homePhone

Represents the homePhone property.

voicemailLocation

Represents the voicemailLocation property.

workgroups

Represents the workgroups property.

ownerID

Represents the ownerID property.

alias

Represents the alias property.

accessRights

Represents the accessRights property.

trackerData

Represents the trackerData property.

statusURI

Represents the statusURI property.

externalPresenceProviders

Represents the externalPresenceProviders property.

contactSources

Represents the contactSources property.

externalContactEntries

Represents the externalContactEntries property.

skills

Represents the skills property.

statusMessage

Represents status message ID property.

Feature	Version	Obsolete Version
directories	12

statusLoggedIn

Represents logged in property.

Feature	Version	Obsolete Version
directories	12

statusOnPhone

Represents on the phone property.

Feature	Version	Obsolete Version
directories	12

statusNotes

Represents status notes property.

Feature	Version	Obsolete Version
directories	12

statusForwardNumber

Represents forward number property.

Feature	Version	Obsolete Version
directories	12

statusUntil

Represents status until time property.

Feature	Version	Obsolete Version
directories	12

statusDuration

Represents time in status property.

Feature	Version	Obsolete Version
directories	12

statusActivated

Represents status activated property.

Feature	Version	Obsolete Version
directories	12

sortDirection

Enumeration: sortDirection

Required

The direction of the sort.

ascending

An ascending (A-Z) sort order.

descending

A descending (Z-A) sort order.

directoryID

String

Required

The directory ID for this subscription.

Response

204 - No Content

The directory subscription has been updated.

Associated Message

The directory contents have changed.

directoryMessage

Expand All Collapse All

Property

Value

Comments

__type

"urn:inin.com:directories:directoryMessage"

Required

The JSON type representing this option.

isDelta

Boolean

Required

When true, this property indicates that some optional properties that have not changed may be omitted (all required properties will be included). In this case, the client side cache should be updated with the values for the properties provided and no change should be made for the properties not included as part of the message. This allows the API to deliver smaller messages that only represent the properties that have changed.

When this property is false, the client side cache for this subscription should be cleared and replaced with the data provided in the message. For the initial message in response to a subscription, this property will be false to indicate the cache should be initialized with the data provided.

totalCount

Int

This number represents the total number of contacts in the directory. This value will always be greater than, or equal to filteredCount.

filteredCount

Int

This number represents the total number of contacts that match the subscription parameters. This value will always be less than or equal to totalCount.

contactsAdded

List [Unbounded]: Complex Type: contactEntry

The set of directory contacts that have been added.

__type

"urn:inin.com:directories:contactEntry"

Required

The JSON type representing this option.

accessRights

Complex Type: contactAccessRights

The contact's access rights. If the contact has no access right, this property will be omitted.

read

Boolean

Permission to read a contact entry.

create

Boolean

Permission to create a contact entry.

update

Boolean

Permission to update a contact entry.

delete

Boolean

Permission to delete a contact entry.

assistant

String

The name of the contact's assistant or subordinate.

businessAddress

String

The contact's business address.

businessCity

String

The contact's business city.

businessCountry

String

The contact's business country.

businessEmail

String

The contact's business email address.

businessState

String

The contact's business state.

businessZipCode

String

The contact's business zip code.

company

String

The company that this contact works for.

department

String

The department that this contact works in.

displayName

String

The contact's display name. Usually this is Lastname, Firstname.

firstName

String

The contact's first name.

homeAddress

String

The contact's number and street, apartment, etc.

homeCity

String

The home address city.

homeCountry

String

The country associated with the contact's home address.

homeEmail

String

The contact's personal Email address.

homeState

String

The state where the home is located.

homeZipCode

String

The home address zip code.

lastName

String

The contact's last name.

notes

String

The note text, if any, that is stored in this contact entry.

primaryNumberDesignation

Enumeration: defaultPhoneNumberType

Specifies which directory contact property is the primary number.

Feature	Version	Obsolete Version
directories	7

none

-1

Identifies that there is no default phone number designated.

Feature	Version	Obsolete Version
directories	7

extension

Identifies the extension field as the default phone number.

businessPhone

Identifies the business phone field as the default phone number.

businessPhone2

Identifies the business phone 2 field as the default phone number.

homePhone

Identifies the home phone field as the default phone number.

homePhone2

Identifies the home phone 2 field as the default phone number.

mobilePhone

Identifies the mobile phone field as the default phone number.

faxPhone

Identifies the fax phone field as the default phone number.

pagerPhone

Identifies the page phone field as the default phone number.

assistantPhone

Identifies the assistant phone field as the default phone number.

statusURI

String

The contact's Status URI.

title

String

The contact's job title.

alias

String

The contact's alias.

assistantPhone

Complex Type: phoneNumber

The assistant's telephone number.

Property type documentation:

Represents a phone number.

standardizedNumber

String

Required

The standardized phone number.

displayString

String

Required

The phone number's display string.

numberInfo

Complex Type: editablePhoneNumber

It contains the base-number,extension and auto dial information.

Feature	Version	Obsolete Version
directories	8

baseNumber

String

The phone number.

extension

String

The extension.

autoDialable

Boolean

Whether or not the extension is a auto dialable.

editNumber

String

The string to use when editing the phone number. This property contains the phone number and/or an extension. They are delimited by /^ when the extension is autodialed, and just ^ when it isn't. Extensions without a number will always be returned as autodialed.

Note

editNumber has been marked obsolete. displayString can be used in its place, as it provides identical information. Alternatively numberInfo can be used for to retrieve similar information as it contains the parsed information found in displayString.

Feature	Version	Obsolete Version
directories	6	8

dialable

Boolean

Whether or not the returned number is a dialable number.

businessPhone

Complex Type: phoneNumber

The contact's business phone.

Property type documentation:

Represents a phone number.

businessPhone2

Complex Type: phoneNumber

The contact's alternate business phone.

Property type documentation:

Represents a phone number.

entryID

String

Required

A unique identifier for the contact.

extension

String

The contact's extension.

fax

Complex Type: phoneNumber

The telephone number of the contact's Fax machine.

Property type documentation:

Represents a phone number.

homePhone

Complex Type: phoneNumber

The contact's home telephone number.

Property type documentation:

Represents a phone number.

homePhone2

Complex Type: phoneNumber

The contact's secondary home phone number.

Property type documentation:

Represents a phone number.

index

Int

Required

The zero-based index of this contact within the directory subscription's current page.

mobilePhone

Complex Type: phoneNumber

The contact's mobile phone number.

Property type documentation:

Represents a phone number.

ownerID

String

The owner of this contact entry.

pager

Complex Type: phoneNumber

The contact's pager number.

Property type documentation:

Represents a phone number.

skills

List [Unbounded]: String

The Skills that this contact has.

trackerData

String

The tracker data.

userID

String

The contact's user ID.

voicemailLocation

String

The contact's voicemail location.

workgroups

List [Unbounded]: String

The workgroups that this contact is a member of.

activated

Boolean

Indicates if the user is activated on the current workgroup.

Feature	Version	Obsolete Version
directories	5

statusID

String

The ID of the status message that the specified contact is currently set to.

The value represented by this property should be treated as case-insensitive.

This property can be null.

statusSummary

Complex Type: statusSummary

The directory contact's status notes. This property will only be provided if the logged-in user has View access for the "Status Summary" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Status Summary"	Directory Status Columns - Status Summary - View

This property can be null.

statusID

String

Required

The ID of the status message that the specified contact is currently set to.

The value represented by this property should be treated as case-insensitive.

loggedIn

Boolean

Required

Whether the contact is logged in.

onPhone

Boolean

Required

Whether the contact is on the phone.

statusNotes

String

The directory contact's status notes. This property will only be provided if the logged-in user has View access for the "Notes" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Status Notes"	Directory Status Columns - Notes - View

This property can be null.

forwardNumber

Complex Type: phoneNumber

The directory contact's forward number. This property will only be provided if the logged-in user has View access for the "Forward Number" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Forward Number"	Directory Status Columns - Forward Number - View

This property can be null.

Property type documentation:

Represents a phone number.

until

Complex Type: userStatusUntil

The contact's status until time. This property will only be provided if the logged-in user has View access for the "Until" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Until"	Directory Status Columns - Until - View

This property can be null.

Property type documentation:

Note

Clients must supply a complete UTC dateTime, regardless of the user specifying only date or only time. The hasDate and hasTime members have to do with UI, not the completeness of untilDateTime. If a user specifies only a date, clients must use the UTC dateTime converted from midnight local time for that date. If a user specifies only a time, clients must use the UTC dateTime converted from today's date at that local time.

untilDateTime

DateTime

Required

The status until date and time.

Note

This property will only be applied if CanHaveDate and CanHaveTime are true.

hasDate

Boolean

Required

This has to do with UI, not the untilDateTime.

hasTime

Boolean

Required

This has to do with UI, not the untilDateTime.

onPhone

Boolean

The contact's onPhone status. This property will only be provided if the logged-in user has View access for the "On Phone" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "On Phone"	Directory Status Columns - On Phone - View

This property can be null.

onPhoneChanged

DateTime

The directory contact's status onPhoneChanged. This property will only be provided if the logged-in user has View access for the "On Phone" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "On Phone"	Directory Status Columns - On Phone - View

This property can be null.

statusChanged

DateTime

The directory contact's statusChanged. This property will only be provided if the logged-in user has View access for the "Time In Status" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Time In Status"	Directory Status Columns - Time In Status - View

This property can be null.

loggedIn

Boolean

The directory contact's status loggedIn. This property will only be provided if the logged-in user has View access for the "Logged In" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Logged In"	Directory Status Columns - Logged In - View

This property can be null.

stations

List [Unbounded]: String

The directory contact's status stations. This property will only be provided if the logged-in user has View access for the "Logged In" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Logged In"	Directory Status Columns - Logged In - View

This property can be null.

icServers

List [Unbounded]: String

The directory contact's status icServers. This property will only be provided if the logged-in user has View access for the "Logged In" ACL in the "Directory Status Columns" group.

Access Restrictions

Type	API Name	UI Name
Access Right	viewStatusColumns "Logged In"	Directory Status Columns - Logged In - View

This property can be null.

contactsChanged

List [Unbounded]: Complex Type: contactEntry

The set of directory contacts that have been changed. Each contactEntry in this list will only contain changed properties, and their new values, with the exception of entryID, as it's needed to uniquely-identify the contactEntry.

contactsRemoved

List [Unbounded]: String

The set of directory contact entryIDs that have been removed.

subscriptionId

String

Required

The subscription's ID.

403 - Forbidden

The session user does not have permission to query this directory.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

404 - Not Found

The directory does not exist.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

405 - Method Not Allowed

A timeout occurred while waiting for the directory contacts to load.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

400 - Bad Request

The request was invalid. This can occur when the message body is malformed or missing required items. This will also occur if a required header or query string parameter is missing or invalid.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

401 - Unauthorized

The specified session token is missing, invalid, or has expired.

Parameters

Type

Name

Comments

Header

WWW-Authenticate

Required

Indicates that the client needs to authenticate using a custom ICWS scheme, which supports a realm of type ICWS and a location which is the URL at which the client can authenticate. A typical example would be the following.


								WWW-Authenticate: ICWS realm="ICWS" location="/ICWS/connection"

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

410 - Gone

This resource has been deprecated and removed from the API.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

500 - Internal Server Error

An unexpected error occurred while processing the request.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

DELETE

/icws/{sessionId}/messaging/subscriptions/directories/{subscriptionId}

Deletes the directory subscription.

Feature	Version	Obsolete Version
directories	4

Request

Parameters

Type

Name

Comments

Header

ININ-ICWS-CSRF-Token

Required

The ININ session token necessary for all calls that require a security or user context.

Header

Required

The session cookie. With the exception of the connection request, all requests must provide a session cookie.

Template

sessionId

Required

The ININ session ID necessary for all calls that require a security or user context.

Template

subscriptionId

Required

The subscription ID.

Response

204 - No Content

The directory subscription was deleted.

400 - Bad Request

The request was invalid. This can occur when the message body is malformed or missing required items. This will also occur if a required header or query string parameter is missing or invalid.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

401 - Unauthorized

The specified session token is missing, invalid, or has expired.

Parameters

Type

Name

Comments

Header

WWW-Authenticate

Required


								WWW-Authenticate: ICWS realm="ICWS" location="/ICWS/connection"

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

410 - Gone

This resource has been deprecated and removed from the API.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.

500 - Internal Server Error

An unexpected error occurred while processing the request.

error

Provides additional detail for an error.

Expand All Collapse All

Property

Value

Comments

errorId

String

The error identifier that describes the current error.

message

String

Required

A message that describes the current error.