Get started with using the Finale Inventory Reporting API

Reporting API Overview

The simplest approach to retrieve information from Finale is usually to use our reporting API. The reporting API allows you to run any of the reports in Finale and get the result back in a CSV or JSON format. The reporting API has access to almost all data in the Finale system and produces a result that is much easier to process. Specifically, the reporting API returns data in a table whose values correspond directly to the values displayed in the Finale user interface or presented in PDF or Excel reports generated in Finale. By contrast, the other API endpoints produce more complicated JSON that requires additional processing before being used in a business application. That said, the reporting API can only be used to retrieve information from Finale. The other API endpoints must be used to update information.

Steps to Use the Reporting API

The first step for using the reporting API is to create a report in Finale that contains the information you need using the regular Finale user interface. Your business team can work with your Finale account representative to create a report containing the correct information.

Once you've created the report, copy the URL used to run the report from the browser address bar. From the user interface, the report opens using a URL that displays a progress screen before redirecting to a copy of the report. You'll need to modify the URL slightly to directly access the report from your code.

If the URL for the report in the user interface is:

https://app.finaleinventory.com/{accountPathComponent}/doc/report/pivotTableStream/1722981156957/Reports.pdf?format=xls&data=stock&attrName=%23%23other005&rowDimensions=~lJrNAf7Ay0BzDMzMzMzNwMDAwMDAwJrNAdTAy0CJZmZmZmZmwMDAwAHAwJrNA0XAzP7AwMDAAcDAmjPAzQJ7wMDAwMDAwA&metrics=~kprNBK2nT24gaGFuZMtAZjmZmZmZmsDAwMDAwMCazQSvqE9uIG9yZGVyy0BmOZmZmZmawMDAwMDAwA&filters=W1sicHJvZHVjdFByb2R1Y3RVcmwiLG51bGwsbnVsbF0sWyJzdG9ja0xvdElkIixudWxsLG51bGxdXQ%3D%3D&reportTitle=Search+stock+by+product+or+lot

then you will modify the middle of the URL to replace pivotTableStream with pivotTable to produce the following URL:

https://app.finaleinventory.com/{accountPathComponent}/doc/report/pivotTable/1722981156957/Reports.pdf?format=pdf&data=stock&attrName=%23%23other005&rowDimensions=~lJrNAf7Ay0BzDMzMzMzNwMDAwMDAwJrNAdTAy0CJZmZmZmZmwMDAwAHAwJrNA0XAzP7AwMDAAcDAmjPAzQJ7wMDAwMDAwA&metrics=~kprNBK2nT24gaGFuZMtAZjmZmZmZmsDAwMDAwMCazQSvqE9uIG9yZGVyy0BmOZmZmZmawMDAwMDAwA&filters=W1sicHJvZHVjdFByb2R1Y3RVcmwiLG51bGwsbnVsbF0sWyJzdG9ja0xvdElkIixudWxsLG51bGxdXQ%3D%3D&reportTitle=Search+stock+by+product+or+lot

The modified URL does not show a progress screen and directly returns the formatted report in the HTTP response body.

The above URL is for the "Search stock by product or lot" report.

Formats

The report URL has a format parameter in the query string. If you are writing a program to process data from the reports, it is recommended that you change the format to csv or jsonObject as they are easier to parse than a PDF like in the example URL above.

csv

Below is what the previous report URL looks like when changed to return a CSV file. In it, both the file extension and the format were changed to CSV.

https://app.finaleinventory.com/{accountPathComponent}/doc/report/pivotTable/1722981156957/Reports.csv?format=csv&data=stock&attrName=%23%23other005&rowDimensions=~lJrNAf7Ay0BzDMzMzMzNwMDAwMDAwJrNAdTAy0CJZmZmZmZmwMDAwAHAwJrNA0XAzP7AwMDAAcDAmjPAzQJ7wMDAwMDAwA&metrics=~kprNBK2nT24gaGFuZMtAZjmZmZmZmsDAwMDAwMCazQSvqE9uIG9yZGVyy0BmOZmZmZmawMDAwMDAwA&filters=W1sicHJvZHVjdFByb2R1Y3RVcmwiLG51bGwsbnVsbF0sWyJzdG9ja0xvdElkIixudWxsLG51bGxdXQ%3D%3D&reportTitle=Search+stock+by+product+or+lot

Below is an example of the response for a stock report where there are 2 products with stock. Each line represents a row in the report.

CSV

Product ID,Description,Location,Stock item description,On hand,On order
10009,Shirt
,,Main
,,"M0, open stock",3,0
,,,TOTAL:,3,0
,,TOTAL:, ,3,0
989103,Pants - Jeans
,,Main
,,"M0, open stock",4,0
,,,TOTAL:,4,0
,,TOTAL:, ,4,0

jsonObject

Below is what the previous report URL looks like when changed to return a JSON file. In it, the format was changed to jsonObject and the file extension was changed to JSON.

https://app.finaleinventory.com/{accountPathComponent}/doc/report/pivotTable/1722981156957/Reports.json?format=jsonObject&data=stock&attrName=%23%23other005&rowDimensions=~lJrNAf7Ay0BzDMzMzMzNwMDAwMDAwJrNAdTAy0CJZmZmZmZmwMDAwAHAwJrNA0XAzP7AwMDAAcDAmjPAzQJ7wMDAwMDAwA&metrics=~kprNBK2nT24gaGFuZMtAZjmZmZmZmsDAwMDAwMCazQSvqE9uIG9yZGVyy0BmOZmZmZmawMDAwMDAwA&filters=W1sicHJvZHVjdFByb2R1Y3RVcmwiLG51bGwsbnVsbF0sWyJzdG9ja0xvdElkIixudWxsLG51bGxdXQ%3D%3D&reportTitle=Search+stock+by+product+or+lot

Below is an example of the response for a stock report where there are 2 products with stock. Each JSON object represents a row in the report.

JSON

[  
  {"Product ID":"10009","Description":"Shirt"},  
  {"Product ID":null,"Description":null,"Location":"Main"},  
  {"Product ID":null,"Description":null,"Location":null,"Stock item description":"M0, open stock","On hand":3,"On order":0},  
  {"Product ID":null,"Description":null,"Location":null,"Stock item description":"TOTAL:","On hand":3,"On order":0},  
  {"Product ID":null,"Description":" "},  
  {"Product ID":null,"Description":null,"Location":"TOTAL:","Stock item description":" ","On hand":3,"On order":0},  
  {"Product ID":"989103","Description":"Pants - Jeans"},  
  {"Product ID":null,"Description":null,"Location":"Main"},  
  {"Product ID":null,"Description":null,"Location":null,"Stock item description":"M0, open stock","On hand":4,"On order":0},  
  {"Product ID":null,"Description":null,"Location":null,"Stock item description":"TOTAL:","On hand":4,"On order":0},  
  {"Product ID":null,"Description":" "},  
  {"Product ID":null,"Description":null,"Location":"TOTAL:","Stock item description":" ","On hand":4,"On order":0}  
]

Example

There is an example of running a report from PHP in GitHub at:

PHP Report Example

If you need to change the filter parameters when you run the report (for example to change the date range) the filter parameter is Base64 encoded JSON and can be changed from your code as necessary.