Integration guide

The term “integration” describes a tool that allows two software systems to automatically exchange data. The Predictive Index (PI) is most frequently integrated with Applicant Tracking Systems (ATS), Human Resources Information Systems (HRIS), or other business software systems to enhance a hiring process or to allow employees to work together better. 

For example, a typical automated ATS integration includes assessing applicants when they reach a certain stage by sending an email invitation or linking them directly to an assessment, and then using an automated process to place PI results directly into the ATS system. The goal of any integration is to make the use of PI more convenient, efficient, and consistent. 

Current Integration Strategies

The Predictive Index currently provides two general strategies for integrating the PI platform with other software:

  • API Integration: automated bridge between two systems using an Application Program Interface (API)
  • Invitation Link: using PI software features to create specialized links and putting these into email or website content

API Integration

PI has built an Open Application Program Interface (API) for its clients to use to connect with other software. An Open API allows clients to build a bridge between systems to access PI data and features from within that other software application. Using an API always requires some programming, but that work can be done by client technology teams, software vendors, or third-party integration service providers. For many software systems, the “bridge” has already been built by a software vendor or a third-party service providers.

The Integration Catalog is a great place to check whether your software system already has an integration available

If you see anything in the resources above that interests you or wish to pursue an integration between PI and other software, ask your PI Consultant to put you in touch with the PI Integration Team, or contact them directly with this form.

PI software offers features that enable clients to create specialized links that take people directly to an assessment, storing results wherever the client decides at the time the link is defined. These are called “Invitation Links” because anyone with the link can follow it, enter their name and email, and take the assessment without previous permission or invitation. Invitation Links can be general in nature or they can be uniquely associated with specific Jobs defined within the PI software. These links have also been called “Open Invitation Links” and abbreviated “OI Links”.

If you have any questions about integrations between PI and other software, ask your PI Consultant to put you in touch with the PI Integration Team, or contact them directly with this form.

API Integration Guide

This section will provide an overview of decisions, process, and resources involved with building an integration between PI software and other systems using our Application Programming Interface (API). Congratulations on taking the first step in determining whether an API Integration is right for your organization!

Integration Key Concepts

The term “integration” describes a technical configuration that allows some amount of automated exchange of data between two systems. In the case of Predictive Index, an integration usually involves connecting to an Applicant Tracking System (ATS), a Human Resources Information System (HRIS), or another business software system.

The Predictive Index provides an Open Application Program Interface (API) for its clients. An Open API allows clients to access data and features that are available within the PI software and bridge them into another software application. Accessing an API always involves some programming, but for some target software systems that programming work has been done already.

When a hiring system is integrated using our API, it usually includes:

  • an automated strategy for sending assessment invitations or directly linking to assessments
  • followed by some automated placement of assessment results into the target system
  • usually including a link from the target system back into the PI software

A typical Applicant Tracking System API integration process flow:

Integration Process Overview

The integration process should be personalized based on your ATS, business goals, and technical resources. We’ve outlined four general steps to help get you started.

Determine the Applicant Tracking System

To get started, determine what Applicant Tracking System (ATS) or Human Resources Information System (HRIS) you are using. The Predictive Index can be integrated with most ATS/HRIS platforms that offer supportive features or with custom software systems.

Our Integration Catalog provides information about the types of integrations with PI that are available for many ATS, HRIS or other software systems. Whether you see your ATS/HRIS system in this list or not, you will need to contact the vendor of your system and learn what steps are required to begin an integration project. Each vendor has their own requirements, possibly including some of these:

  • Request that integration support be turned on or installed
  • Request a test/sandbox/staging instance of your software for use in preparing an integration
  • Request access to the technical documentation to be used during setup/configuration
  • Pay a one-time and/or ongoing integration fee to your ATS/HRIS vendor (some integrations are free)
  • Contract with vendor’s Professional Services team to configure and test

Once you have learned about the ATS/HRIS vendor’s process, you will have a better idea about what kind of integration is possible and whether there are vendor-related costs. 

Determine your Goals

Work with your PI Consultant to determine the overall goals for the integration, including what type of features you may want displayed in your system.

