All Classes Pages
CaseSearchPage Class Reference

More...

Detailed Description

Case Search

Overview

This API allows users to search for cases based on various criteria. If no cases match the search criteria, the server will respond with 204 success code and an empty body.
This API only supports exact match searches; partial matches are not supported. For example, if a client searches for 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 will be returned. The case with customer's contact point value of dean..nosp@m.paul.nosp@m.@exam.nosp@m.ple..nosp@m.com will not be returned.

Since
11.6

APIs

Method URL Description
GET /ws/v12/interaction/case?customer={ID} Retrieve cases for one customer ID.
{ID} is the ID of the customer.
GET /ws/v12/interaction/case?email={EMAIL_ADDRESS} Retrieve cases of a customer with a specified email address.
{EMAIL_ADDRESS} is the email address of the customer.
GET /ws/v12/interaction/case?phone={PHONE_NUMBER} Retrieve cases of a customer with a specified phone number.
{PHONE_NUMBER} is the phone number of the customer.
GET /ws/v12/interaction/case?custom.<name>={VAL} Retrieve cases having custom attribute <name> with value {VAL}

NOTE: You can mix and match one or more filter criteria listed above in any order. If more than one filter criteria are used, then response will only contain cases that satisfy all filter criteria.

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;
    • case belongs to a department where the user is a foreign user;
    • the department of the case is shared with the department of the user, and as part of this sharing, activity sharing is enabled as well.

Licenses

The logged in user must have the following 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.

Supported common query parameters

Refer to Supported Common Query Parameters in ECE REST API page for detailed description of each common parameter listed below.

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:

  • schema-interaction-Cases - used in case of success
  • schema-kb-WSError - used in case of error

Summary attributes always returned in server response

   Summary attributes of Case Resource

Additional attributes returned in server response if explicitly requested by client

Server can be prompted to return additional attributes of resource representation using $attribute common query parameter.
See Values of $attribute common parameter supported by Case Resource for the list of allowed attribute names.

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 - Search for cases by customer with summary attributes in response
Example 2 - Search for cases by status and custom attribute, with range parameters
Example 3 - Search for cases by multiple attributes with pagination parameters