Management API

TABLE OF CONTENTS [Document Version - 1.3]

• Usage
• Common API Parameters
• Authentication
  • Tokens API
    • Token URL
    • Password
    • Steps
• Responses
  • ManagementActionResponse
• Entities
  • Campaign
  • List
  • Team
  • User
• Campaign Methods
  • Get Campaigns
  • Get Campaign
  • Create Campaign
  • Update Campaign
  • Update Activity Status
  • Update Campaign Status
  • Update Campaign Type
  • Associate List with Campaign
  • Disassociate List from Campaign
  • Associate Team with Campaign
  • Disassociate Team from Campaign
• List Methods
  • Get Lists
  • Get List
  • Create List
  • Update List
  • Update List Activity Status
• Team Methods
  • Get Teams
  • Get Team
  • Create Team
  • Update Team
  • Update Team Activity Status
  • Associate User with Team
  • Disassociate User from Team
• User Methods
  • Get Users
  • Get User
  • Create User
  • Update User
  • Update User Activity Status
  • Associate Skills with Users
  • Disassociate Skills from Users
• Global Emergency
  • Enable
  • Disable
• Appendix
  • Appendix 1: Campaign Types
  • Appendix 2: Campaign Statuses
  • Appendix 3: Zip Tone Styles
  • Appendix 4: Zip Tone Beep Styles
  • Appendix 5: List Types

Usage

This API is designed as a Management Remote Control. The API methods allow the caller to perform the following actions.

• Create, Update & Activate/Deactivate Campaigns
• Create, Update & Activate/Deactivate Lists
• Create, Update & Activate/Deactivate Teams
• Create, Update & Activate/Deactivate Users
• Change the Status of Campaigns
• Change the Dialling Strategy of Campaigns
• Associate/Disassociate Lists and Teams with Campaigns
• Associate/Disassociate Users with Teams
• Associate/Disassociate Skills with Users
• Enable Global Emergency Mode

Common API Parameters

The following is a list of common parameters that are used by a number of the API methods, along with details of what each parameter represents.

• Campaign Id – The unique identifier of a particular campaign as recorded in the correspondingly named table in the system’s database.
• List Id – When leads are imported into the system they are grouped together into lists this is the unique id of a particular list as recorded in the database.
• Team Id – Agents can be assigned to teams and this is a unique integer id of a team as recorded in the corresponding table in the database.
• User Id – Unique id of a particular user (often representing an agent) as recorded in the corresponding table in the database.

Authentication

An authentication token is required to access this API. A token can be requested from the token service using the Token API.

Tokens API

All API methods require a security token to use the system. This token is stored in the HTTP cookie to allow multiple API calls from one authentication request.

A token is requested by authenticating with a user and password combination. The Token service API will return a token on success.

Token URL

https://[CUSTOMER].maxcontact.com/webservices/services/apitoken/login/{login}

Password

The password needs to be sent in the authorization header of the request; the password needs to be converted to Base64 with ASCII encoding to get the bytes[] from the password string.

Steps:

1. Make a request to the token Uri
2. Store token key for any subsequent requests
3. Make request to the Callbacks API

Recommendations

• It is recommended that you keep track of the Token Key and its expiry as making a request every time can slow down the import process.
• Login should be plain text

When a successful API call is made to the API Token service, it will return a json/xml object
A token key must be passed to each API endpoint along with the request.

Responses

The API will by default return an XML response, but Accept and Content-Type headers with values of application/json can be supplied with requests and this will result in the API returning JSON formatted responses.

ManagementActionResponse

Most methods return a ManagementActionResponse object. The “data” property will be a different type dependent on the method used.

{
 Success: bool,
 Data: This is dependent on the method used, entities are described below,
 ResponseCode: string,
 ResponseDetail: string
}

The available response codes are as follows:

• Success
• Error
• Invalid Parameters

Entities

Campaign

Returned by a number of methods including get campaign and get campaigns, this object represents a campaign.

{
 Id: int,
 CampaignName: string,
 Active: Boolean,
 Description: string
 CallerId: string,
 Type: int,
 MaxLines: int,
 DegradeToProgressive: boolean,
 ProgressiveThreshold: int,
 TargetDropPercent: decimal,
 IsBlended: boolean,
 AutoRecord: boolean,
 DefaultListId: int,
 HoursPerWorkingDay: decimal,
 DefaultPhoneType: int,
 TeleParamPlanId: int,
 SchedulePlanId: int,
 ZipTone: int,
 ZipToneBeep: int,
 ZipToneWav: string,
 NotReadyWaitTime: int,
 Status: int
}

