Skip to main content

Label or Unlabel a Report


Label or Unlabel a Report

Contact Zuora Global Support to enable this feature in your tenant. This feature is currently in development and is subject to change without advance notice.

The Label a Report, Reporting API posts one or more labelId attribute values (folders) to an existing report definition.  The report labelId attributes make the report accessible from the corresponding folders.

As a preferred alternative you may want to set labelIds when you Copy a Report and Assign Labels or when you Save a Report

To remove label attributes you can make a DELETE call to remove the reports's labelId attributes using a request body with an array of labelIds that you want to be removed from the specified ReportId



The ReportId to which you want to add or remove labels must be known prior to using these Reporting API calls. The ReportId is added as a request path value as is shown in the Request section below. 

You can obtain the ReportId (id) from the JSON response to the call: Search by Report Names. ReportId is also given in the response to Create a Report or Save a Report


Folder labelIds must also be known ahead of time to add or remove them from a report.  Folder labelIds are added to the request body as an array of one, or many labels.

Getting labelIds

You can get all the current report label Ids for a particular report with the response to Get Report Labels for ReportIdor you can call the following to get all labels under the root label:



Or add in a parent labelId to get subordinate labelIds with a call like the following:




To Add Labels to a Report

API Sandbox: 




To Remove Labels from a Report

API Sandbox: 




This POST request must be submitted with: Content-Type: application/json

Request Body

The request body must include the labelIds, as a comma-separated list inside a bracketed array (enclosed by [square brackets]) as is shown in the example request body below.


A successful invocation of Save a Report and Assign Labels returns a JSON response with a new and unique ReportId with the report metadata, details and definition.  Refer to the JSON response in the example below to see how the response is structured.


HTTPS Requests

To add labels to a report with a ReportId: ab123


To remove labels from a report with a ReportIdab123


Both the POST and the DELETE REST method calls must be accompanied by a JSON request body containing a comma-separated array of labelIds. 

Request Body:

The request body has the same format regardless of whether the REST method is POST or DELETE.




JSON Response:


"success": true

"response": "The reports label status has successfully been changed."



Exception Condition
Header: HTTP/1.1 401 Unauthorized Basic authentication failed. Check apiAccessKeyId or apiSecretAccessKey.
Bad Request; That's a bad request API endpoint or submission is incorrect.  Check your URL.

Status 400: Bad Request

<zanResponse success="false">

<response xsi:type="xs:string">

{ "errorId" : "1d644185-1b92-4ffc-a5f4-740c96d9e187", "message" : "Cannot find any matching label(s) for id(s) provided in request.", "errorCode" : "ZAN-USAGE-REST-ERROR" }



One or more of the labelId values submitted could not be found. Check that the value of the labelId is correct.

Status 500: Internal Server Error

"Required request body content is missing: org.springframework.web.method.HandlerMethod$HandlerMethodParameter@49d1be25"

POST and DELETE for update of report labels requires a request body message with the labelId values.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<zanResponse success="false"><response xsi:type="xs:string">

{ "errorId" : "e57be6da-ef02-418b-9b7b-8bcecbcdd51c", "message" : "Could not read JSON: Can not deserialize instance of java.util.ArrayList out of VALUE_STRING token\n at [Source:; line: 1, column: 41] (through reference chain: com.zuora.zan.reportlabel.controller.LabelParam[\"labelIds\"]); nested exception is com.fasterxml.jackson.databind.JsonMappingException: Can not deserialize instance of java.util.ArrayList out of VALUE_STRING token\n at [Source:; line: 1, column: 41] (through reference chain: com.zuora.zan.reportlabel.controller.LabelParam[\"labelIds\"])", "errorCode" : "ZAN-REST-ERROR" }


This can happen because the request body labelId values are not enclosed within square brackets as an array: ["labelId1","labelId2", "labelIdN"].