Provisioning REST API

API Developers reference#


4. Provisioning REST API#


4.1 /Agents resource#

Supported methods:GET
Arguments :None
Response Codes :200 OKRequest Succeeded
401 UnauthorizedNo or invalid token supplied (see 1.4.2)
403 ForbiddenAgent not permitted to provision
Response Body :AgentsProvisionedAgent[]Required
Since Version :1
Provisioning Models :System

Agents The /Agents resource allows administrators and advanced agents to view all existing agents. A ProvisionedAgent has the following members:

Id (string) : the unique ID of the agent

UserName (string) : the username the agent will use to log into the chat system with

Channels (List{ProvisionedChannel}) : the channels the agents is allowed to use

MetaData (Dictionary{string,string}) : the agent’s custom meta-data

ProvisioningMode (ProvisioningMode) : the agent’s level of access to the provisioning API (v18.6+, takes priority over CanProvision)

CanProvision (Boolean) : true if the agent can access the provisioning API

State (ProvisionedAgentState) : the current state of the agent

Users (List{String}) : the IDs of the users who may use the agent

ProvisionedChannels have the following members:

Id (string) : the ID of the channel. Can be retrieved from the/Channels resource.

State (ProvisionedChannelState) : the current state of the channel

ProvisionedAgentState and ProvisionedChannelState are enumerations with the following values:

  • 0: Idle
  • 1: Activating
  • 2: Active

ProvisioningMode (v18.6+) is an enumeration with the following values:

0: Unspecified : will not be returned by a GET; when used in a PUT, uses CanProvision instead. This is the default value.

1: None : the agent cannot access the provisioning API.

2: System : the agent can access all operations of the provisioning API.

3: Self : the agent can access the provisioning API only to access/modify its own data.

See the “Provisioning modes” row on each table in this section for more information on which provisioning modes have access to which operations.


4.2 /Agents/{agentId} resource#

Supported methods:PUT, GET, DELETE
Arguments :{agentId}StringRequired
< agent >ProvisionedAgentRequired for PUT
Response Codes :200 OKRequest Succeeded
400 Bad RequestAttempted to PUT agent with incorrect ID
401 UnauthorizedNo or invalid token supplied (see 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1.3.1)
404 Not FoundAttempted to GET/DELETE unknown agent
Response Body :AgentProvisionedAgentFor GET requests
(no response)for PUT/DELETEs
Since Version :1
Provisioning Models :System

Agents AgentId The /Agents/{agentId} resource allows administrators and advanced agents to view, create, modify and delete agents by their ID.See the /Agents resource for details of the ProvisionedAgent type. Note that the State member of both ProvisionedAgent and ProvisionedChannel is read-only, and cannot be modified with a PUT request.When creating or updating an agent with a PUT request, the ID passed as a property of the ProvisionedAgent must match the ID in the resource URL. If they do not match, the API will return a 400 Bad Request response.


4.3 /Agents/{agentId}/Channels resource#

Supported methods:GET
Arguments :{agentId}StringRequired
Response Codes :200 OKRequest Succeeded
401 UnauthorizedNo or invalid token specified(see 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1.3.1)
404 Not FoundAgent ID is not known
Response Body :ChannelsProvisionedChannels[]Required
Since Version :1
Provisioning models :System, Self (for own ID)

Agents AgentId Channels The /Agents/{agentId}/Channels resource returns all channels that the agent with the specified ID is provisioned to access. See the /Agents resource for details of the ProvisionedChannel type Note that this resource is read-only. To add or remove channels, use the /Agents/{agentId}/Channels/{channelId} resource. Also note that self-provisioning agents can use this resource, but only if the given agentId is their own.


4.4 /Agents/{agentId}/Channels/{channelId} resource#

Supported methods:PUT, DELETE
Arguments :{agentId}String
{ChannelId}StringRequired
Response Codes :200 OKRequest Succeeded
304 Not ModifiedPUT request has no effect
400 Bad RequestAttempted to PUT invalid channel
401 UnauthorizedNo or invalid token supplied (see 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1,3,1)
404 Not FoundAgent or channel not found
Response Body :(no response)
Since Version :1
Provisioning modes :System, Self (for own ID)

Agents AgentId Channels ChannelId The /Agents/{agentId}/Channels/{channelId} resource allows provisioned channels to be added or removed from an agent. Channel IDs can be retrieved from the/Channels resource.


4.5 /Agents/{agentId}/MetaData resource#

Supported methods:GET, PUT
Arguments :{agentId}StringRequired
< metadata >
Response Codes :200 OKRequest Succeeded
401 UnauthorizedNo or invalid token supplied (see 1.4.2)
304 ForbiddenAgent not permitted to provision (see 1.3.1)
404 Not FoundAgent ID is not known
Response Body :MetadataDictionaryFor GET only
Since Version :1
Provisioning modes :System, Self (for own ID)

Agents AgentId MetaData The /Agents/{agentId}/MetaData resource allows retrieval or replacement of all of an agent’s meta-data in one operation.Individual meta-data keys can be modified via the /Agents/{agentId}/MetaData/{key} resource.


4.6 /Agents/{agentId}/MetaData/{key} resource#

Supported methods:PUT, GET, DELETE
Arguments :{agentId}StringRequired
{key}StringRequired
< value >StringRequired for PUT
Response Codes :200 OKRequest Succeeded
401 UnauthorizedNo or invalid token supplied (see 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1.3.1)
404 Not FoundAgent or key not found
Response Body :ValuesStringFor GET requests
(no response)For PUT/DELETEs
Since Version :1
Provisioning modes :System, Self (for own ID)

