Use the Reporting API

Overview

The Reporting API notation here does not include the authorization information that is passed with every request. All Reporting API requests require that you specify these parameters and values as your user information.

Responses include the following information:

• All responses return a base response consisting of a response code (responseCode) and a response message (responseMsg).
• Most responses return applicable response parameter data.
• Some responses return a status code (statusCode) and a status message (statusMsg).

Run reports

You can run reports and obtain the report data right away. If, however, running a report takes more than the time allotted, the report is run offline, and you must periodically check for the report data.

To run a report:

1. Call runReportRequest, providing the following parameter information.

   runReportRequest(reportName,reportParams,pageSize)
   

   Parameter	Description
   reportName	Name of the report, for example, DailyActivityReport.
   reportParam(s)	(Optional) and for each request input param to be assigned a value.
   pageSize	Number of rows of data per page. Default is 50.

   The runReportResponse returns the reportId. The reportId is used to refer to the particular report in future requests. The reportId returned is valid for up to 120 days.

2. Call getMetaDataRequest, providing the ReportId returned when the report was run, to get the metadata.

   getMetaDataRequest(ReportId)
   

   getMetaDataResponse returns the following data.

   Parameter	Description
   numberOfRows	Total number of rows.
   numberOfPages	Total number of pages in the report.
   pageSize	Page size.
   numberOfColumns	Total number of columns.
   dataName	Name of each column.
   dataType	Type of column data, for example, string.

3. Call getDataRequest with the following parameters to get the report.

   getDataRequest(reportId,pageNum)
   

   Parameter	Description
   reportId	ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
   pageNum	Report page number containing data to be returned.

   Data is returned for the report page specified by pageNum. To obtain the data in a multi-page report, you must call getDataRequest for each report page.

Run reports offline

When a report takes longer to run than the time allotted, it is taken offline and status code 2, “Report is currently executing,” is returned. You must check for the results at a later time.

1. Request to run a report by calling runReportRequest.

   runReportRequest(reportName,reportParams,pageSize)
   

   Parameter	Description
   reportName	Name of the report, for example, DailyActivityReport.
   reportParam(s)	(Optional) and for each request input param to be assigned a value.
   pageSize	Number of rows of data per page. Default is 50.

   The report times out. The ReportId and status code 2 are returned.

2. Get the report results later by calling getResultsRequest, providing the reportId as a parameter.

   getResultsRequest(reportId)
   

   getResultsResponse returns a statusCode and statusMsg. Call getResultsResponse in a loop until statusCode 3, “Report has completed successfully,” is returned.

3. Request to get the report’s metadata by calling getMetaDataRequest.

   getMetaDataRequest(ReportId)
   

   getMetaDataResponse returns the following data.

   Parameter	Description
   numberOfRows	Total number of rows.
   numberOfPages	Total number of pages in the report.
   pageSize	Page size.
   numberOfColumns	Total number of columns.
   dataName	Name of each column.
   dataType	Type of column data, for example, string.

4. Request to get the report data by calling getDataRequest.

   getDataRequest(reportId,pageNum)
   

   Parameter	Description
   reportId	ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
   pageNum	Report page number containing data to be returned.

   Data is returned for the report page specified by pageNum. To obtain the data in a multi-page report, you must call getDataRequest for each report page.

Manage report templates

Using the Reporting API, you can create, update, and delete report templates.

Create a report template

To create a report template, call createTemplateRequest with the following parameters.

createTemplateRequest(templateName,reportName,reportParams)

The response to creating a report template returns a respCode and respMsg.

Update a report template

To update a report template, call the updateTemplateRequest with the following parameters.

updateTemplateRequest(templateName,reportParams)

The response to updating a report template returns a respCode and respMsg.

Note: Updating a report template is not incremental. It only sets values for the parameters that are passed to updateTemplateRequest.

Delete a report template

To delete a report template, call deleteTemplateRequest, providing the templateName as the input parameter.

deleteTemplateRequest(templateName)

The response to deleting a report template returns a respCode and respMsg.

Using report templates

Report templates are run like any standard report. They can also be scheduled to run on a daily, weekly, or monthly basis. Report template schedules can be updated or deleted.

Run a report template

To run a report template and obtain the report template data:

1. Call runReportRequest with the following parameters.

   runReportRequest(templateName,reportParams,pageSize)
   

   Parameter	Description
   templateName	Name given to the report template when it was created.
   reportParam(s)	(Optional) paramName and paramValue for each reportParam that you want to assign a value to. These parameters can be ones previously saved in the report template or additional ones. The parameter values take precedence over the values previously saved for the parameters in the report template.
   pageSize	Number of rows of data per page. Default is 50.

