Knowledge Center

Knowledge Center > Reporting > API Reference > Overview of the Zuora Reporting API

Overview of the Zuora Reporting API

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 Zuora Reporting API provides a structured, programmatic way to access and control reporting features, methods, and data.  Whatever you can accomplish using the user-interface, the API can do as well.

REST Endpoints for API Sandbox and Production

The Reporting API URL endpoints are different from that of the Zuora REST API.  The Reporting API REST services are:

Environment API Endpoint
API Sandbox (US Data Center) https://zconnectsandbox.zuora.com/api/rest/v1 
Production (US Data Center) https://zconnect.zuora.com/api/rest/v1
API Sandbox (EU Data Center) https://zconnect.sandbox.eu.zuora.com/api/rest/v1
Production (EU Data Center) https://zconnect.eu.zuora.com/api/rest/v1

Versions

The Reporting API is a versioned REST API.  The URL endpoint contains the major version number. Versions help ensure that any changes will be backward compatible by allowing the API user to specify a version to get consistent returns.  Refer to the applicable description of Zuora REST API Versions for more information. 

Request and Response Types

All requests that have a request body must be JSON encoded.  Most of the Reporting API methods use only query path parameters that are appended to the URL/method namespace as part of the request path, but for those that have a body payload, declare the content-type:

  Content-Type: application/json

When responses have a body or payload, they are also sent as JSON formatted content.

  Content-Type: application/json;charset=UTF-8

Authentication

You must have a valid Reporting profile to authenticate and gain access to the secured Reporting API endpoint.

You can authenticate in the following ways:

  • Set the apiAccessKeyId (user login) and apiSecretAccessKey (user password) in the header to authenticate to your chosen REST endpoint. For example:

    curl https://zconnectsandbox.zuora.com/api/rest/v1/reports/search?query=Financial \
      -H "apiAccessKeyId: {username}" \
      -H "apiSecretAccessKey: {password}" \
  • Use the Zuora session token from your active browser session. Log in to Zuora and your browser will store a Z-Connect cookie that can be used to authenticate and send API calls. A REST client integrated with your browser as an extension or plug-in will be necessary to use your browser session key to authenticate REST calls. This method sets the ZSession request header.

The Reporting API does not support OAuth or Basic Authentication.

Entity Authentication

If your tenant has the Multi-entity feature enabled, you can use the entityId or entityName header to specify which entity to authenticate against. For example:

curl https://zconnectsandbox.zuora.com/api/rest/v1/reports/search?query=Financial \
  -H "entityName: EuropeanBU" \
  -H "apiAccessKeyId: {username}" \
  -H "apiSecretAccessKey: {password}" \

If you do not specify entityId or entityName, you will authenticate against the entity in which your user account was created. If you specify entityId and entityName, an error will occur.

You can use the Get entities operation to retrieve entity information.

Authorization

Whatever an authenticated user can accomplish using the Reporting user-interface, the API can do with the right method invocations.

Use of the Reporting API is constrained by the permissions defined for the user login invoking a method. API users and development should use a login with the Manage permission because the limitations for a user with view-only permission is restrictive.  Refer to the Reporting documentation on Roles and Permissions for more information on user permission controls and restrictions if you will build an interface for users.

Request Parameters

Three kinds of REST request parameters are present in the Reporting API: Path, Query, and Body

Path Parameters

Request path parameters are represented in the URL path by the name of the request parameter enclosed in {curlyBraces}.  Replace the request parameter and curly braces with the value required for invocation of the Reporting API method.   In this example, {labelId} is the request path parameter that must be specified:

GET https://zconnectsandbox.zuora.com/api/rest/v1/reports/reportlabels/{labelId}

And here is the value for {labelId} substituted in the REST URL ready for sending provided appropriate authentication headers. 

GET https://zconnectsandbox.zuora.com/api/rest/v1/reports/reportlabels/0000000050f401150150f52e9f080010

Query Parameters

Query parameters set an attribute to a value, and they are appended to the end of the URL path when they are sent. Some query parameters are very strict about the syntax of the values that they will accept, so pay attention to the types of enclosing brackets and quote marks submitted as values.  

Here below is an example of a Reporting API query being constructed using the Chrome Advanced REST client.  The URL is broken into parts so that the query parameters can be defined more easily. When the user clicks to roll the query back into a single URL string, the query parameters are appended to the end of the URL with proper REST syntax. Advanced REST client - Query parameters roll-up to a single URL string

Body Parameters

Request Body parameters occur when the request type is POST, PUT, PATCH, or DELETE.   The body of the request or the payload is separate from the URL and it must usually be encoded in JSON format.  The Reporting API body may be very large text strings when report definitions must be passed by the API.  Here is an example of a request body with a simple report definition ready for a POST:

{
    "name": "Invoice Report",
    "datasource": "Transaction DataSource",
    "dsName": "Payment",
    "description": "This is my Invoice Report",
    "definition": "{\"rowFields\":[{\"name\":\"CreatedDate\",\"id\":\"Account.CreatedDate\",\"label\":\"Created Date\",\"type\":\"datetime\",\"order\":11,\"dataSourceName\":\"Account\",\"dataSourceLabel\":\"Account\",\"dataSourceType\":\"Account\",\"searchKey\":\"Account Created Date\",\"custom\":false,\"filterable\":true,\"sortable\":true,\"groupable\":true,\"dateOptions\":{\"groupBy\":\"NG\",\"cohortStartDate\":\"\"}}],\"colFields\":[{\"name\":\"AccountNumber\",\"id\":\"Account.AccountNumber\",\"label\":\"Account Number\",\"type\":\"text\",\"order\":1,\"dataSourceName\":\"Account\",\"dataSourceLabel\":\"Account\",\"dataSourceType\":\"Account\",\"searchKey\":\"Account Account Number\",\"custom\":false,\"filterable\":true,\"sortable\":true,\"groupable\":true}],\"valFields\":[{\"name\":\"SalesRepName\",\"id\":\"Account.SalesRepName\",\"label\":\"Sales Rep\",\"type\":\"text\",\"order\":28,\"dataSourceName\":\"Account\",\"dataSourceLabel\":\"Account\",\"dataSourceType\":\"Account\",\"searchKey\":\"Account Sales Rep\",\"custom\":false,\"filterable\":true,\"sortable\":true,\"groupable\":true,\"aggregation\":\"COUNT\"}],\"detailFilters\":[],\"summaryFilters\":[],\"selectedFields\":[]}"
}

This simple report definition reveals that it is significantly easier to create a report using the Report Builder user interface.  Copies of a report definition can then be programmatically manipulated with the support of Reporting API calls to save, label and run that report to get the results you want.  

Last modified
15:23, 14 Aug 2017

Tags

Classifications

(not set)