Applicant Lifecycle

Summary

During the hiring process, applicants will reach your Partner Stage and your service will process their information before posting the results back to Fountain via the Partners API.

Applicant Land

Fountain's users control how an applicant will move through their hiring funnels using workflow stages. Each stage has a different purpose, from collecting contact information, uploading a file, initiating a background check, or scheduling an in-person interview.

When an applicant lands on a stage, Fountain will complete a pre-defined action before advancing the applicant to the next stage. When the stage an applicant lands on is your Partner stage, Fountain will notify you via the webhook URL you provided when setting up the Partner integration.

Calling applicant_webhook

Fountain will send a POST request to the URL configured in your integration. The POST request will contain the following Applicant data:

JSON
{
  "applicant": {
    "account_id": "<String>",
    "account_option": "<String>",
    "applicant_id": "<String>",
    "applicant_name": "<String>",
    "applicant_email": "<String>"
  }
}
Fountain expects to receive a 2XX Success HTTP response code.

Schema

Account ID: Unique identifier for the customer's Fountain account
Account Option: ID representing the selected service package through which the applicant is being processed
Applicant ID: Unique identifier for the job applicant
Applicant Name: Full name submitted by the job applicant
Applicant Email: Email address submitted by the job applicant

Receiving Additional Applicant Data in Applicant Webhook

It's possible you need more information about an Applicant than the default fields listed above.

For applicant data that has already been collected during the application process (e.g., from a Data Collection stage), the data can be whitelisted and delivered in the applicant_webhook payload. This must be configured manually by Fountain and can be requested by sending an email to partners@fountain.com. Include the list of Applicant attributes you need as well as the key you would like to receive for each attribute.