2. Request to get the report’s metadata by calling getMetaDataRequest.

   getMetaDataRequest(ReportId)
   

   getMetaDataResponse returns the following data.

   Parameter	Description
   numberOfRows	Total number of rows.
   numberOfPages	Total number of pages in the report.
   pageSize	Page size.
   numberOfColumns	Total number of columns.
   dataName	Name of each column.
   dataType	Type of column data, for example, string.

3. Request to get the report data by calling getDataRequest.

   getDataRequest(reportId,pageNum)
   

   Parameter	Description
   reportId	ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
   pageNum	Report page number containing data to be returned.

   Data is returned for the report page specified by pageNum. To obtain the data in a multi-page report, you must call getDataRequest for each report page.

Schedule a report template

You can schedule a report template to run on a daily, weekly, or monthly basis. The Reporting API includes functionality to create schedules and to get the results of a scheduled report template.

1. Create a schedule for a report template, call createScheduleRequest with the following parameters.

   createScheduleRequest(scheduleName,templateName,schedule)
   

   Parameter	Description
   scheduleName	Name that you give to the schedule.
   templateName	Name of the report template to be scheduled.
   schedule	One of these values: daily. weekly. Select dayOfWeek value: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. monthly. Specify dayOfMonth value as an integer from 1 to 31. If you specify 30 when the month is 28 days long, the value is corrected to 28. Note:The time of the day starts at midnight the previous night. The value daily, for example, means midnight the previous night to midnight tonight.

2. To get the results of a scheduled report template that is run, call getScheduleRequest with scheduleName as a parameter.

   getScheduleRequest(schedulename)
   

   getScheduleResponse returns all the reportIds and execution dates of the reports that were run on the schedule.

3. For each report, call getMetaDataRequest, passing in the reportId as a parameter, to get the information on how that report is formatted.

   getMetaDataRequest(ReportId)
   

   getMetaDataResponse returns the following data.

   Parameter	Description
   numberOfRows	Total number of rows.
   numberOfPages	Total number of pages in the report.
   pageSize	Page size.
   numberOfColumns	Total number of columns.
   dataName	Name of each column.
   dataType	Type of column data, for example, string.

4. Request to get the report data for each report that was run by calling getDataRequest.

   getDataRequest(reportId,pageNum)
   

   Parameter	Description
   reportId	ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
   pageNum	Report page number containing data to be returned.

   Data is returned for the report page specified by pageNum. To obtain the data in a multi-page report, you must call getDataRequest for each report page.

Manage report template schedules

Using the Reporting API, you can update and delete report template schedules.

Update a schedule

To update a schedule, call the updateScheduleRequest with the following parameters.

updateScheduleRequest(scheduleName,templateName,schedule)

The response to updating a schedule returns a respCode and respMsg.

Delete a schedule

To delete a schedule, call deleteScheduleRequest, providing the scheduleName as the input parameter.

deleteTemplateRequest(scheduleName)

The response to deleting a schedule returns a respCode and respMsg.

Performing API Searches

Using the Reporting API, you can search for transaction data by any of the following search names.

• TransactionIDSearch
• BatchIDSearch
• AccountNumberSearch
• CommentSearch
• AccountNumberRefSearch
• PurchaseOrderSearch
• RecurringBillingProfileIDSearch
• RecurringBillingProfileNameSearch
• RecurringBillingAccountNumberSearch
• RecurringBillingCommentSearch
• RecurringBillingAmountSearch

To run a search request:

1. Call runSearchRequest with the following parameters.

   runSearchRequest(searchName,reportParam(s),pageSize)
   

   searchName	One of the search names listed above, for example, TransactionIDSearch.
   reportParam(s)	paramName and paramValue of one or more input parameters for this search. See Report Parameters for the required and optional parameters.
   pageSize	Number of rows of data per page. Default is 50.

The runSearchResponse object returns the reportId for this search and the statusCode and statusMsg. The reportId returned is valid for up to 120 days.

1. Request to get the search metadata by calling getMetaDataRequest.

   getMetaDataRequest(ReportId)
   

   getMetaDataResponse returns the following data.

   Parameter	Description
   numberOfRows	Total number of rows.
   numberOfPages	Total number of pages in the report.
   pageSize	Page size.
   numberOfColumns	Total number of columns.
   dataName	Name of each column.
   dataType	Type of column data, for example, string.

2. Request to get the search data by calling getDataRequest.

   getDataRequest(reportId,pageNum)
   

   Parameter	Description
   reportId	ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
   pageNum	Report page number containing data to be returned.

   Data is returned for the report page specified by pageNum. To obtain the data in a multi-page report, you must call getDataRequest for each report page.

Response and Status Codes

Response Codes

Response codes indicate the success or failure of a Reporting request. The table below describes the supported response codes and messages returned with each.

Status Codes

Status codes indicate the status of a report, not necessarily the status of the Reporting request to be executed. A report may fail even if a Reporting request succeeds.