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.

Authentication

There are 3 ways you can authenticate with the REST API:

  1. Basic Authentication: This is the default and most straightforward authentication method. Every HTTP request contains an authentication header according to the Basic-Authentication standard, in order to apply any relevant permission restrictions. HTTP requests that lack such a header are denied. In this case, you need to consult with your System Administrator to obtain a valid username and password.

  2. OAuth2: This is generally used for 3rd-party access to the API. The API client needs to implement the OAuth2 flow, and provide an Authorization header of Bearer. Note that this option requires the purchase of the External ID module for Priority.

  3. Personal Access Token (PAT): Newly introduced in version 19.1 of Priority. With this method, the admin can set a secret token to be used by the client in order to authenticate. Multiple PATs can be associated with a single Priority user, and they can be replaced or deleted independently of one another. PATs can be defined in the REST Interface Access Tokens form in Priority. When using this method, the Authorization header should be set to Basic, the username should the PAT that was defined, and the password should be hardcoded to PAT.

Note: You cannot use Basic Authentication (method 1) while External ID access is enabled.

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:

Header Contents
X-App-Id The unique application ID assigned to your application by Priority Software.
X-App-Key The unique application license key assigned to your application by Priority Software.

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

Run in Postman

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.