Management API

TABLE OF CONTENTS [Document Version - 1.4]

• Usage
• Common API Parameters
• Authentication
  • Tokens API
    • Token URL
    • Password
    • Steps
• Responses
  • ManagementActionResponse
• Entities
  • Campaign
  • List
  • Team
  • User
  • Break
• Campaign Methods
  • Get Campaigns
  • Get Campaign
  • Create Campaign
  • Update Campaign
  • Update Activity Status
  • Update Campaign Status
  • Update Campaign Type
  • Get Associate List with Campaign
  • 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
• Plans Methods
  • Get Plans
• Break Methods
  • Get Breaks
• 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,
 MessageOfTheDay: 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,
 AssignedCampaignIds: array of int
}

AssignedCampaignIds is an array of active campaign IDs. It returns an empty array when the list has no active campaign assignments.

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
}

Break

Returned by Get Breaks, this object represents a single active break code configured for the tenant.

{
 Id: int,
 Name: string,
 Description: string,
 BreakTime: int,
 IncludeInActiveTime: boolean
}

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

Get Associate List with Campaign

API call to get the active lists associated with a campaign.

GET
/webservices/services/management/campaigns/{campaignId}/lists
Params:
campaignId: int
Headers:
Accept: application/json | application/xml
Returns:
ManagementActionResponse containing an array of active list assignments:
{
 ListId: int
}
Errors:
403 Forbidden (Permission: Campaign Manager Access)
400 Bad Request (ResponseCode: InvalidParameters)

Example response:

{
 "Data": [
   {
     "ListId": 17
   },
   {
     "ListId": 23
   }
 ],
 "Success": true,
 "ResponseCode": "Success",
 "ResponseDetail": ""
}

If the campaign is active but has no active assigned lists, this returns a 200 success with an empty Data array.

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

Plans Methods

Get Plans

API call to get active plans by plan type, for use in Campaign and List configuration.

GET
/webservices/services/management/plans/{planType}
Params:
planType: string
Headers:
Accept: application/json | application/xml
Returns:
ManagementActionResponse containing array of plan lookup objects with Id, Name
Errors:
403 Forbidden (Permission: Plan Admin Access)
400 Bad Request (ResponseCode: InvalidParameters)

Supported plan type values

Results only contain active records, ordered by name ascending. Inactive plans are never returned. A supported plan type with no active plans still returns a 200 success, with an empty Data array.

An unsupported plan type value returns a 400 error without echoing it back. Plan IDs are per-environment and can be deactivated at any time, so resolve them at runtime rather than hardcoding or caching them.

Example response:

{
 "Data": [
   {
     "Id": 21,
     "Name": "UK outbound parameters"
   }
 ],
 "Success": true,
 "ResponseCode": "Success",
 "ResponseDetail": ""
}

Break Methods

Get Breaks

API call to get the active break codes configured for the tenant.

GET
/webservices/services/management/breaks
Returns:
ManagementActionResponse containing an array of Break (see Entities section)
Headers:
Accept: application/json | application/xml
Errors:
403 Forbidden (Permission: Settings - Manage Breaks)

Only active breaks are returned, ordered by name. BreakTime is the target break duration in minutes, not seconds. The Id returned here is the value to send as BreakId when requesting a break for an agent. If no active breaks exist, the endpoint still returns a 200 success with an empty Data array.

Example response:

{
 "Data": [
   {
     "Id": 1,
     "Name": "Lunch",
     "Description": "Scheduled meal break",
     "BreakTime": 30,
     "IncludeInActiveTime": false
   }
 ],
 "Success": true,
 "ResponseCode": "Success",
 "ResponseDetail": ""
}

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: