Detailed Description

Case Lookup

Overview

Use this API to lookup the cases based on various criteria for logged in users. If no cases match the lookup criteria, the server responds with 204 success code and an empty body. This API only supports exact matches; partial matches are not supported. For example, if a client looks up for the cases associated with email address paul@.nosp@m.exam.nosp@m.ple.c.nosp@m.om, only those cases where customer's contact point value is paul@.nosp@m.exam.nosp@m.ple.c.nosp@m.om is returned. The case with customer's contact point value of dean..nosp@m.paul.nosp@m.@exam.nosp@m.ple..nosp@m.com is not returned.@

since 15.0

APIs

Method	URL	Description
POST	`/ws/v20/interaction/case/lookup`	Lookup cases based on various attributes.

Authentication

Authentication is required. The client must be logged in to call this API. Each API request must contain X-egain-session request header returned by Login API.

Permissions

All of the following are required:

'View Agent Console' action
Only cases that satisfy one of the below conditions will be returned by server:
- case belongs to user's home department;

Licenses

The logged in user must have the following licenses:

Any User Licenses

Request

Request headers

Name	Description	Allowed values	Default value
X-egain-session	Session ID obtained from Login API response header	N/A	N/A
Accept	Content type accepted by client	`application/xml` or `application/json`	N/A
Accept-Language	Language locale accepted by client (used for locale specific fields in resource representation and in error responses)	Supported 'Accept-Language' header codes	`default system language`

Supported API specific query parameters

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

customer: customer ID to be used in case search.
email: email address of a contact person of the customer to be used in case search.
phone: phone number of a contact person of the customer to be used in case search. The phone number must be unformatted (no spaces, hyphens, etc).
status: status of the case. Status value must be either "open" or "closed". Searching for "open" cases will return all cases which are not closed.
custom.<name>: custom attribute value for custom attribute <name> of a case to be used in case search. Only non-encrypted custom attributes are supported.

$pagenum: Pagination parameter that specifies the page number of results to be returned. Used in conjunction with pagesize. Default value: 1
$pagesize: Pagination parameter that specifies the number of results per page. Used in conjunction with pagenum. Default value: 25
$rangestart: Range parameter that specifies the starting index of the range of results to be returned. Used in conjunction with rangesize. Default value: 1
$rangesize; Range parameter that specifies the number (range) of results to be returned. Used in conjunction with rangestart. Default value: 25
attribute common query parameter. Available values: all, created, custom.<name>, originatingChannel, description, solution, userLastWorked, relatedCases, notes, lastClosed Examples: $attribute= Additional attributes Attributes 'created' and 'description' is returned in server response. $attribute=created,description All attributes All the attributes are returned in server response. $attribute=all
order. "asc" "desc"
sort. Available values: id, department, status, customer, custom.<name> Examples: $sort= Sort based on Id Response is sorted based on 'id' attribute. $sort=id Sort based on Status Response is sorted based on 'status' attribute. $sort=status

Elements required in request body

At least one of the optional element must be sent.

Optional elements allowed in request body customer, email, phone, status, custom, createdDate, lastModifiedDate, department, ownerId, ownerLoginId, lastClosedDate

Note:
- If actor is client application then 'department' element must be provided.
- At least one element must be provided. You can mix and match one or more lookup criteria listed above in any order. If more than one lookup criteria is used, then the response only contain cases that satisfy all lookup criteria.

customer: customer ID to be used for case lookup
email: <email> [ 1 .. 100 ] characters, email address of a contact person of the customer to be used in case lookup
phone: [ 1 .. 40 ] characters, phone number of a contact person of the customer to be used in case lookup
status: status of the case. Lookup on "open" cases will return all cases which are not closed. possible values "open" "closed"
createdDate: date of creation of case to be used in case filter. This is a range query parameter. Refer "Range query parameter representation" section.
lastModifiedDate: date of last modification of case to be used in case filter. This is a range query parameter. Refer "Range query parameter representation" section.
department: department name of the case. All cases from provided department will be returned.
ownerId: user ID of agent to be used for case lookup. All cases whose owner is the agent identified by provided user ID will be returned.OwnerId can be provided only if ownerLoginId is not provided.
ownerLoginId: login ID of agent to be used for case lookup. All cases whose owner is the agent identified by provided login ID will be returned. OwnerLoginId can be provided only if ownerId is not provided.
lastClosedDate: date of last closing of case to be used in case filter. This is a range query parameter. Refer "Range query parameter representation" section. The start date must be provided, the date range must be between 14 days and, the end date must be greater than the start date.

Response

Response headers

Name	Description	Possible values
X-egain-session	Session ID of the current user session	N/A
Content-Type	Media type of response body	`application/xml` or `application/json`

Response body xml schemas:

Cases Schema - used in case of success
Error - used in case of error

HTTP status codes

Success Status codes

200 - OK

Matches are found for this search and returned in the response body.

204 - No Content

No matches were found for given search criteria.
Matches found for this search, however the requested page or range doesn't contain any results.

Failure Status codes

400 - Bad Request

Unsupported query parameter is sent in the request.
Unsupported value for query parameter is sent in the request.
None of the API specific query parameter is provided (since at least one search criterion is required).
Unsupported combination of common query parameters ($order provided without $sort, mixing of pagination and range parameters etc.).

401 - Unauthorized

X-egain-session request header is missing.
Session is invalid or expired.

403 - Forbidden

The user does not have sufficient permissions. Refer the "Permissions" section for details.

406 - Not Acceptable

Invalid 'Accept-Language' header value.

500 - Internal server error

Examples:

Example 1 - Lookup case with email attribute
Example 2 - Lookup for cases by department name.
Example 3 - Lookup for cases by multiple attributes