Activity Search

Overview

Use this API to search for activities based on various criteria. This API only supports exact match searches; partial matches are not supported. For example, if a client searches for activities where customer ID is 1080, then only activities with customer ID 1080 is returned. Activities associated with customer ID 10801 is not returned.

Note:

If actor is customer:

Only activities that the customer (self, or customer sent in as query parameter) can view is returned. Refer 'API's for Core Case management' section for information about the activities visible to the customer.

Permissions

Actor	Permission
User	All of the following are required: Must have 'View Agent Console' action on 'System' resource. Only activities that satisfy one of the below conditions is returned by server:: activity must either belong to the user's home department, or to a department in which the user is a foreign user; the department of the activity is shared with the department of the user, and as part of this sharing, activity sharing is enabled as well.
Client Application	No additional permission required.
Customer	Only activities that the customer (self, or customer sent in as query parameter) can view is returned. Refer 'API's for Core Case management' section for information about the activities visible to the customer. If the query parameter customerID={id} is provided, the logged in customer must be authorized to perform this action on behalf of the customer specified through the "customerID" query parameter. Otherwise, the application returns a 400 (bad request) response code.

Supported API specific query parameters

One or more query parameters listed below can be supplied per API call:

Actor	Available values
User	caseID, status, type, createdDate, lastModifiedDate, custom, customerID, mode, assignedTo, queueID, assignedUserName
Client Application	caseID, status, type, createdDate, lastModifiedDate, custom, department, mode
Customer	caseID, status, type, customerID, mode, secure, read, count

Note:

If actor is client application then at least one of the following query parameter must be provided:
- caseID
- type, status and department: All of type, status and department must be provided.

SecurityoAuthUser or oAuthClient or oAuthCustomer

Request

query Parameters

$pagenum

string

Pagination parameter that specifies the page number of results to be returned. Used in conjunction with $pagesize.
Default value: 1

$pagesize

string

Pagination parameter that specifies the number of results per page. Used in conjunction with $pagenum.
Default value: 25

$rangestart

string

Range parameter that specifies the starting index of the range of results to be returned. Used in conjunction with $rangesize.
Default value: 1

$rangesize

string

Range parameter that specifies the number (range) of results to be returned. Used in conjunction with $rangestart.
Default value: 25

$attribute

string

Server can be prompted to return additional attributes of resource representation using $attribute common query parameter.

Actor	Available values
User / Client Application	all, created, createdBy, payload, custom.<name>, lastDepartment, contactPointData, userLastWorked, classifications, language
Customer	all, created, createdBy, payload, custom.<name>

Examples:

-- $attribute=

Additional attributes

Attributes 'created' and 'payload' is returned in server response.

$attribute=created,payload

All attributes

All the attributes are returned in server response.

$attribute=all

$order

string

Common query parameter $order.

Enum: "asc" "desc"

$sort

string

Activities returned in server response are sorted based on the attribute supplied under $sort.

Actor	Available values
User / Client Application	id, case, created, custom.<name>, department, dueDate, lastModified
Customer	id, case, created, custom.<name>

Examples:

-- $sort=

Sort based on ID

Response is sorted based on 'id' attribute.

$sort=id

Sort based on created date

Response is sorted based on 'created' attribute.

$sort=created

caseID

string

Case ID.

customerID

string

ID of the customer of the activity.

Note: If actor is customer then customer must be authorized to perform this action on behalf of the customer specified through the "customerID" query parameter.

status

string

Status value of an activity.

If activities are to be searched based on status and substatus both, the status value must be sent in the format: <status_value>:<substatus_value>. Refer section 'Supported Activity status and substatus values' for more information on status and substatus values.
Substatus is optional, and if omitted, the filtering happens on just the status.
Additionally, status can have a special-meaning value. If the value "open" is specified, the filter returns all activities that are not in "completed" status.

Note: If actor is customer, then only 'open' and 'completed' status are supported.

Examples:

-- status=

With status

Search activities with 'completed' status.

status=completed

With status and substatus

* Search activities with 'assigned' status and 'new' substatus. * Few more examples: assigned:in-progress, assigned, awaiting_assignment.

status=assigned:new

mode

string

Mode value of an activity.

Enum: "inbound" "outbound" "none"

assignedTo

string

User ID to whom the activity is assigned. This returns the activities assigned to this user.

queueID

string

Queue ID to be used in activity search. This returns the activities associated with this queue.

created

string

Date of creation of activity to be used in activity search. This is a range query parameter. Refer 'API's for Core Case management' section for information about range query parameter representation.

lastModified

string

Date of last modification of an activity to be used in activity search. This is a range query parameter. Refer 'API's for Core Case management' section for information about range query parameter representation.

assignedUserName

string

