Case Search

Overview

Use this API to search for cases based on various criteria. If no cases match the search criteria, the server responds 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@example.com, only those cases where customer's contact point value is paul@example.com is returned. The case with customer's contact point value of dean.paul@example.com is not returned.

Note:

  • If actor is customer:
    • Only those cases having at least one activity visible to the customer (self, or customer sent in as query parameter) is returned. Refer 'Activities visible to a customer' section for information about the activities visible to the customer.
  • If actor is client application then 'department' query parameter must be provided.

    Permissions

    Actor Permission
    User All of the following are required:
    • Must have 'View Agent Console' action on 'System' resource.
    • Only cases that satisfy one of the below conditions is returned by server::
      • case 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 case 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 If the query parameter customer={id} is provided, the logged in customer must be authorized to perform this action on behalf of the customer specified through the "customer" 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 status, customer, email, phone, custom.<name>, owner
Client Application department, status, customer, email, phone, custom.<name>, owner
Customer status, customer, activityMode

Note:

  • If actor is client application then 'department' query parameter 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 all, created, createdBy, custom.<name>, originatingChannel, description, solution, userLastWorked, relatedCases, notes, lastClosed
Client Application all, created, createdBy, custom.<name>, originatingChannel, description, solution, userLastWorked, notes, lastClosed
Customer all, created, custom.<name>, originatingChannel, recentActivityDate, unreadActivityCount, lastClosed
Examples:
$attribute=
Attributes 'created' and 'description' is returned in server response.
$attribute=created,description
All the attributes are returned in server response.
$attribute=all
$order
string

Common query parameter $order.

Enum: "asc" "desc"
$sort
string

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

Actor Available values
User / Client Application id, custom.<name>, department, status, customer
Customer id, custom.<name>, recentActivityDate
Examples:
$sort=
Response is sorted based on 'id' attribute.
$sort=id
Response is sorted based on 'status' attribute.
$sort=status
email
string

Email address of a contact person of the customer to be used in case search.

Example: email=jhenry@customer.com
phone
string

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

activityMode
string

Only those cases that contain one or more activities in the activityMode value sent, is returned.

Enum: "inbound" "outbound"
status
string

Status of the case. Searching for "open" cases returns all cases which are not closed.

Enum: "open" "closed"
customer
string
Actor Description
User / Client Application Not allowed.
Customer The customer must be authorized to perform this action on behalf of the customer specified through the "customer" query parameter.
department
string

Department name to be used in search.

custom
string
  • Custom attribute value for custom attribute of a case to be used in case 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 'case'.
    • 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":"case","name":"work_status","value":"Pending"}]
    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 case resource'.
owner
string

ID of the case owner.

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

400

Bad Request message

401

Unauthorized

403

Forbidden

406

Not Acceptable

500

Internal server error

get/case
Request samples
Response samples
application/json
    

  • GET /core/casemgr/v3/case?customer=1014
    • 

  • This example demonstrates the following:
      

    • Search for cases based on customer ID. sorting and default page number. Note that the results would be the same even if the default sorting was explicitly specified. In that case, the URL would be /case?customer=1014&$sort=id&$order=asc.
      • 

    • Representation of the summary attributes, since $attribute is not supplied.
      • 

    

    • 



{
  • "case": [
    ],
  • "paginationInfo": {
    }
}