API Reference Explained

The Predictive Index software platform API Reference site is located at:


It is a single, expandable reference document containing all the API methods, request parameters, response properties, and error codes which are published for use in automated integrations between PI software platform and other systems. 

The content is an automatically generated from the PI software platform source code which means that it is always up to date with the most recently released version of the PI software. 

Why does the link include "swagger"? Swagger UI is the name of the open source project used to auto-generate this reference documentation.

Reading the API Reference

Target Audience

The API Reference site assumes that you know where, how, and why you might use the content within a script or tool that performs RESTful API web service calls. It makes no attempt to teach you how that is done or why you would want to use one method / parameter / property over another. If you are looking for answers to the "Why would I use this method?" question, refer to Common Examples and Integration Best Practices.

Document Hierarchy

The document is organized into two levels of hierarchy: 
  • Class- General API classes that provide several types of access to an object such as BehavioralAssessments or Persons. Each of these are sometimes referred to an individual API (e.g. "the Persons API")
  • Method- Individual API methods within each class that performs a specific action (e.g. GET behavioralassessments/{id} or GET persons/{id}) - 
Each level can be expanded or collapsed to show just the detail you wish to see. You may also notice that each section has its own direct web address so you can share links to specific API methods.

JSON only - not XML

The API Reference site offers drop-down lists for different Content-Types, but in reality the platform only supports JSON (JavaScript Object Notation) and does not support XML (eXtensible Markup Language) in both requests and responses. Use and expect JSON, don't use or expect XML.

Method Sections

In each Method section, there are typically the following sections:
  • Method title - a format string notation describing the spelling and sequence of the method and any parameters to be included in the request URL path.
    TIP: A normal integration can usually ignore the methods that use /companies/ in the URL since most integrations are configured with just one PI instance in mind.
  • Implementation Notes - quite general, but sometimes makes important notes about limits on response content.
  • Response Class - explains the structure of the response content returned upon a successful method call (response status 200). Note: if you click on Model, you will see the data types expected. If you click on Example Value, you will see sample JSON.
  • Response Content Type - use only application/json  - ignore the text and XML options
  • Parameters - pay attention to the Type column
    • path- you must include the parameter in the request as part of the slash-separated components of the path as shown in the format string in the method title
    • query- expected in GETmethods, the parameter must follow the question mark (?) and appear in key=value format separated by ampersands (&)
    • body- expected in POST or PATCH methods, a group of parameters must be structured as JSON. To place a blank parameter set into the Value text box, click on the Example Value in the Data Type column. Then you can edit the blank parameter set values as desired.  
  • Response Messages - the format of any messages to expect. Be sure to build support into your integration that handles expected errors gracefully. Be sure to include support for HTTP response status 429 which indicates too many requests in a time period by performing an exponential back-off retry strategy.
  • Try it out! - this button allows you to interactively test the method using live data if you are authenticated (see next section)

Testing with the API Reference

The API Reference page is designed to support interactive testing that will make real changes to the data of the connected PI instance.


There are two methods of authentication available to allow you to perform testing:

  • Log in to PI Software - if you first log into the PI Software, and then in the same browser visit the API Reference site, you can perform actions using the existing authenticated session using OAuth. Any requests you make will operate under the permissions of the user that is currently logged in.
  • API Key - if you have an API Key generated for a user with permissions in a PI software instance, you can enter the API Key in the text box at the very top of the page labeled "api-key". With the api-key filled in, all requests performed in the page will include an HTTP header with the name api-key and the value you provided. Any requests you make will operate under the permissions of the user that owns the API Key.

Effects of Testing

Keep in mind that all actions taken via the API Reference page are always real -- they create or alter real, permanent data in the PI software instance. There is no "test mode" -- whatever you do via the API will generate email messages, alter data, and otherwise have the same effects as any action taken while logged into the PI software. 

If you do not believe it is safe to test the API using your production PI software instance, you can request a Sandbox Account for use in testing so your test data will not mix with your production data.

Performing Testing

The "Try it out!" button will submit whatever request is being shown with the parameters you may have filled in, and the results will be displayed just below the Try it out! button. The following sections will appear after you submit a request:

  • Curl- the command line equivalent to the action taken by the Try it out! button using the cUrl utility program.
    TIP: Be sure you implement any of the required headers you see in the Curl command!
  • Request URL - the complete URL of the request made by the Try it out! button
  • Response Body - the JSON response content, if any, returned by the API after using the Try it out! button. If an error occurred in processing the request, error content formatted as JSON will be shown here.
    TIP: You should make intentional mistakes and see what error messages are shown here when you do.
  • Response Code - the HTTP response code returned by the API after using the Try it out! button. Success response codes are in the 200 range. 400 or higher is an error.
  • Response Headers - the HTTP headers included in the response from the API after using the Try it out! button.

Limitations of Testing PDF Output

Whenever a request is expected to produce a PDF file as a result (for example, the Behavioral Report), the API Reference page will produce a blank PDF file, even when there is no error or mistake in the request or the actual result. This is a limitation of the API Reference page, not evidence that you did something wrong in making the request.

When testing any method that is expected to return a PDF file or other file object, you can test until you get a success response code (200 or 201 or 204) with the API Reference page, but to actually view the file result you must use another request/response testing tool such as Postman or similar.