API Developers reference


4. Provisioning REST API

4.1 /Agents resource

Supported methods: GET
Arguments : None
Response Codes : 200 OK Request Succeeded
401 Unauthorized No or invalid token supplied (see 1.4.2)
403 Forbidden Agent not permitted to provision
Response Body : Agents ProvisionedAgent[] 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: OUT, GET, DELETE
Arguments : {agentId} String Required
< agent > ProvisionedAgent Required for PUT
Response Codes : 200 OK Request Succeeded
400 Bad Request Attempted to PUT agent with incorrect ID
401 Unauthorized No or invalid token supplied (see 1.4.2)
403 Forbidden Agent not permitted to provision (see 1.3.1)
404 Not Found Attempted to GET/DELETE unknown agent
Response Body : Agent ProvisionedAgent For GET requests
(no response) for PUT/DELETEs
Since Version : 1
Proviusioning 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} String Required
Response Codes : 200 OK Request Succeeded
401 Unauthorized No or invalid token specofoed(see 1.4.2)
403 Forbidden Agent not permitted to provision (see 1.3.1)
404 Not Found Agent ID is not known
Response Body : Channels ProvisionedChannels[] 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} String Required
Response Codes : 200 OK Request Succeeded
304 Not Modified PUT request has no effect
400 Bad Request Attempted to PUT invalid channel
401 Unauthorized No or invalid token supplied (see 1.4.2)
403 Forbidden Agent not permitted to provision (see 1,3,1)
404 Not Found Agent 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} String Required
< metadata >
Response Codes : 200 OK Request Succeeded
401 Unauthorized No or invalid token supplied (see 1.4.2)
304 Forbidden Agent not permitted to provision (see 1.3.1)
404 Not Found Agent ID is not known
Response Body : Metadata Dictionary For 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} String Required
{key} String Required
< value > String Required for PUT
Response Codes : 200 OK Request Succeeded
401 Unauthorized No or invalid token supplied (see 1.4.2)
403 Forbiddn Agent not permitted to provision (see 1.3.1)
404 Not Found Agent or key not found
Response Body : Valus String For 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 : query String Required
Response Codes : 200 OK Request Succeeded
400 Bad Request No valid agent assosiated with token or bad search parameters
401 Unauthorized No or invalid token supplied (See 1.4.2)
403 Forbidden Agent not permitted to provision (see 1.3.1)
Response Body : Channels Dictionary Required
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 OK Request Succeeded
401 Unauthorized No or invalid token supplied (See 1.4.2)
403 Forbidden Agent not permitted to provision (see 1.3.1
Response Body : Users ProvisionedUser[] 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} String Required
< user > ProvisionedUser Required for PUT
Response Codes : 200 OK Request Succeeded
400 Bad Request Attempted to PUT user with incorrect ID
401 Unauthorized No or invalid token supplied (See 1.4.2)
403 Forbidden Agent not permitted to provision (see 1.3.1)
404 Not Found Attempted to GET/DELETE unknown user
Response Body : User ProvisionedUser For GET requests
(no response) For PUT/DELETEs
Response Body : User ProvisionedUser For 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 OK Request Succeeded
401 Unauthorized No or invalid token supplied (See 1.4.2)
403 Forbidden Agent not permitted to provision
Response Body : Throttles ProvisionedThrottle[] 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 behavior 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} String Required
< Throttle > ProvisionedThrottle Required for PUT
Response Codes : 200 OK Request Succeeded
400 Bad Request Attempted to PUT throttle with incorrect ID
401 Unauthorized Attempted to PUT throttle with different type
403 Forbidden No or invalid token supplied (See 1.4.2)
404 Not Found Agent not permitted to provision (see 1.3.1)
Attempted to GET/DELETE unknown throttle
Response Body : throttle ProvisionedThrottle For 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/Lync 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.