Login name of the user to whom the activity is assigned. This returns the activities assigned to this user regardless of the activity status.

type

string

Type value of an activity. This returns the activities of specified type. Note that at least one more parameter must be provided along with 'type' for filtering the activities.

Actor	Available values
User / Client Application	email, social, call_track, chat, task
Customer	email, social, call_track, chat

Enum: "email" "social" "call_track" "chat" "task"

read

string

This returns the activities which are read or unread based on the value provided in the parameter.

Enum: "yes" "no"

secure

string

This returns the activities which are secure or not based on the value provided in the parameter.

Enum: "yes" "no"

department

string

Department name to be used in search.

custom

string

Custom attribute value for custom attribute of a activity to be used in activity search.
Only non-encrypted custom attributes are supported.
The custom attribute criteria is specified using a json representation.
Each JSON object must have following keys:
- object: Value of this key represents object to which this custom attribute belongs.
  Supported 'object' value is 'activity'.
- name: Value of this key represents name of the custom attribute.
- value: Value of this key represents value of the custom attribute to be used in search.
Example:
custom=[{"object":"activity","name":"complainttype","value":"incorrect_order"}]
Note:
- The 'custom' query parameter JSON value should be url encoded.
- Some developer tools for invoking APIs may not url encode the 'custom' query parameter JSON value by default. Ensure that only url encoded values are used.
- The 'name' of the custom attribute must match the attribute name in 'Get metadata for custom attributes for activity resource'.

header Parameters

Accept required	string Default: application/json Content type accepted by client. Enum: "application/json" "application/xml"
Accept-Language required	string Default: en-US Language locale accepted by client (used for locale specific fields in resource representation and in error responses). Enum: "en-US" "es-ES" "fr-FR" "it-IT" "de-DE" "nl-NL" "pt-BR" "pt-PT" "da-DK" "ru-RU" "fr-CA" "zh-CN" "ja-JP" "ko-KR" "sv-SE"

Responses

200

If $count parameter is provided in the request, the count of the activities is provided in the response. If no activities qualify for the criteria, the count is returned as 0.
If $count parameter is not provided in the request, the qualifying activities is returned in the response.

204

No Content

This is returned only if $count parameter is not provided in the request, and one of the below are true:
- No matches were found for given search criteria.
- Matches found for this search, however the requested page or range doesn't contain any results.

400

Bad Request

Any criteria for successful execution mentioned in the Overview and Request Body sections are violated.
In case actor is customer and the logged in customer does not have grants on the customer provided through the query parameter "customerID".
In case actor is client application and activity type is not email or chat.

401

Unauthorized

In case actor is user or customer and :
- X-egain-session request header is missing.
- Session is invalid or expired.
In case actor is client application and :
- Authorization header is not provided.
- Authorization header format is incorrect.
- Session does not exist corresponding to the provided authorization header.
- The session identified through authorization header is not a client application session.

403

Forbidden

406

Not Acceptable

500

Internal server error

get/activity

Request samples

curl
JavaScript
Node.js

Response samples

application/json

GET /core/casemgr/v3/activity?customerID=1002&$attribute=all&$pagenum=1&$pagesize=2
This example demonstrates the following:
- Search for activities based on customer ID.
- Requesting all attributes to be returned in the response.
- Representation of all supported attributes in the response.
- Default sorting (on activity ID in ascending order)
- Provide pagination parameters in the request ($pagenum and $pagesize).

