Introduction

Overview

The Cisco Support Case API v3 provides a powerful, convenient, and simple way to interact with the Cisco Support Case Manager tool and aims to improve the partner and customer experience by enabling you to access case information instantly, programmatically, and in bulk.

The Cisco Support Case API is stateless, externally accessible, and delivered as a REST web service, which allows partners to build innovative case management applications and portals. Case API is available for Cisco Partner Support Service (PSS) partners.

Features

The Cisco Support Case API provides the following features:

Includes web services that return:

Detailed case information for specified case(s)
Summary case information associated with the specified case(s), user ID(s), and contract ID(s)

Supports RESTful interface.
Supports JSON data format.

API Reference

This topic describes the methods provided by this API.

Notes:

Pagination is supported for Get Cases By Contract Id and Get Cases By User Id; see Pagination Response Record for details on paging.
For information on error codes returned by the API, see Error Codes.
You can download the WADL for this API by clicking the following link: Cisco Case API v3 WADL.
This API reference provides information related to the latest version of this API. Cisco encourages you to use the latest version of the Cisco Support APIs; however, if you use the legacy version of this API, refer to the Cisco Case API v1 Reference for details.

GET Case Summary

Returns brief information for the specified case or cases.

Request Parameters

Parameter	Required	Type	Length	Description
case_ids	Yes	char	100	Identifier of the case or cases for which to return results. Multiple values must be specified within a comma-separated list and cannot exceed 30 IDs.
sort_by	No	char	100	Order in which the results should be sorted; one of the following values: UPDATED_DATE: Sort by last modification time (ascending). Default. STATUS: Sort by status (ascending).

Response Parameters

