Look up a case based on specific attributes

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

Permissions

All of the following are required:

  • Must have 'View Agent Console' action on 'System' resource.
  • All requested cases must satisfy one of the following:
    • 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 also enabled.
SecurityoAuthUser or oAuthClient
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.

Available values: all, created, custom.<name>, originatingChannel, description, solution, userLastWorked, relatedCases, notes, 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.

Available values: id, department, status, customer, custom.<name>

Examples:
$sort=
Response is sorted based on 'id' attribute.
$sort=id
Response is sorted based on 'status' attribute.
$sort=status
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"
Request Body schema: application/json

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
string

customer ID to be used for case lookup

email
string <email> [ 1 .. 100 ] characters

email address of a contact person of the customer to be used in case lookup

phone
string [ 1 .. 40 ] characters

phone number of a contact person of the customer to be used in case lookup

status
string

status of the case. Lookup on "open" cases will return all cases which are not closed.

Enum: "open" "closed"
createdDate
string

date of creation of case to be used in case filter. This is a range query parameter. Refer "Range query parameter representation" section.

lastModifiedDate
string

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
string

department name of the case. All cases from provided department will be returned.

ownerId
string

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
string

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
string

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.

Responses
200

OK

  • Matches are found for this lookup criteria and returned in the response body.
204

No content to return

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

Bad Request message

401

Unauthorized

403

Forbidden

406

Not Acceptable

500

Internal server error

post/case/lookup
Request samples
application/json
  • POST /core/casemgr/v3/case/lookup
  • This example demonstrates the following:
    • Lookup case by providing email address.
{
  • "email": "jhenry@customer.com"
}
Response samples
application/json
  • Case lookup with status as 'open' and department as 'Service'.
{
  • "case": [
    ],
  • "paginationInfo": {
    }
}