Integrations often add many of the following functional features to your ATS/HRIS

  • Assign PI assessments to candidates or employees—behavioral, cognitive, or both.
  • Include assessments directly within the job application process as a link or inside an inline frame. **
  • Generate email messages inviting people to take PI assessments. **
  • Associate a job opening in the ATS/HRIS with a specific job target defined within PI software.
  • Detect and display assessment completion status.
  • Display assessment results (e.g. cognitive score or behavioral pattern image or behavioral reference pattern name).
  • Store PDF report files directly in a candidate or employee record (e.g. Behavioral Report, Interview Guide).
  • Display a link to the PI software person detail page.
  • Display a PI Match Score for candidates associated with a PI job target.
  • Associate PI results with employees for ongoing use after hiring.
  • Initiate other PI software functions.
  • Display other PI software results or data.

Items in the list above marked with a double asterisk (**) are integration goals that can be achieved using only an Open Invitation Link or “Invite by Link”, an included feature of the PI Software Assessment Center. For example, you can place an Open Invitation Link into an application page or follow-up email. Such a strategy may be the most sensible integration approach for an organization with infrequent hiring. The effort and cost required to build a more complex integration may be too much for such an organization. If your goals can be met using only an Open Invitation Link, your investigation may end here. See Send a behavioral and cognitive assessment for more information.

API Integration Goals

For most of the sample goals listed above, however, it is necessary to build an automated integration using the Predictive Index Open API and the customization and integration features of the ATS/HRIS. Such an integration requires that someone set up a go-between process, sometimes called “middleware”, that can bridge between the two systems. When the ATS/HRIS software signals for an action to occur, the integration process translates that into commands that the Predictive Index API understands. And when results are ready in the Predictive Index system, the PI system sends a signal to the integration process which then takes the PI data and puts it into the correct places in the ATS/HRIS. Some ATS vendors have already built an API integration directly into their product, while other ATS systems require the go-between/middleware process.

The Predictive Index provides two types of information about its Open API:

Swagger Page

It is important to note that the Predictive Index Open API will only function for a given organization if the following are true:

  • API Access has been activated for the PI client account. Clients may request API Access to be turned on by contacting the Integrations Team.
  • An API Key has been generated which is required for authentication to the Open API. Clients can do this themselves. 

Determine your Integration Resource

If your ATS vendor does not supply a pre-built integration with PI, it is up to your organization to determine who will do the work of creating an integration. 

The Predictive Index provides access to PI data using our Open API, but it does NOT perform or provide the actual integrations. Your organization is responsible for any costs associated with integrating your PI data with another software system. 

There are currently 3 available options:

  • Learn whether your ATS provider offers a professional services team to help with the integration.
  • Use an internal resource within your own organization to understand project scope and to build the integration.
  • Contract with a third-party integration solution provider of your choosing or use one recommended by The Predictive Index. This strategy usually involves a separate contract between your organization and the solution provider as well as set-up and recurring fees.

If you would like suggestions from The Predictive Index regarding possible third-party integration solution providers, please look at the bottom of the Integration Catalog or a list of providers or contact the Integrations Team with this form.

Legacy Integration Note: In the past, The Predictive Index provided several integrations with selected ATS/HRIS systems. However, changes in the PI software, emerging client needs, and the ever-changing landscape of ATS/HRIS software systems have made it impractical for PI to continue providing integrations ourselves. Any remaining legacy integrations will be eventually phased out and no new legacy integrations will be configured.

Begin Integrating

Once you’ve identified your ATS requirements, integration goals, and technical resource, work with your ATS contact, The Predictive Index, and your technical resource to begin building the integration.