Parameter	Type	Length	Description
count	int	5	Total number of records returned.
cases	array	-	Array of information returned for each case; this array includes the parameters listed below.
item_entry_id	int	5	Number assigned to this entry within the returned results.
user_id	char	50	Identifier of the case originator.
case_id	char	64	Identifier of the case.
title	char	240	Title of the case.
severity	int	1	Severity of the case; one of the following values: 1 = Severity 1 2 = Severity 2 3 = Severity 3 4 = Severity 4
contact_name	char	150	The name of the primary contact
status_flag	char	1	Status of the case; one of the following values: O = Open C = Closed
status	char	150	Detailed status of the case; one of the following values: Cisco Pending Close Pending Closed Customer Pending Cisco Release Pending Service Order Pending
creation_date	char	150	Date and time (in UTC) that the case was created.
updated_date	char	150	Date and time (in UTC) that the case was last updated.
serial_number	char	30	Serial number of the device associated with the case.
contract_id	char	120	Identifier of the contracted associated with this case.
technology_name	char	150	The technology the case is linked to (e.g. "Voice - Communications Manager")
sub_technology_name	char	150	The sub-technology the case is linked to (e.g. "Communications Manager Call Failure - IP Phone to IP Phone"")
rmas	array	-	List of RMAs associated with this case.
bugs	array	-	List of bugs associated with this case.

Sample Request

GET https://apix.cisco.com/case/v3/cases/case_ids/682299374?sort_by=STATUS

Sample Response

{
  "cases": [
    {
      "item_entry_id": 1,
      "user_id": "directcust4",
      "case_id": "682299374",
      "title": "SNTC : Day 2 : NOS Handover Collector Training :TARGET CORPORATION",
      "severity": "3",
      "contact_name": "CPRSMOKE TESTER",
      "status_flag": "C",
      "status": "Closed",
      "creation_date": "2017-05-09T20:08:45.000Z",
      "updated_date": "2017-05-12T18:51:54.000Z",
      "serial_number": "",
      "contract_id": "",
      "technology_name": "Smart Services Capabilities",
      "sub_technology_name": "Collector Deployment SNTC (Contract Required)",
      "rmas": [],
      "bugs": []
    }
  ],
  "count": 1
}

GET Case Details

Returns detailed information for the specified case.

Request Parameters

Parameter	Required	Type	Length	Description
case_id	Yes	char	100	Identifier of the case for which to return results.

Response Parameters

Parameter

Type

Length

Description

caseDetail

object

Detailed information returned for each case; this object includes the parameters listed below.

bugs

array

Identifier or identifiers of the bugs associated with the case.

case_id

char

Identifier of the case.

close_date

char

150

Date and time (in UTC) that the case was closed.

contact_business_phone_numbers

array

Business phone number for the customer associated with the case.

contact_email_ids

array

Email address for the customer associated with the case.

contact_mobile_phone_numbers

array

Mobile phone number for the customer associated with the case.

contact_name

char

150

The name of the primary contact

contact_user_id

char

100

Cisco.com account ID for the customer associated with the case.

contract_id

char

120

Identifier of the contract associated with the case.

creation_date

char

150

Date and time (in UTC) that the case was created.

notes

array

Array of details returned for each note associated with the case; this array includes the parameters listed below.

created_by	char	50	Name of the user that created the note.
creation_date	char	150	Date the note was created.
note	char	2000	Description of the note.
note_detail	char	32767	Detailed description from the case notes.

owner_email

char

Email address of the case owner.

owner_name

char

Proper name of the case owner.

preferred_contact_method

char

Preferred method of contact for the customer associated with the case.

problem_code_name

char

The problem area associated with the case, e.g. "Configuration Assistance".

request_type

char

The selected case request type. Typically "Diagnose and Fix" "Request RMA" "Expert Consultation" or "Ask a Question".

rmas

array

RMA number or numbers associated with the case.

serial_number

char

Serial number of the device associated with the case.

severity

int

Severity of the case; one of the following values:

1 = Severity 1
2 = Severity 2
3 = Severity 3
4 = Severity 4

status

char

150

Detailed status of the case; one of the following values:

Cisco Pending
Close Pending
Closed
Customer Pending
Cisco Release Pending
Service Order Pending

sub_technology_name

char

150

The sub-technology the case is linked to (e.g. "Communications Manager Call Failure - IP Phone to IP Phone"")

technology_name

char

150

The technology the case is linked to (e.g. "Voice - Communications Manager")

title

char

240

Title of the case.

tracking_number

char

240

Customer's tracking or case number.

updated_date

char

150

Date and time (in UTC) that the case was last updated.

user_id

char

Identifier of the user associated with this case.

Sample Request

GET https://apix.cisco.com/case/v3/cases/details/case_id/682299374

Sample Response

{
    "caseDetail": {
        "user_id": "DirectCust4",
        "case_id": "682299374",
        "title": "SNTC : Day 2 : NOS Handover Collector Training :TARGET CORPORATION",
        "severity": "3",
        "status": "Closed",
        "creation_date": "2017-05-09T20:08:45.000Z",
        "updated_date": "2017-05-12T18:51:54.000Z",
        "serial_number": "",
        "contract_id": "",
        "contact_user_id": "DirectCust4",
        "contact_name": "CPRSMOKE TESTER"
        "preferred_contact_method": "Email",
        "contact_email_ids": [
            "emailaddress@cisco.com"
        ],
        "contact_business_phone_numbers": [
            "31-1248789/2001"
        ],
        "contact_mobile_phone_numbers": [],
        "owner_name": "Josh Engineer",
        "owner_email": "emailaddress@cisco.com",
        "close_date": "2017-05-11T18:43:56.000Z",
        "technology_name": "Smart Services Capabilities",
        "sub_technology_name": "Collector Deployment SNTC (Contract Required)",
        "tracking_number": "",
        "problem_code_name": "Configuration Assistance",
        "request_type": "",
        "rmas": [],
        "bugs": [],
        "notes": [
            {
                "note": "",
                "note_detail": "Closed with Customer Permission",
                "created_by": "Josh Engineer",
                "creation_date": "2017-05-11T18:44:00.000Z"
            },
            {
                "note": "",
                "note_detail": "duplicate case, 682307531",
                "created_by": "Joshua Frumkin",
                "creation_date": "2017-05-11T18:44:00.000Z"
            }
        ],
    }
}

GET Cases by Contract ID

Returns summary information for cases associated with the specified contract or contracts.

Request Parameters

Parameter	Required	Type	Length	Description
contract_ids	Yes	char list	120	Identifier of the contract or contracts for which to return results. Multiple values must be specified within a comma-separated list and cannot exceed 10 IDs.
date_created_from	No	char	240	Beginning date (in UTC) of the range in which to search. For example: 2013-04-23T11:00:14Z Note: The maximum date range currently supported is 90 days.
date_created_to	No	char	240	End date (in UTC) of the range in which to search. For example: 2013-04-23T11:00:00Z Note: The maximum date range currently supported is 90 days.
status_flag	No	char	1	Return only cases associated with the specified status; one of the following values: O = open C = closed If status_flag is O (open), all open cases within the specified date range are returned; if a date range is not specified, all open cases associated with the other search parameters are returned. The maximum range returned is 90 days. The default behavior for this parameter is to return cases of both open and closed status.
sort_by	No	char	100	Order in which the results should be sorted; one of the following values: UPDATED_DATE: Sort by last modification time (ascending). Default STATUS: Sort by status (ascending).
page_index	No	integer	5	Index number of the page to return; a maximum of 100 records per page are returned.

Response Parameters

Parameter	Type	Length	Description
pagination_response_record	object	-	See Pagination Response Record for details.
cases	array	-	Array of information returned for each case; this array includes the parameters listed below.
user_id	char	50	Identifier of the user associated with this case.
case_id	char	64	Identifier of the case.
title	char	240	Title of the case.
severity	int	1	Severity of the case; one of the following values: 1 = Severity 1 2 = Severity 2 3 = Severity 3 4 = Severity 4
contact_name	char	150	The name of the primary contact
status_flag	char	1	Status of the case; one of the following values: O = Open C = Closed
status	char	150	Detailed status of the case; one of the following values: Cisco Pending Close Pending Closed Customer Pending Cisco Release Pending Service Order Pending
creation_date	char	150	Date and time (in UTC) that the case was created.
updated_date	char	150	Date and time (in UTC) that the case was last updated.
serial_number	char	30	Serial number of the device associated with the case.
contract_id	char	120	Identifier of the contracted associated with this case.
rmas	array	-	List of RMAs associated with this case.
bugs	array	-	List of bugs associated with this case.

Sample Request

https://apix.cisco.com/case/v3/cases/contracts/contract_ids/1234567?date_created_from=2017-04-01T00:00:00Z&date_created_to=2017-04-30T23:59:59Z&sort_by=&status_flag=O&page_index=1

Sample Response

{
  "pagination_response_record": {
    "last_index": 1,
    "page_index": 1,
    "page_records": 1,
    "self_link": "https://apix.cisco.com/case/v3/cases/contracts/contract_ids/1234567?date_created_from=2017-04-01T00:00:00Z&date_created_to=2017-04-30T23:59:59Z&sort_by=&status_flag=O&page_index=1,
    "title": "Get Cases By Contract Id",
    "total_records": 1
  },
  "cases": [
    {
      "item_entry_id": 1,
      "user_id": "directcust4",
      "case_id": "682299374",
      "title": "SNTC : Day 2 : NOS Handover Collector Training :TARGET CORPORATION",
      "severity": "3",
      "contact_name": "CPRSMOKE TESTER",
      "status_flag": "O",
      "status": "Cisco Pending",
      "creation_date": "2017-04-24T19:02:31.000Z",
      "updated_date": "2017-05-12T18:51:54.000Z",
      "serial_number": "",
      "contract_id": "1234567",
      "rmas": [],
      "bugs": []
    }
  ]
}

GET Cases by User ID

Returns summary information for cases associated with the specified user or users.

Request Parameters

Parameter	Required	Type	Length	Description
user_ids	Yes	char list	100	Identifier of the user or users for which to return results. Multiple values must be specified within a comma-separated list and cannot exceed 10 IDs.
date_created_from	No	char	240	Beginning date (in UTC) of the range in which to search. For example: 2013-04-23T11:00:14Z Note: The maximum date range currently supported is 90 days.
date_created_to	No	char	240	End date (in UTC) of the range in which to search. For example: 2013-04-23T11:00:00Z Note: The maximum date range currently supported is 90 days.
status_flag	No	char	1	Return only cases associated with the specified status; one of the following values: O = open C = closed If status_flag is O (open), all open cases within the specified date range are returned; if a date range is not specified, all open cases associated with the other search parameters are returned. The maximum range returned is 90 days. The default behavior for this parameter is to return cases of both open and closed status.
sort_by	No	char	100	Order in which the results should be sorted; one of the following values: UPDATED_DATE: Sort by last modification time (ascending). Default STATUS: Sort by status (ascending).
page_index	No	integer	5	Index number of the page to return; a maximum of 100 records per page are returned.

Response Parameters

Parameter	Type	Length	Description
pagination_response_record	object	-	See Pagination Response Record for details.
cases	array	-	Array of information returned for each case; this array includes the parameters listed below.
user_id	char	50	Identifier of the user associated with this case.
case_id	char	64	Identifier of the case.
title	char	240	Title of the case.
severity	int	1	Severity of the case; one of the following values: 1 = Severity 1 2 = Severity 2 3 = Severity 3 4 = Severity 4
contact_name	char	150	The name of the primary contact
status_flag	char	1	Status of the case; one of the following values: O = Open C = Closed
status	char	150	Detailed status of the case; one of the following values: Cisco Pending Close Pending Closed Customer Pending Cisco Release Pending Service Order Pending
creation_date	char	150	Date and time (in UTC) that the case was created.
updated_date	char	150	Date and time (in UTC) that the case was last updated.
serial_number	char	30	Serial number of the device associated with the case.
contract_id	char	120	Identifier of the contracted associated with this case.
rmas	array	-	List of RMAs associated with this case.
bugs	array	-	List of bugs associated with this case.

Sample Request

https://apix.cisco.com/case/v3/cases/users/user_ids/directcust4?date_created_from=2017-04-01T00%3A00%3A00Z&date_created_to=2017-04-30T23%3A59%3A59Z&sort_by=&status_flag=O&page_index=1

Sample Response

{
  "pagination_response_record": {
    "last_index": 1,
    "page_index": 1,
    "page_records": 1,
    "self_link": "self_link": "https://apix.cisco.com/case/v3/cases/users/user_ids/directcust4?page_index=1&sort_by=UPDATED_DATE&status_flag=O&date_created_from=2017-04-01T00:00:00Z&date_created_to=2017-04-30T23:59:59Z",
    "title": "Get Cases By User Id",
    "total_records": 1
  },
  "cases": [
    {
      "item_entry_id": 1,
      "user_id": "directcust4",
      "case_id": "682299374",
      "title": "SNTC : Day 2 : NOS Handover Collector Training :TARGET CORPORATION",
      "severity": "3",
      "contact_name": "CPRSMOKE TESTER",
      "status_flag": "O",
      "status": "Cisco Pending",
      "creation_date": "2017-04-24T19:02:31.000Z",
      "updated_date": "2017-05-12T18:51:54.000Z",
      "serial_number": "",
      "contract_id": "1234567",
      "rmas": [],
      "bugs": []
    }
  ]
}

Pagination Response Record

Provides information about the page requested and the total number of pages available to return.

Parameters

Parameter	Type	Length	Description
last_index	integer	5	Total number of pages available.
page_index	integer	5	Index number of the requested page.
page_records	integer	5	Total results for this page.
self_link	char	120	Self reference link.
title	char	120	Name of the method called.
total_records	integer	5	Total results for this query.

Sample JSON Response

{
  "pagination_response_record": {
    "last_index": 6,
    "page_index": 6,
    "page_records": 45,
    "self_link": "https://apicisco.com/case/v3/cases/contracts/contract_ids/1234567?page_index=6&sort_by=UPDATED_DATE",
    "title": "Get Cases By Contract Id",
    "total_records": 545
  },

Error Codes

This table describes the error codes returned by the Cisco Support Case API.

Error Code	Message	Description
400	Bad Request	Request does not conform to HTTP protocol.
403	INVALID_USERID AUTHENTICATION_ERROR	Invalid user ID.
403	INVALID_SORT_OPTION	Invalid sort_by value.
403	MISSING_INPUTS	Mandatory search criteria is missing.
403	INVALID_DATEFORMAT	Invalid date format.
403	INVALID_STATUSFLAG	Invalid status_flag value.
403	CASE_NOTFOUND	Case ID is not available in the system.
403	INVALID_DATERANGE	Invalid date range.
403	INVALID_CUSTOMERID	Invalid BID or BIDs are not associated with the specified user.
403	EXCEEDED_CASEIDS	Number of specified case IDs exceeds the maximum allowed.
403	EXCEEDED_CONTRACTIDS	Number of contract IDs exceeds the maximum allowed.
403	EXCEEDED_INPUTS	More than 1 contract ID was specified and/or more than 10 user IDs were specified.
403	EXCEEDED_USERIDS	More than 10 user IDs were specified.
403	EXCEEDED_BILLTOIDS	More than 5 Bill to customer IDs were specified.
403	CASE_API_FORBIDDEN	User does not have access to this service.
403	Not Authorized	Token is invalid.
403	Forbidden	You do not have permission to access the requested method or object.
403	Not Authorized	The API key associated with your request was not recognized, or the signature was incorrect.
403	Account Inactive	The API key you are using to access the Mashery API has not been approved or has been disabled.
403	Account Over Queries Per Second Limit	The API key you are using has attempted to access the API too many times in one second.
403	Account Over Rate Limit	The API key you are using has attempted to access the API too many times in the rate limiting period.
403	Rate Limit Exceeded	The service you have requested is over capacity.
403	Unknown Referrer	Unknown referrer.
403	Service requires SSL	The service requires SSL.
404	API_UNAVAILABLE	Service is not configured in JVM.
414	Request URI Too Long	The request URI is too long.
415	INVALID_MEDIATYPE	Unsupported media type input by the user.
500	API_UNAVAILABLE	Database is down or currently unavailable.
500	UNKNOWN_FAILURE	Generic error.
500	SYSTEM_ERROR	Error while request data transformation to JSON.
500	SYSTEM_ERROR	SQL exception while invoking backend procedure.
500	SYSTEM_ERROR	Error while writing the data to HTTP response.
500	Internal Server Error	An internal server error has occurred (usually from the API).
502	Bad Gateway	Bad response from the server was received on the backend.
502	Proxy Error	An error from the server was received on the backend
503	API Maintenance/Service Unavailable	The service is unavailable due to maintenance.
504	Gateway Timeout	The backend service timed out.
596	Service Not Found	The service requested does not exist or is unavailable. Note: Most likey spaces were found in the input parameters. Please check the input values.