List

Returned by a number of methods including get list and get lists, provides details about a list of leads.

{
 Id: int,
 ListName: string,
 Description: string,
 ListType: int,
 CallerIdEnabled: boolean,
 CallerId: string,
 MaxCallbackDays: int,
 UseMaxCallbackDays: boolean,
 MaxCallbackDate: datetime,
 FetchWeight: int,
 AlertsEnabled: boolean,
 ScriptingEnabled: boolean,
 ScriptProvider: int,
 ScriptId: int,
 Script: string,
 RecallPlanId: int,
 CallingTimePlanId: int,
 ResultCodePlanId: int,
 IvrPlanId: int,
 AnswerMachinePlanId: int,
 DoNotCallPlanId: int,
 SchedulePlanId: int
}

Team

Returned by a number of API methods including get team and get teams, this object provides details of a single team.

{
 Id: int,
 TenantId: int,
 TeamName: string,
 PrimarySupervisorId: int,
 MaxCallbacksPerDay: int,
 ServiceTime: int,
 HoursPerWorkingDay: decimal,
 WellBeingDeckId: int
}

User

Returned by a number of API methods including get user and get users, this object provides details of an individual user.

{
 Id: int,
 FirstName: string,
 LastName: string,
 Login: string,
 RolePlanId: int,
 UseRTC: boolean,
 Extension: string,
 AutoLogon: int,
 TeamId: int,
 AgentCapacityPlanId: int,
 SSOActive: boolean,
 Password: string
}

Campaign Methods

Get Campaigns

API call to get all existing campaigns.

GET
/webservices/services/management/campaigns
Returns:
ManagementActionResponse containing array of Campaigns

Get Campaign

API call to get an existing campaign.

GET
/webservices/services/management/campaigns/{campaignId}
Params:
campaignId: int
Returns:
ManagementActionResponse containing a Campaign

Create Campaign

API call to create a new campaign.

POST
/webservices/services/management/campaigns
Body:
A single Campaign entity (see Entities section)
Returns:
ManagementActionResponse containing a Campaign

Update Campaign

API call to update an existing campaign.

PUT
/webservices/services/management/campaigns/{campaignId}
Params:
campaignId: int
Body:
A single Campaign entity (see Entities section)
Returns:
ManagementActionResponse containing a Campaign

Update Activity Status

API call to activate or deactivate a campaign.

PATCH
/webservices/services/management/campaigns/{campaignId}/activityStatus
Params:
campaignId: int
Body:
{
 Active: boolean
}
Returns:
ManagementActionResponse containing a Campaign object

Update Campaign Status

API call to update the status of a campaign.

PATCH
/webservices/services/management/campaigns/{campaignId}/status
Params:
campaignId: int
Body:
{
 CampaignStatus: string
}
Returns:
ManagementActionResponse containing the updated campaign status

Update Campaign Type

API call to update a campaign’s type.

PATCH
/webservices/services/management/campaigns/{campaignId}/type
Params:
campaignId: int
Body:
{
 CampaignType: string
}
Returns:
ManagementActionResponse containing the updated campaign type

Associate List with Campaign

API call to associate a list of leads with a campaign.

PUT
/webservices/services/management/campaigns/{campaignId}/lists
Params:
campaignId: int
Body:
{
 ListId: int
}
Returns:
ManagementActionResponse indicating success or failure

Disassociate List from Campaign

API call to disassociate a list from a campaign.

DELETE
/webservices/services/management/campaigns/{campaignId}/lists
Params:
campaignId: int
Body:
{
 ListId: int
}
Returns:
ManagementActionResponse indicating success or failure

Associate Team with Campaign

API call to associate a team with a campaign.

PUT
/webservices/services/management/campaigns/{campaignId}/teams
Params:
campaignId: int
Body:
{
 TeamId: int
}
Returns:
ManagementActionResponse indicating success or failure

Disassociate Team from Campaign

API call to disassociate a team from a campaign.

DELETE
/webservices/services/management/campaigns/{campaignId}/teams
Params:
campaignId: int
Body:
{
 TeamId: int
}
Returns:
ManagementActionResponse indicating success or failure

List Methods

Get Lists

API call to get all existing lists.

GET
/webservices/services/management/lists
Returns:
ManagementActionResponse containing array of Lists

