CustomerSearchPage Class Reference

More...

Detailed Description

Customer Search

Overview

This API allows users to search for customers based on various criteria. If no customers 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 customers with email address paul@.nosp@m.exam.nosp@m.ple.c.nosp@m.om, only customers with contact point value of paul@.nosp@m.exam.nosp@m.ple.c.nosp@m.om will be returned. The customer with 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/customer?phone={VAL}	Retrieve customers based on one phone number of the customer's contact point: {VAL}
GET	/ws/v12/interaction/customer?email={VAL}	Retrieve customers based on one email address of the customer's contact point: {VAL}
GET	/ws/v12/interaction/customer?custom.<name>={VAL}	Retrieve customers having custom attribute <name> with value: {VAL}
GET	/ws/v12/interaction/customer?activity={"type":"email","isRead":"false","isSecure":"true","mode":"outbound","sentDate":"{RANGE}"}	Retrieve customers having activities with specific criteria.

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 customers 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.
• If customer departmentalization setting is set to "Yes", only customers which belong to either the user's home department, or to the department where the user is a foreign user will be returned.

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:

• activity: Retrieve customers having activities with specific criteria. The criteria is specified using a json representation. The json must contain the following:
  • type: Type of activity. Must be "email".
  • isRead: Indicates whether activity is read. Must be false.
  • isSecure: Indicates whether the activity is secure. Must be true.
  • mode: Mode of the activity. Must be "outbound".
  • sentDate: Data range when the activity was sent out. This is a range parameter. Range cannot be more than 14 days. Range query parameter representation can be found here.
    Note: With the above criteria, customers with unread secure emails sent in the provided date range will be returned.
• phone: a phone number of a contact person's contact point to be used in customer search. All customer's contact persons and their contact points will be scanned to find matches.
• email: an email address of a contact person's contact point to be used in customer search. All customer's contact persons and their contact points will be scanned to find matches.
• created: date of creation of customer to be used in customer search. This is a range parameter. Range query parameter representation can be found here.
• custom.<name>: custom attribute value for custom attribute <name> of a customer 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.

• $attribute - Values of $attribute common parameter supported by Customer Resource
• $sort - Values of $sort common parameter supported by Customer Resource
• $order
• $pagenum
• $pagesize
• $rangestart
• $rangesize

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-Customers - used in case of success
• schema-kb-WSError - used in case of error

Summary attributes

   Summary attributes of Customer 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 Customer 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 customers by phone number with pagination parameters
Example 2 - Search for customers by email address
Example 3 - Search for customers by custom attribute with range parameters
Example 4 - Search for customers by phone number and custom attribute
Example 5 - Search for customers by unread secure emails sent in provided range

---