The project will probably include many of the following tasks:

  • Ensure that the right internal resources are available for meetings in which options are evaluated and decisions are made
  • Determine what display name, email address, and phone will be used as the default contact for auto-generated email messages
  • Generate an “API Key” for Production and possible Sandbox accounts, including the above default contact details
  • Sign up one or several technical contacts on the The Predictive Index Status site that is used to notify clients and developers about future updates or alerts regarding changes or issues with the API
  • Arrange any required fees/contracts
  • Activate integration features if required
  • Assign integration project manager
  • Identify test account credentials
  • Activate API Access in the Predictive Index platform – can be requested by a client or their consultant – this may already be activated for your account
  • Optionally arrange a “Sandbox” account for developing and testing the integration
  • Answer questions that developers who are actually building the integration may have
  • Identify requirements – will a “standard” integration be used or will additional customization be needed?
  • Arrange a contract and payment terms
  • Assign a Project Manager and technical resource(s)
  • Schedule and manage the integration using the PI Sandbox account and ATS testing account
  • After testing, implement same integration in production systems
  • Provide ongoing maintenance and support
  • Sign up one or several technical contacts on the The Predictive Index Status site that is used to notify clients and developers about future updates or alerts regarding changes or issues with the API

Helpful Resources

  • Contact PI Integrations Team: If you have any questions or requests related to integrations, use this form
  • API Reference Site: Detailed technical reference of the API based directly on production software, along with testing features built into the page
  • Integration Catalog: list of known integrations between PI and other software, including a list of integration solution providers
  • PI Status Notification Website:  Subscribe to one or several areas of concern to receive notifications about future updates or changes or issues with the API or the PI platform in general

Software Features in the API

If you are thinking about connecting Predictive Index actions and results with other software systems using our API, you are probably wondering which PI features are accessible outside of the PI Software itself. The text below will attempt to answer that question.

Note: The details below are accurate as of the publishing date. We continually expand the API, however, so if you are looking for a feature that is not found here, please contact us with this form.

  • Create BA or CA and new Person
  • Create BA or CA for existing Person
  • Obtain BA or CA survey link for specific person – to be shown in a web page or sent via custom email
  • Send BA or CA invitation via email directly to Person; control the email subject and intro text
  • Change BA expiration date
  • Re-send BA invite with new expiration date, email subject and body
  • Automatically send CA invitation to the same person upon completion of an assigned BA
  • Associate external identifier with BA or CA and/or with Person
  • Control the name, email, and phone of the BA or CA administrator
  • Assign a Person to a Job (by Title or by Id)
  • Designate Person Type (Candidate, Employee, Other)
  • Assign a Person to a Folder (by Path or by Id)
  • Redirect user’s browser upon completion of BA
  • Notify assessment taker via email upon completion of assessment
  • Notify administrator via email upon completion of assessment
  • Notify a system upon completion of assessment — using per-assessment or general setting assessment status webhook
  • Behavioral Report – send via email or download
  • Behavioral Pattern Graph Images – all or self-only as PNG or SVG
  • Person Snapshot – send via email or download
  • Interview Guide (Job Target-specific) – send via email or download
  • Placard – send via email or download
  • Personal Development Chart – send via email or download
  • Manager Development Chart – send via email or download
  • Management Strategy Guide – send via email or download
  • Coaching Guide (Job Target-specific) – send via email or download
  • Cognitive Report – send via email or download
  • Cognitive Result Images – download as PNG or SVG
  • All Jobs
  • Job Details for a single Job
  • Persons associated with a Job
  • Persons matching a Job Target
  • Job Target Profile Report – send via email or download
  • Update Job details
  • Link to Person Page in PI Software
  • Find People by email, external ID, name, assessment status
  • Update Person details
  • Create or Update people and organizational hierarchy information via CSV file

Generate an API Key

An application programming interface key is a unique string of alphanumeric characters transmitted as part of an API request that authenticate the source of the API request.

If using integrations with the PI software, you can generate the API key for the admin that will be receiving all email notifications and will be listed as the administrator on each assessment.

This guide will walk you through how to generate the API Key for a user.

1. Navigate to the Administration section and click on the User Management tab.

2. Click on the name of the user you would like to generate an API Key for.

Note: You can only have 1 API Key active at a time, so if you already have one, generating a new one will deactivate the previously active one.

3. Under the Permissions section, click Generate New Key. You can then copy the key from the software.

Hit save changes at the bottom before closing out.

To inform us of a typo or other error, click here. To request a new feature, click here.