PI API Key Testing and Troubleshooting

Predictive Index customers who wish to use the PI Application Programming Interface (API) to access their PI data must generate and use an API Key. Once generated, it is often useful to test the API Key to learn whether it works as expected.

This article provides guidance for testing and troubleshooting PI API Keys.

Testing a PI API Key

Test any Predictive Index API Key through the API Reference site published by The Predictive Index (referenced on the PI Developers site). 

Does it work at all?

A good test method to choose is “GET Behavioral Assessments” which will read up to 50 existing behavioral assessments:

  1. Open this page: https://pi.predictiveindex.com/swagger/ui/index#!/BehavioralAssessments/BehavioralAssessments_GetBehavioralAssessmentsV2(opens in a new tab)

  2. Paste the API Key into the upper-right box in the header of the web page (NO need to click Explore)

  3. Scroll down to the “Try it out” button at the bottom of the GET Behavioral Assessments section and click it

  4. Scroll to the Result below the button and see what it says

    1. If the Result shows assessment results (in JSON format), your API Key works!

    2. If the Result section shows a 401 error, the API Key is not working correctly. See Troubleshooting below…

Does it do everything I need?

What do you need the API Key to allow you (or the software using the API Key) to do?

  • Read Basic Data – If you intend to use the API Key to simply read data available to the PI User that owns the API Key, the test above will be enough.
  • Read All Data – If you intend to use the API Key to read ALL the data in the PI instance, then the PI User that owns the API Key should be given an elevated role such as Power User or Account Admin. If your instance of PI also utilizes Cognitive Assessments, you may need to grant Cognitive Access to the API Key User, too.
  • Create and Modify All Data – If you intent to use the API Key to not only read existing data but also to create and send new assessments and invitations, to change Person data, and/or to Archive assessments, then you must assign the API Key Owner the role of Account Admin or Account Owner (and grant Cognitive Access if your instance uses the Cognitive Assessment).

To test whether the API Key is correctly configured to do “all you need it to do”, you must test several of the intended actions that will be taken by the system using that API Key. Here are some additional tests you might perform:

Create a Person and Send a Behavioral Assessment

Use the POST Behavioral Assessment method. This method can be used two ways: to send an assessment for an existing PI Person, or to create a new PI Person and send them an assessment. The example below will do the second: create a new PI Person and send them a behavioral assessment:

  1. Open this page: https://pi.predictiveindex.com/swagger/ui/index#!/BehavioralAssessments/BehavioralAssessments_PostBehavioralAssessmentBybehavioralAssessmentToCreatedirectToNewSurveySite

  2. Paste the API Key into the upper-right box in the header of the web page (do NOT click Explore)

  3. Scroll back down to POST Behavioral Assessment method

  4. Create a request payload using a real email address at which you can receive the assessment invitation and put it into the “behavioralAssessmentToCreate” space. Here is a sample (it must be in JSON format, as shown):

    1. {
  "notifyAssessmentAvailableUsingEmail": 1,
  "firstName": "API Key",
  "lastName": "Tester",
  "email": "somerealemailaddress@domain.com",
  "personType": "Other"
}
  5. Click the “Try it out!” button
  6. Look at the HTTP Response Code in the Response section.
    1. If it is “201” then you have been successful and your API Key can be used to create/send assessments
    2. If it is anything else, then you have either:
      1. Introduced a syntax error in your behavioralAssessmentToCreate payload
      2. Used an API Key whose PI User does not have permission to send assessments. To resolve this, go into the PI software, find the user, and change their role to Power User or Account Admin.

Archive an existing Behavioral Assessment

Use the DELETE Behavioral Assessment by ID method to send an archive command for a behavioral assessment. This will soft-delete the person and all their assessments and make it impossible to read their data via the API or the PI software, so do not test this on a real person whose data matters to you!! The only way to recover soft-deleted data is to ask PI Support to help you.

  1. Use the GET Behavioral Assessments method shown in the “Does it work at all?” section at the top of this article to get results.
  2. In the Results of that method, find an assessment you are okay to archive. For example, if the assessmentState = 50, that assessment expired and is no longer of any use. If the assessment was sent long ago, it is probably safe to archive it. When you have found an assessment to archive, copy its assessmentId to a temporary location.
  3. Open this page: https://pi.predictiveindex.com/swagger/ui/index#!/BehavioralAssessments/BehavioralAssessments_DeleteBehavioralAssessmentByIdByid

  4. Be sure your API Key is in the upper-right box in the header of the web page (do NOT click Explore)

  5. Scroll back down to DELETE Behavioral Assessment by ID method

  6. Paste the assessmentId you copied in step 2 into the field labeled “id“
  7. Click the “Try it out!” button
  8. Look at the HTTP Response Code in the Response section.
    1. If it is “204” then you have been successful and your API Key can be used to archive assessments
    2. If it is anything else, then either:
      1. The assessmentId you specified is not correct. Did you copy/paste it correctly? Did you archive it previously? or
      2. The API Key whose PI User does not have permission to archive assessments. To resolve this, go into the PI software, find the user, and change their role to Power User or Account Admin.

Troubleshooting an API Key Problem

401 Error

A 401 error with a PI API Key usually arise when one of the following has occurred:

  1. The API Key belongs to a PI User who has been deactivated by accident.
    1. To resolve this, log into PI software as an Account Owner or Account Admin and go to the Administration > User Management view. Find the API Key owner in the list and ensure the activation switch is toggled ON.
  2. The API Key has been replaced because someone clicked the “Generate” button which creates a new API Key for the PI User and invalidates the old key that you are using.
    1. To resolve this, find the new API Key that was generated for this PI User and start using it instead of the one that was failing.
  3. The PI Instance/Account does not have API Access turned on. It is possible to generate an API Key even when API Access is turned off.
    1. To get API Access turned on, submit a request to integrations@predictiveindex.com and include the name of the PI Instance/Account. Once API Access is turned on, normally it should not be turned off by PI, but anything is possible.