{"activity": [{"link": [{"rel": "self",
"href": "/core/casemgr/v3/activity/1000"
}
],
"case": {"link": [{"rel": "case",
"href": "/core/casemgr/v3/case/1000"
}
],
"id": "1000"
},
"department": {"name": "Service",
"id": "999"
},
"mode": {"value": "inbound",
"displayValue": "Inbound"
},
"type": {"value": "email",
"displayValue": "Email",
"subtype": {"value": "general",
"displayValue": "General"
}
},
"secure": false,
"sentOnBehalf": false,
"status": {"value": "completed",
"displayValue": "Completed",
"substatus": {"value": "done",
"displayValue": "Done"
},
"assigned": {"user": {"firstName": "Jenny",
"lastName": "Anthony",
"id": "1005"
},
"activityFolder": {"name": {"value": "activities_completed",
"displayValue": "Completed"
},
"id": 7
},
"pinned": false,
"locked": false
}
},
"created": "2021-10-06T13:59:48.000Z",
"createdBy": {"user": {"id": "12"
}
},
"lastModified": "2021-10-08T17:09:46.000Z",
"subject": "Issue with laptop configuration",
"language": {"value": "en",
"displayValue": "English"
},
"userLastWorked": {"firstName": "Jenny",
"lastName": "Anthony",
"id": "1002"
},
"customer": {"link": [{"rel": "customer",
"href": "/core/customermgr/v3/customer/1000"
}
],
"customerName": "John Davis",
"contacts": {"contact": [{"systemCreated": false,
"email": [{"emailAddress": "johndavis@example.com",
"id": "1000"
}
],
"id": 1000
}
]
},
"id": "1000"
},
"classifications": {"category": [{"name": "Laptop Configuration",
"isComplaint": false,
"id": "456700000001000"
}
],
"resolutionCode": [{"name": "Share Documentation",
"id": "456700000001001"
}
]
},
"queue": {"name": "Email queue",
"id": "1001"
},
"attachments": {"count": 0,
"purgedCount": 0,
"link": {"rel": "attachment",
"href": "/core/casemgr/v3/activity/1000/attachment"
}
},
"notes": {"count": 0,
"link": [{"rel": "note",
"href": "/core/casemgr/v3/activity/1000/notes"
}
]
},
"contactPointData": "johndavis@example.com",
"contentPurged": false,
"payload": {"email": {"hasDraft": false,
"leaveOpen": false,
"escalated": false,
"outboundFailed": false,
"alias": {"name": "alias",
"value": "support@business.com",
"id": "1000"
},
"date": {"date": "2021-09-13T05:05:51.000Z"
},
"emailAddresses": {"from": "johndavis@example.com",
"to": {"address": ["johndavis@example.com"
]
},
"replyTo": {"address": ["support@business.com"
]
},
"receiver": "support@business.com"
}
}
},
"customAttributes": {"customAttribute": [{"attribName": "complainttype",
"attribValues": {"attribValue": [{"value": "incorrect_order",
"displayValue": "Incorrect Order"
}
]
}
}
]
},
"id": "1000"
},
{"link": [{"rel": "self",
"href": "/core/casemgr/v3/activity/1001"
}
],
"case": {"link": [{"rel": "case",
"href": "/core/casemgr/v3/case/1001"
}
],
"id": "1001"
},
"department": {"name": "Service",
"id": "999"
},
"mode": {"value": "inbound",
"displayValue": "Inbound"
},
"type": {"value": "email",
"displayValue": "Email",
"subtype": {"value": "general",
"displayValue": "General"
}
},
"secure": false,
"sentOnBehalf": false,
"status": {"value": "awaiting_assignment",
"displayValue": "Awaiting Assignment",
"substatus": {"value": "ready_for_assignment",
"displayValue": "Ready for assignment"
},
"assigned": {"pinned": false,
"locked": false
}
},
"created": "2021-10-06T13:59:49.000Z",
"createdBy": {"user": {"id": "12"
}
},
"lastModified": "2021-10-06T14:04:23.000Z",
"subject": "Issue with mobile configuration",
"language": {"value": "et",
"displayValue": "Estonian"
},
"userLastWorked": {"firstName": "Jenny",
"lastName": "Anthony",
"id": "1002"
},
"customer": {"link": [{"rel": "customer",
"href": "/core/customermgr/v3/customer/1000"
}
],
"customerName": "John Davis",
"contacts": {"contact": [{"systemCreated": false,
"email": [{"emailAddress": "johndavis@example.com",
"id": "1000"
}
],
"id": 1000
}
]
},
"id": "1000"
},
"classifications": {"category": [{"name": "Mobile Configuration",
"isComplaint": false,
"id": "456700000001002"
}
],
"resolutionCode": [{"name": "Share Documentation",
"id": "456700000001003"
}
]
},
"queue": {"name": "Email queue",
"id": "1001"
},
"attachments": {"count": 0,
"purgedCount": 0,
"link": {"rel": "attachment",
"href": "/core/casemgr/v3/activity/1001/attachment"
}
},
"notes": {"count": 0,
"link": [{"rel": "note",
"href": "/core/casemgr/v3/activity/1001/notes"
}
]
},
"contactPointData": "johndavis@example.com",
"contentPurged": false,
"payload": {"email": {"hasDraft": false,
"leaveOpen": false,
"escalated": false,
"outboundFailed": false,
"alias": {"name": "alias",
"value": "support@business.com",
"id": "1000"
},
"date": {"date": "2021-09-13T05:05:51.000Z"
},
"emailAddresses": {"from": "johndavis@example.com",
"to": {"address": ["johndavis@example.com"
]
},
"replyTo": {"address": ["support@business.com"
]
},
"receiver": "support@business.com"
}
}
},
"customAttributes": {"customAttribute": [{"attribName": "complainttype",
"attribValues": {"attribValue": [{"value": "incorrect_order",
"displayValue": "Incorrect Order"
}
]
}
}
]
},
"id": "1001"
}
],
"paginationInfo": {"count": 2,
"pagenum": 1,
"pagesize": 2
}
}