Generating a PI API Key for PI v1

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.

API Keys are “owned” by individual PI Users and are not assigned or created as a company-wide setting. The role and permissions of the user that owns an API Key determines the access that API Key will grant.

This article explains how to generate an API Key for accessing the data of an instance of the PI version 1 software.

To learn about PI version 2 software’s API Key features, see: Managing Open API Settings (PI version 2 docs)

Activate API Access

Your organization’s PI instance must have API Access turned on before any API Key you generate will work. Contact Predictive Index Support and ask them “Please ensure that API Access is turned on for our PI instance named _____”.

As of the time of this writing, API Access activation process and the use of the PI API does not currently cost anything extra for existing PI customers.

Where to Generate API Keys

API Keys are generated in the PI Software’s Administration > User Management area.

This administrative action can be taken only by PI Users with the role of Account Admin or Account Owner.

How to Generate an API Key

Refer to the PI Support site for general guidance on how to generate an API Key: Integration Guide > Generate an API Key.

Or you can follow this example:

Example – API Key for user named Data Manager

Steps to take if you decide to create a new user named “Data Manager” to own an API Key for use with MagicTools or an API Integration:

  1. Log into PI (https://app.predictiveindex.com) as an Account Admin or Account Owner user with whatever email and password you normally use.
  2. Go to Administration (on the menu seen when you click your name in the upper right corner).
  3. In User Management, click “Create New User”.
  4. Give the user the following details:
    1. First Name: Data
    2. Last Name: Manager
    3. Email: data.manager@yourdomain.com
      1. Note: no two users in the entire PI system can have the same email address
      2. Use a real email address if the user you are creating will need to log into the PI software directly
      3. Invent any fake email address if the user will not log into the PI software — as long as the email has not been used previously in the PI system and this user will only ever use the API Key to access PI data.
    4. Job Title: (optional)
      1. When using MagicTools: MagicTools Connection
      2. When using an API Integration: Integration with XYZ (the name of the system you are integrating with)
    5. Default Folder:
      1. When using MagicTools: \Your Company (type the backslash and then choose the first item shown in the suggestion list).
      2. When using an API Integration: choose a default folder into which new assessments/users will be created by the integration. If the integration will specify a folder, this is not as important. But if the integration doesn’t specify a folder, this is an important decision.
    6. Role: Account Admin – this elevated role allows the API Key to do things like archive unwanted data and move people to new folders.  
  5. Click “Create User” – you will be taken back to the list of all users.
  6. Click on the name of this new user in the list of users so you can view/edit the user details again.
  7. At the bottom, you will see a new “API Key” field that wasn’t there before you created the user.
  8. Click the “Generate New Key” button. 
  9. Click the little icon next to the API Key field to copy the new API Key to the clipboard.
  10. Paste the API Key into a document and save it to a secure location. Remember: an API Key is a powerful thing — guard it!
  11. Click “Save Changes” if you made any changes other than generating the API Key. Click “Cancel” if the Save Changes button is disabled — newly generated API Keys are automatically saved when you click Generate, so there is no need to click Save Changes if generating an API Key is the only action you are taking.

Granting Cognitive Assessment Access

If your organization uses the PI Cognitive Assessment, be sure to read this section.

Because the Cognitive Assessment is considered sensitive personal information, access to results is usually limited to a small group of hiring team members. If the API Key you are generating will be used by a system or tool (such as MagicTools for PI) that needs to access Cognitive Assessment data, that permission must be granted by someone with “Account Owner” permissions. A user with “Account Admin” access does not have the ability to grant permission. Therefore, be sure to contact a user with “Account Owner” access to have them activate Cognitive Access for the user you created as the owner of the API Key. While editing a user’s profile/details, Account Owner users will see a checkbox that grants access to Cognitive data.

Testing an API Key

It is always best to test your new API Key before sharing it or using it. Learn how to do this here: PI API Key Testing and Troubleshooting

Sharing an API Key with others

Because API Keys grant powerful access to semi-sensitive information, take precautions to protect them. Some choices:

  • Use a temporary encrypted sharing tool like the one offered by Believable Magic: Securely Share Sensitive Content
  • Save the API Key in a document that is stored in a shared location accessible only to you and the intended recipient

Generating a new API Key

If you have already created an API Key for a user and then use the “Generate New Key” button to generate a new API Key, the previously generated API Key will be deactivated immediately. Any integration or other data access function that was previously configured to use the old API Key will be disabled by this action. Generating a new API Key is necessary when you wish to disable access by people who might possess a current API Key and ensure that only the new API Key is usable. Be sure to immediately share the new API Key with whoever controls the configuration of any integration that relies on that Key!