Search for customers

Overview

Use this API to search for customers based on various criteria. If no customers match the search criteria, the server responds with 204 success code and an empty body. This API only supports exact match searches and partial matches are not supported except search by customer name. For example, if a client searches for customers with email address paul@example.com, only customers with contact point value of paul@example.com are returned. The customer with contact point value of dean.paul@example.com are not returned.

In case actor is customer, this API can be used to get the details of the logged in customer.

Permissions

Actor Permission
User All of the following are required:
  • View Agent Console' action.
  • If "Customer departmentalization" setting is enabled, then each of the requested customers must belong to either the user's home department, or to the department where the user is a foreign user.
Client Application No additional permission is required.
Customer All authenticated customers can access this API.

Supported API query parameters

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

Actor Available values
User phone, email, custom, activity, facebookId, twitterId, instagramId, appleOpaqueId, youTubeId, created, type, customerName, $attribute, $sort, $order, $pagenum, $pagesize, $rangestart, $rangesize
Client Application phone, email, custom, activity, facebookId, twitterId, instagramId, appleOpaqueId, youTubeId, created, type, customerName, $attribute, $sort, $order, $pagenum, $pagesize, $rangestart, $rangesize, department
Customer $attribute

Note:

  • If actor is client application and "Customer departmentalization" setting is enabled then the following query parameter must be provided:
    • department
SecurityoAuthUser or oAuthClient or oAuthCustomer
Request
query Parameters
phone
string

A phone number of a contact's contact point to be used in customer search. All customer's contacts and their contact points are scanned to find matches.

email
string

An email address of a contact's contact point to be used in customer search. All customer's contacts and their contact points are scanned to find matches.

custom
string
  • Custom attribute value for custom attribute of a customer or contact person to be used in customer 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' values are 'customer' and 'contactPerson'.
    • 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":"contactPerson","name":"isprimary","value":"y"},{"object":"customer","name":"preferredlang","value":"English"}]
    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 customer resource'.
activity
string
  • Retrieve customers having activities with specific criteria. The criteria is specified using a json representation.
    Note:
    • Date range should be provided in'sentDate'. Refer Range Query Parameter Representation section.
Examples:
activity={"type":"email","isRead":"false","isSecure":"true","mode":"outbound","sentDate":"{DATE RANGE}"}
facebookId
string

Facebook ID of the contacts contact point to be used in customer search.

twitterId
string

Twitter ID of the contacts contact point to be used in customer search.

instagramId
string

Instagram ID of the contacts contact point to be used in customer search.

appleOpaqueId
string

Apple Opaque ID of the contacts contact point to be used in customer search.

youTubeId
string

YouTube ID of the contacts contact point to be used in customer search.

created
string

Date of creation of customer to be used in customer search. This is a range query parameter. Refer Range Query Parameter Representation section for more details.

$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, role, pin, industry, marketSegment, entitlements, custom.<name>, level, preferredAgent, howReferred, created,createdBy,
Customer all, role, pin, industry, marketSegment, entitlements, custom.<name>
$sort
string

Customers returned in server response are sorted based on the attribute supplied under $sort.
Available values:

Actor Available values
User/Client Application id, type, customerName, custom.<name>
Customer Not allowed
Examples:
Response is sorted based on 'id' attribute.
$sort=id
Response is sorted based on 'customerName' attribute.
$sort=customerName
type
string

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

Enum: "individual" "corporate" "group"
customerName
string

Name of the customer to be used in customer search.

department
string

Department name to be used in search.

$order
string

Common query parameter $order.

Enum: "asc" "desc"
$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

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

OK

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.
400

Bad Request

401

Unauthorized

403

Forbidden

406

Not Acceptable

500

Internal server error

get/customer
Request samples
Response samples
application/json
    

  • GET /core/customermgr/v3/customer?phone=14082343456102&$sort=type&$order=desc&$pagenum=4&$pagesize=1
    • 

  • This example demonstrates the following:
      

    • Search for customers based on the phone number of their contact point.
      • 

    • Sorting on customer type, in descending order
      • 

    • Explicitly specifying the pagination parameters.
      • 

    • Representation of the summary attributes of the customer
      • 

    • Representation of paginated response, with links to previous and next pages.
      • 

    

    • 



{
  • "link": [
    ],
  • "customer": [
    ],
  • "paginationInfo": {
    }
}