Agents AgentId MetaData Key The /Agents/{agentId}/MetaData/{key} resource allows individual meta-data key/value pairs to be viewed, created, modified and deleted.


4.7 /Channels resource#

Supported methods:GET
Arguments :queryStringRequired
Response Codes :200 OKRequest Succeeded
400 Bad RequestNo valid agent associated with token or bad search parameters
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1.3.1)
Response Body :ChannelsDictionaryRequired
Since Version :1
Provisioning modes :Self, System

Channels The /Channels resource allows administrators and advanced agents to search for channels by their display name.A dictionary containing all channels matching the given query string will be returned. The dictionary maps channel IDs onto display names. The search parameter cannot be empty, otherwise a 400 Bad Request will be returned.This method requires the currently authorised user to have specified a valid agent when they acquired their token, otherwise a 400 Bad Request will be returned.


4.8 /Users resource#

Supported methods:GET
Arguments :none
Response Codes :200 OKRequest Succeeded
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1.3.1
Response Body :UsersProvisionedUser[]Required
Since Version :1
Provisioning modes :System

Users The /Users resource allows administrators and advanced agents to view all existing users. Users are associated with agents by inserting their IDs into the agent’s configuration via the /Agents/{agentId} resource.A ProvisionedUser has the following members:

UserId (string) : the unique ID of the user

UserName (string) : the username the user will use to authenticate

As of version 1, the UserName must be a user found in Active Directory in the format of DOMAIN\user.


4.9 /Users/{userId} resource#

Supported methods:PUT, GET DELETE
Arguments :{userId}StringRequired
< user >ProvisionedUserRequired for PUT
Response Codes :200 OKRequest Succeeded
400 Bad RequestAttempted to PUT user with incorrect ID
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent not permitted to provision (see 1.3.1)
404 Not FoundAttempted to GET/DELETE unknown user
Response Body :UserProvisionedUserFor GET requests
(no response)For PUT/DELETEs
Response Body :UserProvisionedUserFor GET requests
(no response)For PUT/DELETEs
Since Version :1
Provisioning modes :System

Users UserId The /Users/{userId} resource allows administrators and advanced agents to view, create, modify and delete users by their ID.See the /Channels resource for details of the ProvisionedUser type. Users are associated with agents by inserting their IDs into the agent’s configuration via the /Agents/{agentId} resource.When creating or updating a user with a PUT request, the ID passed as a property of the ProvisionedUser must match the ID in the resource URL. If they do not match, the API will return a 400 Bad Request response.


4.10 /Throttles resource#

Supported methods:GET
Arguments :None
Response Codes :200 OKRequest Succeeded
401 UnauthorizedNo or invalid token supplied (See 1.4.2)
403 ForbiddenAgent not permitted to provision
Response Body :ThrottlesProvisionedThrottle[]Required
Provisioning modes :System

Throttles The /Throttles resource allows administrators and advanced agents to view all existing throttles.A ProvisionedThrottle has the following members:

Id (string) : the unique ID of the throttle.

Type (ProvisionedThrottleType) : the type of the throttle.

Threshold (int) : The maximum number of operations the throttle will allow (the behaviour of this depends on the (ProvisionedThrottleType).

Agents (List) : The IDs of agents to which the throttle will apply.

ProvisionedThrottleType is an enumeration with the following values:

0: MessagesPerMinute
1: TargetedMessagesPerMinute
2: ConcurrentTransfers

4.11 /Throttles/{throttleId} resource#

Supported methods:PUT, GET DELETE
Arguments :{ThrottleId}StringRequired
< Throttle >ProvisionedThrottleRequired for PUT
Response Codes :200 OKRequest Succeeded
400 Bad RequestAttempted to PUT throttle with incorrect ID
401 UnauthorizedAttempted to PUT throttle with different type
403 ForbiddenNo or invalid token supplied (See 1.4.2)
404 Not FoundAgent not permitted to provision (see 1.3.1)Attempted to GET/DELETE unknown throttle
Response Body :throttleProvisionedThrottleFor GET requests
(no response)For PUT/DELETEs
Since Version :1
Provisioning mode :System

Throttles ThrottleId The /Throttles/{throttleId} resource allows administrators and advanced agents to view, create, modify and delete throttles by their ID.See the /Throttles resource for details of the ProvisionedThrottle type.When creating or updating a throttle with a PUT request, the ID passed as a property of the ProvisionedThrottle must match the ID in the resource URL. If they do not match, the API will return a 400 Bad Request response.When updating a throttle with a PUT request, the Type property must be preserved; otherwise the API will return a 400 Bad Request response. This is to simplify how changes need to be propagated around the service.
Getting Started Documentation

Getting Started Overview

This document is an introduction to the main concepts of the MindLink API, as well as a walkthrough of initial steps to get up and running with performing basic collaboration and provisioning concepts. It is meant as a complimentary initial guide to the “MindLink API Developers Guide” document.

We assume you are familiar with Microsoft Office Communications Server/Skype and its group/Persistent Chat Server role, and the types of applications that are typically built to extend it – “Communications Enabled Business Processes” (CEBP).

We also assume you are familiar with the concepts of using web services (in any programming language of your choice), including the RESTful web services design pattern, HTTP headers, and the parsing and constructing of JSON and XML requests and responses. As such, the examples here will be programming-agnostic, dealing in terms of HTTP requests and responses only.


Sample Code Repository#

Sample code can be downloaded from https://github.com/mindlink/api-samples