Introduction

The Priority REST API is based on the Open Data Protocol (OData), a data access protocol built on HTTP and REST. This documentation provides basic examples of the various requests and responses you can make using the Priority REST API. For a more detailed understanding of OData, please refer to OData Documentation.

Service Root URL

All the examples in this documentation are based on sample requests made to a Priority OData service. Please replace the serviceRoot below with a service root URL appropriate to your installation of Priority. Note that all other URLs in the OData service use this URL as a basis. Consult with your System Administrator if you are not sure what the service root for your installation is.

Request/Response Format

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status.

Response are capped at 350MB in size.

Some general information about responses:

• Dates are returned in DateTimeOffset format: YYYY-MM-DDTHH:MM:SS+HH:MM
• Resource IDs are returned as strings.
• Blank fields are generally included as null or emtpy string instead of being omitted.

Starting with version 21.0, the timezone can be set per company (the TZSERVER system constant) , which might lead to a different offset than expected. Verify the timezone of the company with the Priority administrator.

There are 3 possible situations:

1. The TZSERVER constant is set to off (TZSERVER=0). Dates and times will be based on the timezone of the server.
2. The TZSERVER constant is set to on (TZSERVER=1), but no timezone is specified for the company. Dates and times will be based on the timezone of the server.
3. The TZSERVER constant is set to on (TZSERVER=1), and a timezone is specified for the company. Dates and times will be based on the timezone of the company.

In previous versions, the time offset was always based on the timezone of the server.

Application License

In version 18.3, Priority Software introduced an additional form of licensing - per-application licenses. When accessing the system under this license, requests to the Priority OData service must contain additional headers providing application license information:

Example:

X-App-Id: APP001
X-App-Key: 15nXqSDXnNeaIEFQSSDXkNeZ16DXodeV16TXmSDXoteb16nXmdeVISEh

Requests that do not contain these headers will be treated as using generic API licensing.

Features by Version

Certain features are tagged with a version number reflective of the Priority version in which they were released. Features in development are marked as Beta, indicating they will be available in the next Priority release. In certain cases, features (including beta features) can be obtained for previous versions of Priority pending a request to Priority Software.

Postman Collection

You can use this Postman collection to run the requests in the API against our demo environment. For authentication, use the following credentials:

Username apidemo

Password 123

Error Message Format

Starting with version 19.1 of Priority, errors outputted by the REST API are in JSON format instead of XML format.

Debugging

If you are running into unexpected behavior in Priority when inputting data using the API, that is not duplicated in manual entry in Priority’s UI, you can add a Trace to your requests. Requests with Trace will log additional information on form behavior to aid in debugging the issue.

To add Trace to your requests, add the following header:

X-App-Trace=1

The Priority System Administrator must also enable tracing, by adding a line to the tabula.ini file, under the internet section:

[Internet]
Sqldebug=1

Trace files are saved in Priority’s tmp folder. The path to this folder appears in the tabula.ini file.

Transaction Counting

Whenever a user updates a form in the system (i.e., adds a new record or updates an existing one) via the API, the system counts it as a transaction. Transactions are purchased in packages of 10,000, which are divided equally between API users and renewed monthly.

For example, if you purchase one package, and you have five API users, each user will receive 2,000 transactions per month. Transaction usage is per user, so if Bob used all his transactions and Steve used only 500, Bob cannot use Steve’s transactions to record data. He has to wait until the beginning of the next month, when he will receive another 2,000 transactions.

Examples:

• Creating an order (1 record in ORDERS) with 5 lines (5 records in ORDERITEMS) would be counted as 6 transactions.
• Updating the order’s status (change to 1 record) would be counted as 1 transaction.

Each form in Priority has a defined transaction type (premium, regular or free of charge) that determines which type of transaction is used when recording data to that form via an API or external interface. You can view details of form definitions and transaction usage in the View License Details report. Forms that do not appear in the report use regular transactions. Additional Information regarding API transaction usage can be found in the API Transaction Count report.

Priority Cloud - Fair Use Policy

To prevent APIs from being overloaded by too many requests, we have introduced API throttling to regulate the API usage per tenant. The use by client applications or background job threads that make multiple high volume calls on a continuous basis in order to extract or import data, or update it, can have unintended consequences and impact underlying resource availability, cause performance issues, and ultimately interrupt customer operations.

While throttled, requests will be rejected with a standard HTTP error 429.

The following limitations are enforced:

• Calls per minute: Each user is limited to a maximum of 100 API calls per minute.
• Parallel requests: Up to 15 requests can be queued at once. The system handles up to 10 requests at the same time, with another 5 in the queue.
• Timeout limit: requests that take longer than 3 minutes to process will be dropped and generate an error.

Priority Software reserves the right to update or modify this policy from time to time by posting the changes on this website.

Additional Notes

• On Priority Cloud tenants hosted on AWS, the Odata context returned uses http instead of https. This can be safely ignored, and requests should still be made with https.

We recommend you configure your client or package to always use the same base URL, rather than pick up the URL from the response received from requests.