Skip to main content
Top
Español Français

Key Predict API

  • Updated

    How to activate the API?

    Follow the steps below to activate and configure the Key Predict API integration, in order to connect your tool and automate assessment triggering and results retrieval.

    ⚠️ Important: only account administrators have the rights required to configure the Integration page.

    1. Activate API access

    To use the API, the Webservice option must be activated on your account.

    • You can submit a request from: Account management > Contracts > Options > "Request activation"

    👉 You can also contact your account manager or Key Predict support to activate the option. The Webservice option is a paid feature.

    • Once the option is available on your account, you can activate it from Account management > Integrations. In the list of available integrations, select Key Predict, then click Activate.

    2. Define your integration credentials

    During configuration, you must enter:

    • API Login
    • API Password (minimum 12 characters recommended)

    👉 These credentials are used to secure exchanges between Key Predict and your tool and to authenticate calls and notifications. They can be defined freely or provided by your tool.

    3. Configure notification URLs

    You can enter (optional fields):

    • Webservice URL – Assessment started: Webhook URL used to send a notification when a candidate starts an assessment (see section 10 of the API – Notification on assessment started).
    • Webservice URL – Assessment completed: Webhook URL used to send a notification when a candidate completes an assessment (see section 9 of the API – Notification on assessment completed).
    • Token expiration: when this option is activated, the authentication token expires after 3 days to strengthen security.

    These URLs correspond to your tool's endpoints that will automatically receive event notifications.

    They must be :

    • provided by your technical team or your tool
    • able to receive HTTP requests (webhooks)

    If you do not have these URLs, contact your technical team or your service provider.

    🔒Note on token expiration

    This is an advanced security option – If expiration is activated:

    • the token becomes temporary
    • it must be automatically renewed by your system

    This option is recommended only if you have the technical resources to manage automatic token renewal.

    4. General operation

    Once the integration is configured:

    • Your tool can trigger assessments
    • Key Predict manages test delivery and tracking
    • Two operating modes are available:
      • with notifications (recommended): your tool is automatically notified of events (start, completion)
      • without notifications: your tool can query the API to retrieve information
    • Results can be retrieved and used within your environment

    For more information, see our technical documentation based on the REST (Representational State Transfer) protocol.

     

    5. Use cases

    Our API allows you to integrate Key Predict assessments into an ATS, an HRIS, or any other business application. Below are the most common integration scenarios.

    Use case 1: Create a candidate from your ATS

    This scenario allows you to automatically synchronise a candidate created in your ATS with Key Predict.

    How it works:

    1. When a candidate is created in your ATS, call the create/candidate method.
    2. Submit the candidate's details (last name, first name, email, language, etc.).
    3. Key Predict automatically creates the participant and returns their unique identifier.
    4. Store this identifier in your ATS to use it for subsequent operations.

    Relevant endpoints:

    • create/candidate
    • update/candidate

    Example:

    When a recruiter creates a candidate in their ATS, the candidate is automatically created in Key Predict with no manual intervention.

    Use case 2: Invite a candidate to complete an assessment

    This scenario allows you to send one or more assessments directly from your ATS.

    How it works:

    1. Retrieve the list of assessments available on your account.
    2. Select the questionnaire(s) to send.
    3. Call the candidate/invite method.
    4. Key Predict automatically sends the invitation to the candidate.
    5. The candidate receives an email giving them access to their assessments.

    Relevant endpoints:

    • assessment/list
    • candidate/invite

    Example:

    The recruiter clicks "Invite to complete an assessment" from the candidate profile in their ATS and selects the Profil Pro 2 questionnaire from a dropdown list. The invitation is immediately sent to the candidate without leaving the tool.

    Use case 3: Allow the candidate to start their assessment from your platform

    This scenario allows the candidate to access their assessment directly from your ATS or your candidate portal.

    How it works:

    1. The candidate has received an invitation to complete an assessment.
    2. Your application retrieves the secure assessment session URL generated by Key Predict.
    3. From your candidate portal or your ATS, the user clicks "Start assessment".
    4. Your system automatically redirects the candidate to the Key Predict assessment platform.
    5. Once the assessment is complete, Key Predict can notify your application via the "Assessment Completed" URL.

    Relevant endpoints:

    • Assessment session URL returned at invitation
    • Notification Assessment Completed

    Example:

    From the candidate area of your ATS, a "Start assessment" button allows the candidate to access their questionnaire directly without having to search for the invitation email.

    Use case 4: Retrieve results and display reports in your platform

    This scenario allows you to view assessment results directly from your ATS or your HRIS.

    How it works:

    1. The candidate completes their assessment.
    2. Key Predict sends a notification to your "Assessment Completed" URL.
    3. Your system automatically retrieves the available results.
    4. PDF or HTML reports can be downloaded or displayed directly in your platform.
    5. Recruiters or managers can view results without needing to log in to Key Predict.

    Relevant endpoints:

    • assessment/completed
    • assessment/result

    Example:

    When a candidate completes their Profil Pro 2, a "View report" button automatically appears in the recruiter's candidate profile, allowing them to view results directly from their ATS.

    Use case 5: Compare candidates using fit scores

    This scenario allows you to automate the calculation of candidate fit scores relative to a position or a project.


    How it works:

    1. Create an assessment campaign via the API by defining:
      • the assessments to use,
      • the predictive model associated with the position or the project,
    2. Link the campaign to a stage of your job posting or your project in your ATS.
    3. When a candidate reaches this stage, your ATS automatically triggers their enrolment in the campaign and sends the assessments.
    4. Once the assessments are completed, Key Predict automatically calculates the fit scores based on the predictive model associated with the campaign.
    5. Your ATS retrieves the scores via the API and can display them in the candidate profile or in the applications list.

    Relevant endpoints:

    Example:

    You create a "Senior Sales" campaign linked to a predictive model. When a candidate reaches the "Assessment" stage in your ATS, the tests are sent automatically. Once the results are available, the fit score is calculated and displayed directly in your recruitment pipeline to facilitate candidate comparison.

    Use case 6: Retrieve the Insight profile and Talent Map

    This scenario allows you to display in your ATS or your HRIS a secure link to the Key Predict participant profile. From this profile, recruiters or HR teams can view the participant's Insight and their Talent Map, depending on the features activated on the account.

    How it works:

    1. The candidate or employee completes the required assessments.
    2. Once the results are available, your system retrieves the secure link to the participant profile.
    3. This link is displayed in your ATS or your HRIS, for example from the candidate or employee profile.
    4. By clicking this link, the user accesses the Key Predict participant profile, which centralises the available results: Insight, detailed reports, Talent Map.
    5. Recruiters, managers, or HR teams can view this information without having to search for the participant manually in Key Predict.

    Relevant endpoints:

    Example:

    The recruiter views the BF5 or Profil Pro report directly from their ATS without needing to open another application.