Custom Applicant Validator

Talent Platform allows you to integrate a custom validation service into the applicant’s workflow. When this feature is enabled, the system sends applicant data to an external service after they complete their Preliminary Information.

Based on the results provided by the external service, the system can prevent candidates from moving forward to onboarding if they don’t meet the custom criteria you've set. This ensures that only qualified candidates proceed to the next stage.

External Service Requirements

To integrate an external applicant validation service, the service must meet the following requirements:

• It must accept a POST request.
• Authentication may be required (see the Configuration section for more details).
• The service should expect a request body that follows the format used by the Customer API to retrieve an applicant by their ID.
• The service must return a 200 status code and a response body that follows the structure below:
  
  json
  {
  "status": "Success" | "Failure" | "Error",
  "message": string?
  "data": any?
  }

External Response

The validation process expects a successful 200 response with the following details:

• Status (required): The result of the external validation. Possible values:
  • Success: The applicant can move forward with onboarding.
  • Failure: The applicant did not pass the validation and cannot proceed.
  • Error: There was an issue with the external service.
• Message (optional): A system message that may accompany the status. This message is not shown to the applicant but is visible in the browser’s developer tools.
• Data (optional): Any additional information related to the status. This data is not displayed to the applicant but is also visible in the browser’s developer tools.

Configuration

These steps can be completed by an Administrator user.

Integration Settings

The Custom Applicant (or Candidate or Talent) Customer talent - the person applying or hired for the job Validator can be set up in the Integrations settings page.

To access it, navigate to Configuration > Settings > Integrations > Custom Applicant Validator.

The settings in the table below are available for configuration:

Settings	Required	Description
Validator URL	Always	The full URL of the external applicant validation service. Supports query parameters.
Authentication Type	No	The type of authentication to use for the external validator if authentication is required. Currently supported values: BASIC or APIKEY
Authentication User	When Authentication Type is BASIC	The username to use when BASIC authentication is required by the external service.
Authentication Password	When Authentication Type is BASIC	The password to use when BASIC authentication is required by the external service.
Api Key	When Authentication Type is APIKEY	The password to use when APIKEY authentication is required by the external service. Talent Platform will send this value as an HTTP header.
Api Key Header	When Authentication Type is APIKEY	The HTTP header name to be sent containing the configured Api Key when APIKEY authentication is required by the external service.

Applicant Message Configuration

If an applicant fails the validation or if the external service encounters an issue, a message will appear for the candidate on the Preliminary Information page. These messages can be customized and set for multiple languages by using the Translations feature, which can be found under Configuration > Settings > Translations.

Translation Key	Displayed On	Default Message
applicant_validator_failure	Failure	There was an issue verifying your information, please contact your recruiter.
applicant_validator_error	Error	There was an issue verifying your information, please contact your recruiter.

Candidate Workflows

Workflow Diagram

Successful Validation Workflow

This process describes what happens when an applicant successfully passes validation. The applicant can proceed to their onboarding forms after completing their preliminary information.

Steps:

1. The applicant logs into their profile.
2. They select a task from the Task List List of tasks that have been assigned to the Candidate and need to be completed or begin the onboarding workflow from the Applicant Dashboard.
3. They are taken to the Preliminary Information page.
4. After completing the Preliminary Information, they press Next.
5. In the background, Talent Platform sends the applicant’s details to the custom validation service (Validator URL).
6. The external service returns a successful validation response ({ "status": "Success" }).
7. The system moves the applicant to the Onboarding Forms page.

Failed Validation Workflow

If the applicant fails the validation process, they are unable to proceed to the Onboarding Forms. Instead, they will see a message informing them of the failure.

Steps:

1. The applicant logs into their profile.
2. They select a task from the Task A specific action that needs to be completed by a Candidate (e.g., completing a Form, Package, Credential, Skills Checklist) List or begin the onboarding workflow from the Applicant Dashboard.
3. They are taken to the Preliminary Information page.
4. After completing the Preliminary Information, they press Next.
5. Talent Platform sends the applicant’s details to the custom validation service (Validator URL).
6. The external service returns a failure response ({ "status": "Failure" }).
7. The system keeps the applicant on the Preliminary Information page.
8. The Next button is disabled and grayed out.
9. A message is displayed based on the translation key for validation failure (applicant_validator_failure).

Errored Validation Workflow

If there is an issue with the validation service or an error occurs, the applicant cannot proceed, and a message will inform them that something went wrong.

Steps:

1. The applicant logs into their profile.
2. They select a task from the Task List or begin the onboarding workflow from the Applicant Dashboard.
3. They are taken to the Preliminary Information page.
4. After completing the Preliminary Information, they press Next.
5. Talent Platform sends the applicant’s details to the custom validation service (Validator URL).
6. The external service returns an error response ({ "status": "Error" }).
7. The system keeps the applicant on the Preliminary Information page.
8. The Next button is disabled and grayed out.
9. A message is displayed based on the translation key for validation errors (applicant_validator_error).