Most common steps

The following is a detailed walkthrough of the best practices and API methods to be used for an integration in which the behavioral and cognitive assessments are initiated by an external system, usually an Applicant Tracking System (ATS), using an automated email message to candidates and an optional assessment status webhook to signal completion and then transfer results into the ATS.

Creating candidates and sending assessments

The POST /api/v1/candidates endpoint is the recommended method for sending PI assessments. It handles candidate creation or updating, job assignment, and assessment delivery in a single request.

Why use this endpoint:

Serves as the single entry point for all assessment-sending workflows, replacing the need to orchestrate multiple calls across behavioral assessments, cognitive assessments, and candidates endpoints.
Automatically matches on existing candidates by email — no need to search beforehand

How it handles new candidates:

Creates a new candidate record
Associates the candidate with the job specified in the request
Sends the requested Behavioral and/or Cognitive assessments

How it handles existing candidates:

Matches on the email address provided in the request. Duplicate emails are not supported — each email maps to a single candidate record.
When a match is found, the response will include isExistingCandidate: true
Moves the candidate to the new job included in the request
Re-scores fit ratings based on the new job and returns updated values in the response
Resends a Behavioral or Cognitive assessment only if the assessment is still pending
Does not send a new assessment if it has already been completed — check the assessmentState property in the response to determine status

When to use other endpoints:

The individual GET, POST, and PATCH methods on behavioral assessments, cognitive assessments, and candidates are still available for specific operations such as retrieving results, downloading reports, or updating individual candidate properties.

API key management

The API Key that you generated in the PI software must be included in the header of each HTTP request and is defined as follows:

Header	Description	Value
api-key	API Key generated using the instructions shown here.	1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6

Search for an existing employee

The employees GET endpoint exposes an OData endpoint for searching for existing employees by either, email address, PI Person ID, or External Person ID.

Request

GET https://integrations.predictiveindex.com/api/v1/employees/[?PersonId][&Email][&ExternalPersonId]

Parameters

Name	Required	Type	Description
PersonId	False*	string	The Person's unique PI identifier
Email	False*	string	The Person's email
ExternalPersonId	False*	string	The Person's external identifier

*At least one of these values must be provided in the request.

Example request

curl -X GET --header 'Accept: application/json' --header 'api-key: YOUR_APIKEY_GOES_HERE' 'https://integrations.predictiveindex.com/api/v1/employees?PersonId=c98a0aa4-ee48-44a5-a525-f049679b7c3f'

Example response

HTTP/1.1 200 OK

content-type: application/json; charset=utf-8

date: Tue, 07 Oct 2025 14:41:43 GMT

transfer-encoding: chunked

vary: Origin

{
    "totalRecords": 1,
    "recordsReturn": 1,
    "records": [{
        "person": {
            "personId": "d532ffde-63f2-4645-b652-8391a1c9384e",
            "genderDescription": "Not Set",
            "email": "[email protected]",
            "externalPersonId": null,
            "firstName": "John",
            "gender": null,
            "lastName": "Doe",
            "middleName": null
        },
        "job": {
            "description": null,
            "title": "Sales Manager",
            "externalJobId": null,
            "jobId": "4e7b3db7-4c90-4d2a-bd88-18bf8c6eb54f"
        },
        "behavioralAssessment": {
            "behavioralAssessmentId": "e41d4b3b-c849-45a8-9e72-513d3ffcec47",
            "referenceProfileName": "Maverick",
            "assessmentState": 40,
            "assessmentStateDescription": "Completed",
            "assessmentUrl": "https://assessment.predictiveindex.com/v1/fdb56c05-5f79-466b-a67c-a58a60f93300/e41d4b3b-c849-45a8-9e72-513d3ffcec47?type=emailba"
        }
    }]
}

Integration examples