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.
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:
- Resource IDs are returned as strings.
- Blank fields are generally included as null or emtpy string instead of being omitted.
|200||OK with content|
|201||OK, no content - response to a DELETE request|
|404||Not found - requested form or record do not exist|
|409||Conflict - occurs when trying to POST to a record that already exists|
Potentially Breaking Change
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:
- The TZSERVER constant is set to off (TZSERVER=0). Dates and times will be based on the timezone of the server.
- 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.
- 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.
There are 3 ways you can authenticate with the REST API:
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 user name and password. The user name is defined in the API User Name field of the Personnel File form and is separate from the user’s standard user name.
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.
Personal Access Token (PAT): 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
Note: You cannot use Basic Authentication (method 1) while External ID access is enabled.
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:
|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.|
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.
You can use this Postman collection to run the requests in the API against our demo environment. For authentication, use the following credentials:
Error Message Format
Starting with version 19.1 of Priority, errors outputted by the REST API are in JSON format instead of XML format.
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:
The Priority System Administrator must also enable tracing, by adding a line to the tabula.ini file, under the internet section:
Trace files are saved in Priority’s tmp folder. The path to this folder appears in the tabula.ini file.