The Finale Inventory API is a comprehensive set of services based on REST principles. The API has access to read and modify every entity exposed in the user inteface - in fact Finale's user interface uses the API for its operation. The API is exposed using JSON over HTTPS using the GET method for read operations and the POST method for modification operations
To get started using the API first read the documentation on Authentication. All API sessions must start with a call to the authentication API, both to acquire authorization and to acquire links to the resource collections.
Be sure also to read the documentation on Resource patterns. The Finale Inventory API is defined in terms of resource collections that consistently use a small set of patterns. The documentation on the individual resource collections assumes a foundational understanding of these patterns.
The Example documentation demonstrates how to both read and write using the API using curl, a command line tool that can be used to experiment with the APIs. The curl tool is free software that comes pre-installed on Mac OS X and most Linux distributions and is available for Windows. If you do install curl, select a package the includes SSL support which is required for the Finale Inventory API.
The actual API consists of a set of resource collections corresponding to the various entities exposed in the user interface. The names of the resource collections do not exactly match the names in the user interface. The following list shows the relation between names in the user interface and related resource collections:
- Customer, Supplier ⇒ Party group
- Product ⇒ Product
- Purchase, Sale ⇒ Order, Shipment
- Stock transfer ⇒ Inventory transfer
- Stock change ⇒ Inventory variance, Inventory variance summary
- View stock ⇒ Inventory item
There are places in the documentation where specific fields or entire resources are marked as undocumented. Generally this is because we haven't had yet had customers expressing interest in using those parts of the API. Please contact us if you need to access those parts of API so we can assist you and improve the documentation.
Your usage of the API is covered by our terms of service. This specifically includes the requirement that "You agree not to engage in any of the following prohibited activities: ... taking any action that imposes, or may impose at our sole discretion an unreasonable or disproportionately large load on our infrastructure". Currently we interpret this to mean no more than 120 updates (POST request) per minute, 120 single item fetches (GET specific entity) per minute, and no more than 300 collection requests or reports per hour.
Applications that exceed these rate limits may receive HTTP 429 Too Many Requests errors when they hit the rate limit. Once hitting the limit, requests for the API will fail with that error code until the next time period (minute or hour depending on the specific API endpoint) starts. API endpoints that have automatic enforcement will return the following HTTP headers to assist with staying under the rate limits:
- X-RateLimit-Limit: The total number of requests they can make in a time period.
- X-RateLimit-Remaining: The number of requests they can still make before the reset time.
- X-RateLimit-Reset: Unix timestamp of when the rate limit will be restored.
Please contact us to discuss your specific application if you expect to be close to these request rates so we can discuss your application and how it can be optimized to run efficiently on our infrastructure.