# 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 > > ```json > { > "applicant": { > "account_id": "", > "account_option": "", > "applicant_id": "", > "applicant_name": "", > "applicant_email": "" > } > } > ``` > > 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](mailto: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: 1. 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 ```json { "redirect_url": "https://partner.com/fountain_webhook/applicant/9db8d204-7260-450c-acff-ab8122ae776c" } ``` 2. In your iframed page, which is the URL you provide in the previous step, you will need to add the following header: Text ```text Content-Security-Policy => "frame-ancestors https://*.fountain.com" ``` 3. When the previous steps are complete, [contact the Fountain team](mailto:partners@fountain.com) 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 ```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](https://partners.fountain.com/reference/put_v1-partners-id). 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](https://support.fountain.com/hc/en-us/articles/360041692871--Applicant-Status-Labels-with-Quick-Actions). | 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 ```json { "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 ```json { "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](mailto: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.