For example, if you need to collect the date an applicant was hired, you can ask for "Hire Date" with a key hired_at. In this example, the JSON payload for 'applicant' would include an additional key-value pair: `'hired_at': ''.

For applicant data that has not already been collected in the application process, we recommend adding or modifying a Data Collection stage in the customer's Fountain workflow to collect the required information. If this is not possible or the application process requires more complicated data collection than Fountain supports, you may want to collect Applicant data directly from your site. In this case, you can display your site in an iframe within the Fountain workflow.

I-Frame Experience

To enable an iframe within the Fountain workflow, there are three steps:

Include redirect_url in the response JSON to the applicant_land webhook. This is the URL used in the src attribute of the iframe. The Applicant will see the URL you provided in an iframe. When you have finished collecting information from the applicant, update the Applicant's status. Fountain will automatically advance the applicant to the next step when we receive the status update. This URL can be unique to the individual applicant record as shown in the example below.

JSON

{
     "redirect_url": "https://partner.com/fountain_webhook/applicant/9db8d204-7260-450c-acff-ab8122ae776c"
}

In your iframed page, which is the URL you provide in the previous step, you will need to add the following header:

Text

Content-Security-Policy => "frame-ancestors https://*.fountain.com"

When the previous steps are complete, contact the Fountain team to enable the iframe experience for partner site.

Verifying Webhooks

To verify webhook requests, generate a HMAC-SHA256 hexdigest of the request body using your Fountain Partner API Key (Private API Key) as a secret, then compare it with the hexdigest we send in the request header X-FOUNTAIN-PARTNER-SIGNATURE.

For GET requests that don't have a request body, we hash the entire URL instead and the query_id in the settings_webhook request ensures the request is unique.

Ruby

def verify_signature(body)
  signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, YOUR_PARTNER_API_TOKEN, body)
  Rack::Utils.secure_compare(signature, request.headers['X-FOUNTAIN-PARTNER-SIGNATURE'])
end

If you prefer to set your own HMAC key, you also have the option to set partner_hmac_key to your desired HMAC key using the PUT Update Partner endpoint. If you do so, we will send X-FOUNTAIN-PARTNER-SIGNATURE-V2 instead of X-FOUNTAIN-PARTNER-SIGNATURE and sign it with your provided custom key.

Partner Status

Partner Status is how Fountain users know the status of the work your service is doing on the applicants. For example, if your service is verifying an applicant's identity, you could return status such as "In Progress" or "Complete". When the users see your status, they will see them with your Partner program namespace. For example, If your namespace was "Real People", the Fountain user will see "Real People: Complete" on an applicant verified through your service in Fountain.

Partner Status Types

There are 6 types of statuses available for partners to send back to Fountain. Using different combinations of the Partner Status fields status (determines visual design of status label) and title (customize text within status label), partners have the flexibility to create as many different status labels as needed!

Below is our recommended usage for each status type, but there is flexibility depending on the specific Partner Service. For additional information and visual examples, please visit this Help Center article on status labels in Fountain.

Status Type	Recommended Usage	Examples
incomplete	For applicants that have landed on your Partner Stage, but haven't started or completed any required tasks.
yellow w/ 1/2 full icon	Applicant has started, but not yet finished, inputting their employment history.
in_progress	For applicants that your service has started but not yet completed processing.
Useful if applicants need to continue further in the hiring process before your Partner Service has finished.
purple w/ loading spinner	Applicant has finished inputing personal information for a background check, but it has not concluded yet.
pending_action	For signaling a Fountain user that additional action or input is required from them before the applicant can proceed.
blue w/ no icon	A document requires a Fountain user's countersignature.
completed	Your Partner Service has completed and the result is a positive or expected outcome.
green w/ check mark	Applicant has passed a background check or received passing score for an assessment.
error	Partner Service could not complete due to an error OR Partner Service has completed and the result is a negative or unexpected outcome.
* We highly recommend that you take advantage of the `title` field to provide meaningful and unambiguous error messages for our Fountain users.

Background check was cancelled.

| waiting | Partner Service has started but progress has halted due to other reason; not pending an action nor processing.

purple w/ loading spinner | Any significant dependency outage, Customer or Partner determination for handling a special case, or other issue that interrupts progress |

Partner Status Schema

{
  "applicant": {
    "partner_status": {
      "title": "Order Cancelled",
      "status": "Error",
      "account_option": "service_1",
      "link_title": "View Report",
      "url": "www.linktoreport.com"
    }
  }
}

Title: Customizable, descriptive text that will be displayed.
Status: Status type will determine the visual design of the status label for a Partner's service (one of ["Incomplete", "In Progress", "Pending Action", "Completed", or "Error"])
Account Option: ID of the selected service package or Partner Stage Option for the applicant
Link_Title: Description text for the link pointing to the URL
URL: URL related to the status (e.g., page to take action for "Pending Action")

Partner Details

Partner Details are useful for adding additional information to applicants that have used your service. Details can be viewed by clicking on the status applied to an applicant either on the Applicant Table or in the applicant's profile.

Partner Status is required. Partner Details are optional.

Partner Status must be configured before your integration is complete. Partner Details are not required for your integration, but they should only be sent after Partner Status is correctly configured.

Partner Detail Schema

{
  "applicant": {
    "partner_details": {
      "key": "date_of_issue",
      "value": "2000-01-01",
      "label": "Date Issued",
      "category": "string",
      "account_option": "service_1"
    }
  }
}

Key: Unique key for the applicant detail
Value: Value of the applicant detail
Label: Descriptive text that will be displayed for this detail (instead of key)
Category: Type of data stored in the value. Must be one of [string (default), date, percent, url]
Account Option: Selected service package or Partner Stage Option for the applicant

Note about Partner Labels

Fountain still supports the use of legacy Partner Labels for existing partners, but we highly recommend all new partners use only Partner Status and Partner Details for sending data back to Fountain.

Please contact partners@fountain.com for any questions about switching to Partner Status or concerns about future deprecation of Partner Labels.

Finished Processing

When you are done posting the results of your Partner Service to Fountain, the next action for the applicant depends on how the Fountain user has configured their hiring funnel.

Partner Status and Partner Details are used within Fountain workflow rules to automate actions on Applicants depending on the results of your work. Various automated action rules can be found throughout Fountain's workflow stages, but the most relevant examples for you will be Fountain's Partner Stages, Custom Stages, and Rule Stages.