Get List

API call to get an existing list.

GET
/webservices/services/management/lists/{listId}
Params:
listId: int
Returns:
ManagementActionResponse the requested List

Create List

API call to create a new list.

POST
/webservices/services/management/lists
Body:
A single List entity (see Entities section)
Returns:
ManagementActionResponse containing the new List

Update List

API call to update an existing list.

PUT
/webservices/services/management/lists/{listId}
Params:
listId: int
Body:
A single List entity (see Entities section)
Returns:
ManagementActionResponse containing the updated List

Update List Activity Status

API call to update the activity status of an existing list.

PUT
/webservices/services/management/lists/{listId}/activitystatus
Params:
listId: int
Body:
{
 Active: boolean
}
Returns:
ManagementActionResponse containing the updated activity status

Team Methods

Get Teams

API call to get all existing teams.

GET
/webservices/services/management/teams
Returns:
ManagementActionResponse containing array of Teams

Get Team

API call to get an existing team.

GET
/webservices/services/management/teams/{teamId}
Params:
teamId: int
Returns:
ManagementActionResponse containing the requested Team

Create Team

API call to create a new team.

POST
/webservices/services/management/teams
Body:
A Team entity (see Entities section)
Returns:
ManagementActionResponse containing the new Team

Update Team

API call to update an existing team.

PUT
/webservices/services/management/teams/{teamId}
Params:
teamId: int
Body:
A Team entity (see Entities section)
Returns:
ManagementActionResponse containing the updated Team

Update Team Activity Status

API call to update the activity status an existing team.

PUT
/webservices/services/management/teams/{teamId}/activitystatus
Params:
teamId: int
Body:
{
 Active: boolean
}
Returns:
ManagementActionResponse containing the updated activity status

Associate User with Team

API call to add a user to a team.

PUT
/webservices/services/management/teams/{teamId}/users
Params:
teamId: int
Body:
{
 UserId: int
}
Returns:
ManagementActionResponse indicating success or failure

Disassociate User from Team

API call to remove a user from a team

DELETE
/webservices/services/management/teams/{teamId}/users
Params:
teamId: int
Body:
{
 UserId: int
}
Returns:
ManagementActionResponse indicating success or failure

User Methods

Get Users

API call to get all existing users.

GET
/webservices/services/management/users
Returns:
ManagementActionResponse containing array of Users

Get User

API call to get an existing user.

GET
/webservices/services/management/users/{userId}
Params:
userId: int
Returns:
ManagementActionResponse containing the requested User

Create User

API call to create a new user.

POST
/webservices/services/management/users
Body:
A User entity (see Entities section)
Returns:
ManagementActionResponse containing the new User

Update User

API call to update an existing user.

PUT
/webservices/services/management/users/{userId}
Params:
userId: int
Body:
A User entity (see Entities section)
Returns:
ManagementActionResponse containing the updated User

Update User Activity Status

API call to update the activity status an existing team.

PATCH
/webservices/services/management/users/{userId}/activitystatus
Params:
userId: int
Body:
{
 Active: boolean
}
Returns:
ManagementActionResponse containing the updated User

Associate Skills with Users

API call to associate a skills with multiple users.

PUT
/webservices/services/management/users/skills
Body:
{
SkillId: int,
Proficiency: int,
UserIds: array of int
}
Returns:
SkillUserResult indicating success or failure

Disassociate Skills from Users

API call to disassociate a skills from multiple users.

DELETE
/webservices/services/management/users/skills
Body:
{
SkillId: int,
UserIds: array of int
}
Returns:
SkillUserResult indicating success or failure

Global Emergency

Enable

API call to trigger global emergency. This will stop all Campaigns and enable emergency routing for inbound numbers.

POST
/webservices/services/management/globalemergency/enable
Returns:
ManagementActionResponse indicating success or failure

Disable

API call to revert the system back to normal

POST
/webservices/services/management/globalemergency/disable
Returns:
ManagementActionResponse indicating success or failure

Appendix

Appendix 1: Campaign Types

The following table contains a list of the campaign types offered by the system:

Appendix 2: Campaign Statuses

The following table contains a list of the statuses that a campaign can have:

Appendix 3: Zip Tone Styles

The following table contains a list of the various zip tone styles:

Appendix 4: Zip Tone Beep Styles

The following table contains a list of the various zip tone beep styles:

Appendix 5: List Types

The following table contains a list of the various list types: