Introduction

Overview

The Cisco Service Order Return (RMA) API provides a powerful, convenient, and simple way to interact with the Cisco RMA service and enables you to access RMA information instantly, programmatically, and in bulk.

The Cisco Service Order Return (RMA) API is stateless, externally accessible, and delivered as a REST web service, which allows you to build innovative RMA applications and portals

Features

The Cisco Service Order Return (RMA) API provides the following features:

Supports RESTful interface.
Supports JSON data format.
Includes web services that return:
Details about the specified RMA.
List of RMAs associated to the specified user ID.

API Reference

This topic describes the methods provided by this API.

Notes:

You can download the WADL for this API by clicking the following link: Cisco Service Order Return (RMA) API WADL
For information on error codes returned by these methods, see Error Codes.

Warning! All parameters are case sensitive and must be entered as shown in this document.
If a space is encountered in a mandatory input parameter, Error 403 is thrown. For example: "https://apix.cisco.com/return/v1.0/returns/rma_numbers/ 626099288" will result in "<h1>Not Authorized</h1>" response.

GET RMA Details by RMA Number

Returns detailed information about the specified RMA.

Request Parameters

Parameter	Required	Type	Length	Description
rma_numbers	Yes	int	10	Identifier of the RMA for which to return details. Note: Currently, only one RMA Number is required and accepted. In the future, multiple RMA numbers will be supported.

Response Parameters

Parameter	Type	Length	Description
APIPagination	array	-	Array of information about the number of records returned; this array includes the parameters listed below.
pageIndex	int	5	Index of the requested page.
lastIndex	int	5	Index of the last page returned.
totalRecords	int	5	Total number of records returned.
pageRecords	int	5	Total results for this page.
title	string	200	Title of the service.
selfLink	string	500	URL used to make the service request.
returns	array	-	Array of detailed information about the specified RMA; this array includes the RmaRecord, shipToInfo, billToInfo, replacementParts, returnParts, and laborDetails arrays.
RmaRecord	array	-	Array of detailed information about the specified RMA; this array includes the parameters listed below, as well as the customerRefInfo array.
rmaNo	string	20	Identifier of the RMA; order number.
status	string	20	Current status of the RMA. One of the following values: open, booked, hold, cancelled or closed.
orderDate	string	20	GMT date that the RMA was created.
caseId	string	20	Identifier of the service request.
requestedShipDate	string	50	Requested ship date for the order.
originator	string	20	User name of the individual that originated the order.
allowPartialShipment	string	5	Indicates if this order can be shipped in multiple shipments.
failureClass	string	50	Type of failure associated with the RMA.
failureCode	string	50	System code for the failure associated with the RMA.
contractId	string	20	Identifier of the contract associated with the RMA.
serviceLevel	string	20	Service level associated with the RMA
customerRefInfo	array	-	Array of customer information; this array includes the parameters listed below.
customerPONumber	string	20	Purchase order number associated with the RMA.
origSalesOrderNumber	string	20	Original sales order number.
customerRefNumber	string	20	Customer number associated with the RMA.
customerProvidedSN	string	20	Serial number associated with the RMA.
shipToInfo	array	-	Array of shipping information; this array includes the parameters listed below.
customerName	string	100	Name of the customer to which the order should be shipped.
address1, address2, address3, address4	string	500	Address to which the order should be shipped.
city	string	50	City to which the order should be shipped.
state	string	50	State to which the order should be shipped.
country	string	50	Country to which the order should be shipped.
postalCode	string	20	Postal code of the region to which the order should be shipped.
stateProv	string	20	Providence to which the order should be shipped.
siteUseId	string	50	Identifier of the site to which the order should be shipped.
ackUserId	string	20	Cisco user ID for the individual to contact.
ackPhone	string	20	Phone number of the individual to contact.
ackEmail	string	20	Email address of the individual to contact.
ackName	string	100	Name of the individual to contact.
shipToContactName	string	100	Name of the individual to which the order should be shipped.
shipToContactPhone	string	100	Phone number of the individual to which the order should be shipped.
shipToContactEmail	string	100	Email address of the individual to which the order should be shipped.
billToInfo	array	-	Array of billing information; this array includes the parameters listed below.
customerName	string	100	Name of the customer to which the order should be billed.
address1, address2, address3, address4	string	500	Address to which the order should be billed.
city	string	50	City to which the order should be billed.
state	string	50	State to which the order should be billed.
country	string	50	Country to which the order should be billed.
postalCode	string	20	Postal code of the region to which this order should be billed.
stateProv	string	20	Providence to which the order should be billed.
siteUseId	string	50	Identifier of the site to which the order should be billed.
replacementParts	array	-	Array of tracking information and parts details; this array includes the trackingInfo and partsLineDetails arrays.
trackingInfo	array	-	Array of tracking information for the replacement part or parts; this array includes the parameters listed below.
trackingNumber	string	50	Couriers tracking number for the shipment of replacement parts.
courierList	string	100	Courier information for the shipment for the replacement parts.
shipDate	string	20	GMT date on which the replacement part was shipped via courier.
partsLineDetails	array	-	Array of information about requested replacement parts; this array includes the parameters listed below.
partsLineRef	string	5	Line number for replacement parts entries.
partsLineStatus	string	20	Current status of replacement parts request.
partsTransactionType	string	20	Transaction type of replacement parts.
shippedPartNo	string	20	Shipped part number for the replacement parts.
partsDescription	string	100	Description of replacement parts.
partsQtyAuth	string	5	Authorized quantity of replacement parts.
partsScheduledShipTime	string	20	GMT date when Cisco will ship replacement parts.
partsqtyShipped	string	5	Number of parts shipped as replacement parts.
partsShipDate	string	20	GMT date when parts where shipped by Cisco.
partsShipmentWarehouse	string	20	Identifier of the warehouse from which the parts were shipped.
partsDispatchStatus	string	20	Status of the shipment.
shippedSerialID	string	20	Serial number of the shipped part.
returnLines	array	-	Array of detailed information about the returned part or parts; this array includes one or more returnParts arrays.
returnParts	array	-	Array of information about the returned parts; this array includes the parameters listed below.
returnLineRef	string	5	Line number for return entries.
returnLineStatus	string	20	Current status of return parts.
returnTransactionType	string	20	Transaction type of return parts.
receivedPartNo	string	20	Part number of the returned parts.
returnDescription	string	100	Description of the return.
returnQtyAuth	string	5	Authorized quantity of return.
returnToCiscoBy	string	20	GMT date by which customer must return the part to Cisco.
returnQtyReceived	string	5	Number of parts received in the return.
returnDateReceived	string	20	GMT date when return was received by Cisco.
returnWarehouse	string	20	Identifier of the warehouse that received the return.
receivedSerialNumber	string	20	Serial number of received for the return.
laborDetails	array	-	Array of information about the Cisco field engineer assigned to the RMA; this array includes the parameters listed below, as well as the laborLines array.
fieldEngineerName	string	100	Name of the field engineer assigned to the RMA.
fieldEngineerPhone	string	20	Phone number for the field engineer assigned to the RMA.
fieldEngineerOnRouteTime	string	20	Time that the field engineer was traveling to the site.
fieldEngineerArrivedTime	string	20	Time the field engineer arrived on site.
fieldEngineerReleasedTime	string	20	Time the field engineer departed from the site.
laborLines	array	-	Array of information related to service call; this array includes the parameters listed below.
laborTaskNumber	string	50	Line number for service call details.
laborStatus	string	20	Current status of the service call.
primaryProductFamily	string	20	Primary product family associated to this service call.
laborScheduledTime	string	20	Time the service was scheduled.
laborDispatch	string	20	Current status of labor dispatch.
laborDispatchOrCancellationNotes	string	100	Notes associated with labor dispatch.
notes	array	-	Array of information about notes associated with the RMA; this array includes the parameters listed below.
addlComments	string	200	Additional comments related to the RMA.
failureDescription			Description of the failure associated with the RMA.
fieldEngineerInstructions	string	200	Instruction or notes for the field engineer.
partDeliveryInstructions	string	200	Delivery instructions for replacement parts.
partialShipmentNote	string	200	Notes for partial shipment of the replacement parts.
specialInstructions	string	200	Special instructions (if any) associated with the RMA.

Sample Request

GET https://apix.cisco.com/return/v1.0/returns/rma_numbers/84894022 HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Bearer QROt9zFPchfWTZeodjpmC04cGWsd
Content-Type: application/json
Host: apix.cisco.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Sample Response

HTTP/1.1 200 OK
Date: Wed, 14 Aug 2013 05:20:28 GMT
Server: IBM_HTTP_Server
X-Mashery-Message-ID: b198f36c-20bc-4cdd-9c4a-73f2d0c17e45
Cache-Control: private
Pragma: private
Content-Type: application/json
Content-Language: en-US
Cache-Control: max-age=0
Expires: Wed, 14 Aug 2013 05:20:28 GMT
Connection: close
Transfer-Encoding: chunked

{
   "APIPagination": {
      "pageIndex": "1",
      "lastIndex": "1",
      "totalRecords": "1",
      "pageRecords": "1",
      "title": "Service Order RMA API",
      "selfLink": "https://apix.cisco.com/return/v1.0/returns/rma_numbers/84894022" 
   },
   "returns": { 
     "RmaRecord": [{
         "rmaNo": 84894022,
         "status": "Booked",
         "orderDate": "2013-08-06",
         "caseId": "625774679",
         "requestedShipDate": "2013-08-06",
         "originator": "SVORMA10",
         "allowPartialShipment": "",
         "failureClass": "Operational Failure",
         "failureCode": "HW Fail - Power",
         "contractId": "92156435",
         "serviceLevel": "Premium Parts & Labor - 4 Hour",
         "customerRefInfo": {
            "customerPONumber": "",
            "origSalesOrderNumber": "84894022",
            "customerRefNumber": "",
            "customerProvidedSN": "" 
         },
         "shipToInfo": {
            "customerName": "NPQ CORPORATION",
            "address1": "TECH SUINDRA",
            "address2": "",
            "address3": "",
            "address4": "",
            "city": "HYDERABAD",
            "state": "AP",
            "country": "IN",
            "postalCode": "",
            "stateProv": "AP",
            "siteUseId": "734647093",
            "ackUserId": "mackeryn",
            "ackPhone": "1455652605402",
            "ackEmail": "mq123@cisco.com",
            "ackName": "Mack Yrn",
            "shipToContactName": " Mack Yrn",
            "shipToContactPhone": "997752605402",
            "shipToContactEmail": " mq123@cisco.com" 
         },
         "billToInfo": {
            "customerName": "STARS FIRST LTD",
            "address1": "NUMBER ONE",
            "address2": "BOYCOTT DRIVE",
            "address3": "NEWTAVERN SOUTH",
            "address4": "",
            "city": "REJJITH",
            "state": "",
            "country": "GB",
            "postalCode": "B77 8QJ",
            "stateProv": "",
            "siteUseId": "61530259" 
         },
         "replacementParts": {
            "trackingInfo": {
               "trackingNumber": "",
               "courierList": "",
               "shipDate": "" 
            },
            "partsLineDetails": [{
               "partsLineRef": "2",
               "partsLineStatus": "Awaiting Shipping",
               "partsTransactionType": "ARPRM-SHIP-UKH",
               "shippedPartNo": "RP=",
               "partsDescription": "^Route Processor",
               "partsQtyAuth": "1",
               "partsScheduledShipTime": "2013-08-06",
               "partsqtyShipped": "",
               "partsShipDate": "",
               "partsShipmentWarehouse": "U06",
               "partsDispatchStatus": "DISPATCHED" 
            }] 
         },
         "returnLines": {
            "returnParts": [{
               "returnLineRef": "1",
               "returnLineStatus": "Awaiting Return",
               "returnTransactionType": "ARPRM-RETURN-UKH",
               "receivedPartNo": "RP=",
               "returnDescription": "^Route Processor",
               "returnQtyAuth": "1",
               "returnToCiscoBy": "2013-08-16",
               "reqturnQtyReceived": "",
               "returnDateReceived": "",
               "returnWarehouse": "BLR" 
            }]
         },
         "laborDetails":{
            "fieldEngineerName": "",
            "fieldEngineerPhone": "",
            "fieldEngineerOnRouteTime": "",
            "fieldEngineerArrivedTime": "",
            "fieldEngineerReleasedTime": "",
            "laborLines": [{
               "laborTaskNumber": "3",
               "laborStatus": "Booked",
               "primaryProductFamily": "7500",
               "laborScheduledTime": "2013-08-06",
               "laborDispatch": "SELECTED",
               "laborDispatchOrCancellationNotes": "" 
            }] 
         },
         "notes": {
            "addlComments": "",
            "failureDescription": "Created by SVORMA10 at 2013/08/06 12:38:22\r\nCreated by SVORMA10 at 2013/08/06 04:45:17\r\nCreated by SVORMA10 at 2013/08/06 04:27:37\r\ntest",
            "fieldEngineerInstructions": "Created by SVORMA10 at 2013/08/06 12:38:22\r\nCreated by SVORMA10 at 2013/08/06 04:45:17\r\ntest",
            "partDeliveryInstructions": "",
            "partialShipmentNote": "Created by SVORMA10 at 2013/08/06 12:38:22\r\n Do Not Partial Ship",
            "specialInstructions": "" 
         } 
      }]
   } 
}

GET RMAs by User ID

Returns a list of RMAs associated with the specified user. By default, the last 30 days of RMAs for a user is returned.

Request Parameters

Parameter	Required	Type	Length	Description
user_ids	Yes	string	20	Identifier of the user for which to return associated RMAs. Note: Only 1 user ID is accepted; currently, multiple user IDs are not supported.
fromDate	No	string	10	Beginning date from which to return results. Date must be GMT in the following format: YYYY-MM-DD Note: The fromDate and toDate date range cannot exceed 30 days.
toDate	No	string	10	End date from which to return results. Date must be GMT in the following format: YYYY-MM-DD Note: The fromDate and toDate date range cannot exceed 30 days.
status	No	string	10	Status of the RMA on which to filter results; one of the following values: open, booked, hold, closed, cancelled.
sortBy	No	string	10	Value on which to sort the results; one of the following values: orderdate (default) or status.

Request Parameters

Parameter	Type	Length	Description
APIPagination	array	-	Array of information about the number of records returned; this array includes the parameters listed below.
pageIndex	int	5	Index of the requested page.
lastIndex	int	5	Index of the last page returned.
totalRecords	int	5	Total number of records returned.
pageRecords	int	5	Total results for this page.
title	string	200	Title of the service.
selfLink	string	500	URL used to make the service request.
users	array	-	Array of information about the specified user; this array includes the returns array, as well as the parameters listed below.
userId	string	50	Identifier of the user associated with the RMA.
returnCount	int	5	Total number of records returned.
returns	array	-	Array of information about the RMA; this array includes the parameters listed below, as well as the shippingAddress array.
rmaNo	string	20	Identifier of the RMA; order number.
status	string	20	Current status of the RMA. One of the following values:o pen, booked, hold, cancelled or closed.
orderDate	string	30	GMT date that the RMA was created.
caseId	string	20	Identifier of the service request.
contractId	string	20	Identifier of the contract associated with the RMA.
serviceLevel	string	160	Service Level associated with the RMA
orderedPart	string	100	Part number for the ordered part.
customerProvidedSN	string	20	Serial number associated with the RMA.
trackingNumber	string	50	Tracking number for this RMA.
courierList	string	100	Courier used to ship this order.
earliestShipDateTime	string	20	Earliest date (GMT) at which the order can be shipped.
onSiteContactName	string	100	Name of the individual to which the order should be shipped.
onSiteContactPhone	string	50	Phone number of the individual to which the order should be shipped.
onSiteContactEmail	string	100	Email address of the individual to which the order should be shipped.
shippingAddress	array	-	Array of information about the shipping address; this array includes the parameters listed below.
customerName	string	100	Name of customer to which the order should be shipped.
address1, address2, address3, address4	string	200	Address to which the order should be shipped.
city	string	100	City to which the order should be shipped.
state	string	100	State to which the order should be shipped.
country	string	100	Country to which the order should be shipped.
siteUseId	string	100	Identifier of the site to which the order should be shipped.

Sample Request

GET https://apix.cisco.com/return/v1.0/returns/users/user_ids/svorma8?fromDate=2013-08-01&toDate=2013-08-15 HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Bearer QROt9zFPchfWTZeodjpmC04cGWsd
Content-Type: application/json
Host: apix.cisco.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Sample Response

HTTP/1.1 200 OK
Date: Wed, 14 Aug 2013 05:23:18 GMT
Server: IBM_HTTP_Server
X-Mashery-Message-ID: d43b8915-7ac5-4953-b103-a9fd8f007755
Cache-Control: private
Pragma: private
Content-Type: application/json
Content-Language: en-US
Cache-Control: max-age=0
Expires: Wed, 14 Aug 2013 05:23:18 GMT
Connection: close
Transfer-Encoding: chunked

{
   "OrderList": {
      "APIPagination": {
         "pageIndex": "1",
         "lastIndex": "1",
         "totalRecords": "2",
         "pageRecords": "2",
         "title": "Service Order RMA API",
         "selfLink": "https://apix.cisco.com/return/v1.0/returns/users/user_ids/SVORMA8?fromDate=2013-08-01&toDate=2013-08-15&pageIndex=1" 
      },
      "users": [{
         "userId": "SVORMA8",
         "returnCount": "2",
         "returns": [{
            "rmaNo": "84894100",
            "status": "BOOKED",
            "orderDate": "2013-08-11",
            "caseId": "675775751",
            "contractId": "4348152",
            "serviceLevel": "Advance ReplacementNext Business Day",
            "orderedPart": "WS-X5009=",
            "customerProvidedSN": "",
            "trackingNumber": "1442352345",
            "courierList": "BESTWAY",
            "earliestShipDateTime": "2013-08-11",
            "shippingAddress": {
               "customerName": "XcelCorp",
               "address1": "2900 KOREX DRI",
               "city": "BERWICK",
               "state": "ME",
               "country": "US",
               "siteUseId": "914128396" 
            },
            "onSiteContactName": "SVO RMA8",
            "onSiteContactPhone": "14134268800",
            "onSiteContactEmail": "whoami@cisco.com" 
         },{
            "rmaNo": "84894087",
            "Status": "HOLD",
            "orderDate": "2013-08-09",
            "caseId": "625776365",
            "contractId": "6680005",
            "serviceLevel": "Advance ReplacementNext Business Day",
            "orderedPart": "WS-C6509-V-E-FAN=",
            "customerProvidedSN": "",
            "trackingNumber": "",
            "courierList": "",
            "earliestShipDateTime": "2013-08-09",
            "shippingAddress": {
               "customerName": "KOIR ONLINE",
               "address1": "3016 OMNI STREET",
               "city": "SIHUE",
               "state": "HI",
               "country": "US",
               "siteUseId": "76685207" 
            },
            "onSiteContactName": "Krup Nanerjee",
            "onSiteContactPhone": "78941360",
            "onSiteContactEmail": "knsample@cisco.com" 
         }] 
      }] 
   }
}

Error Codes

This table describes the error codes returned by the Cisco Service Order Return (RMA) API service.

Error Code	Description
API_RMA_FORMAT_ERROR	Invalid RMA number format.
API_DATEFORMAT_ERROR	Invalid date format supplied.
SVO_NO_RECORDS	No order found for the given request.