How can we help you?

First Advantage

First Advantage is the largest global Screening Provider offering comprehensive background screening solutions that provide employers and housing providers straightforward, actionable reports so they can make confident choices, reduce risk, and stay compliant.
Greenhouse Recruiting's integration with First Advantage (FADV) enables Greenhouse Users to access FADV screening services from Greenhouse by providing the following functionalities:

  • Initiate FADV Screening request
  • Track real-time Screening orders status
  • Access via links to view detailed Screening report.


In this article, we will cover how to:

  • Configure User Setup Permissions in Greenhouse Recruiting
  • Create a Harvest API Key for the Greenhouse/First Advantage (FADV) Integration
  • Configure Webhook with First Advantage (FADV) Endpoint URL
  • Enable Greenhouse/ First Advantage (FADV) Integration by adding Company Custom Field Options for Jobs and Candidates
  • Invoke First Advantage Screening by moving candidates to Background Check Stage
  • View First Advantage Background Screening Status and Results in Greenhouse

 

Greenhouse Configuration

Configure User Setup Permissions in Greenhouse Recruiting

In order to enable the Greenhouse/First Advantage (FADV) integration, you will need a new User XCHANGE with the developer permission Can manage ALL organization's API Credentials and Can manage and configure webhooks
Contact a Greenhouse user in your organization with
Site Admin level permissions with the additional user-specific permission Can edit another user's advanced permissions to apply the API credential management permission to your account. Have the user with Site Admin level permissions edit your user account's permissions by navigating to the Configure icon   > Users > Your Name)


The user with Site Admin level permissions should navigate to the
Permissions panel on your user page and expand the Developer Permissions dropdown menu. 
Select
Can manage ALL organization's API Credentials so that a check is in the checkbox. When finished, click Save.



Repeat as necessary for any other user that should have access to set up the integration.

 

Create a Harvest API Key for the Greenhouse/First Advantage (FADV) Integration

To create a Harvest API key for the integration, click on the Configure icon   in the upper right-hand corner. Navigate to Dev Center on the left-hand panel.
From the Dev Center page, click API Credential Management.


From the API Credential Management page, click Create New API Key to generate the API key for First Advantage (FADV).

From the Create new credential dialog box, give your API key a name (FADV API Key) and select Harvest from the Type dropdown menu. When finished, click Create. 

On the Manage API Key Permissions page, Please select the following:

  • Candidates
  • Custom Field Options
  • Custom Fields
  • Custom Locations
  • Demographic Data
  • Departments
  • EEOCEducation
  • Job Stages
  • Jobs
  • Offices
  • Tags

When finished, click Update 

Your Harvest API key for the Greenhouse/First Advantage (FADV) integration is created and configured. Provide your Harvest API key to your First Advantage (FADV) onboarding team so they can set up the integration. Using Harvest API key – Accounts, and Package will be auto-populated


Create a Web Hook for the Greenhouse/First Advantage (FADV) Integration

From the Dev Center page, click Web Hooks. Click Web Hooks from the subsequent page.

You will be directed to a new page where you
Create a New Web Hook. From this page provide the following details:

  • Name: we suggest FADV Screening Webhook
  • When: Select Candidate has changed Stage
  • Endpoint URL:

For Test: https://apicdntest.fadv.com/greenhouse/order
For Prod:
https://apicdn.fadv.com/greenhouse/order

  • Secret Key: The Secret Key is Optional
  • Advanced Settings: Make sure to add Company: <Name of your Company> in Additional HTTP Headers section


When finished, click
Create Web hook.


That's it! Your Greenhouse account and First Advantage (FADV) account can now talk to each other.

Add Offices and Departments to use with the First Advantage (FADV) Integration with Greenhouse


Adding a new Office in Greenhouse requires Country, State and City. It can then be associated to any Job Req1uistion. First Advantage (FADV) will use the Office County, State and City in determining Position Location which in turn is used by FADV for Adverse Action communication among other things.
To create a Office for the integration, click on the Configure icon   in the upper right-hand corner. Navigate to Organization on the left-hand panel. 
From the Organization page, click Offices > + New Office Button
In
Create New Offices Menu, Enter Name for Office and select Location and Create 

 

Add Job Related Custom Fields for First Advantage (FADV) Integration with Greenhouse

For First Advantage (FADV) Integration with Greenhouse needs creation of 2 Jobs Company Custom Fields:

  • FADV_Account – First Advantage Account

  • FADV_Package – First Advantage Package

These 2 fields needs to be configured for each Job Requisition – so that FADV can screen the candidate as needed
To create Jobs Custom field for the integration, click on the Configure icon   in the upper right-hand corner. Navigate to Custom Options on the left-hand panel. 
In the Custom Options Page, click Jobs under Company Custom Fields
In Manage Job Fields Page, click on +Add Field
Enter Field as FADV_Account and Type as Single Select. 
Make sure to select Expose in Job Board API option. Hit Save.


Now repeat the same steps for
FADV_Package – just change the Field name. Type is Single Select and Expose in Job Board API should be selected.


Add Candidate Related Company Custom Fields for First Advantage (FADV) Integration with Greenhouse


For
First Advantage (FADV) Integration with Greenhouse needs creation of 4 Candidates Company Custom Fields:

  • FADV_Status – to display FADV Screening Results and Status in real-time
  • FADV_URL – to display the URL that will take the user to FADV detailed Screening Results
  • FADV_Last_Update – Last Update Timestamp
  • FADV_History – Previous results in case there are multiple Screenings


To create Candidates Custom field for the integration, click on the Configure icon   in the upper right-hand corner. Navigate to Custom Options on the left-hand panel. 
In the Custom Options Page, click Candidates under Company Custom Fields
In Manage Candidates Fields Page, click on +Add Field
Enter Field as FADV_Status and Type as Long textbox. 

Repeat same steps as before for
FADV_URL however the field name is FADV_URL and Type is URL



Repeat same steps as before for
FADV_Last_Update however the field name is FADV_Last_Update and Type is Short Textbox

Repeat same steps as before for
FADV_History however the field name is FADV_History and Type is Long Textbox


How to use the First Advantage (FADV) Integration with Greenhouse

Job Requisition Setup

To use First Advantage (FADV) Integration with Greenhouse first step is to configure the Job with appropriate FADV options 
This requires selection of
Office, FADV_Account and FADV_Package from Job Info Page under Job Setup Tab. Note Office, FADV_Account and FADV_Package are required for every Job the client intends to submit candidates for Background Screening

 

Initiate Background Screening

Now with all the setup to initiate First Advantage (FADV) Background Screening with in Greenhouse – the user just has to move the Candidate to Background Check Stage

Candidate will get an email Invite from FADV to complete their FADV Profile for Screening which includes consent and authorization steps.
Once Candidate Completes their FADV Profile – FADV automatically updates Candidate Custom Fields like FADV_Status, FADV_URL and FADV_Last_Update.
For detailed FADV Workflow and Screenshots please see the Appendix.


Need help?


Add any FAQ's regarding implementation pricing, common errors, etc. 
Please contact
integrationsupport@fadv.com for troubleshooting assistance regarding the integration.


Appendix

Greenhouse Configuration and Workflow


Greenhouse Configuration – Harvest API – so that FADV can read/write Greenhouse data


Greenhouse Configuration – Webhook – so that Greenhouse can notify FADV when there's a candidate ready for Screening



Greenhouse Configuration – Offices – For Position Location



Greenhouse Configuration – Company Custom Fields: Jobs



Greenhouse Configuration – Company Custom Fields: Candidates




Greenhouse Configuration – Job Info – Select Office, FADV_Account, FADV_Package – so that FADV can aptly handle the Screening Request

 


Greenhouse – FADV Workflow








Recruiter Experience – In Greenhouse – The recruiter moves the candidate to "Background Check" stage to start the Screening



Recruiter Experience – In Greenhouse – The recruiter can check the status of the Screening Request


Candidate Experience – Meanwhile candidate receives a FADV email to complete their Profile



Candidate Experience – they configure their Password


Candidate Experience – candidate provides consent for Screening and review auto-populated Information


Candidate Experience – Once they complete their Profile – they will be able to track progress of Screening Request and Results


Recruiter Experience – The Recruiter can track Screening Status Results in real-time in Greenhouse. Also by clicking the FADV_URL they can see detailed Screening Results


Recruiter Experience – The Recruiter needs to enter their FADV credentials to see detailed Screening Results after they click FADV_URL



Recruiter Experience – The Detailed Screening Results Report can be printed/downloaded and can be used for additional steps like Adjudication

Common Errors and Error Handling

 

Error Code Description Error Handling
E-103 Required value missing or not found in proper format: CandidateInvitations/CandidateInvitation/
ContactMethod/InternetEmailAddress is missing
Candidate email Address is missing and either:
  1. Value is empty or null
  2. Value does not meet format setting
Please reach out to FADV Integration Resource or for possible workarounds if candidate cannot provide email address or if client does NOT want to leverage this particular solution model.
E-103 Required value missing or not found in proper format: CandidateInvitations/CandidateInvitation/
ClientReferences/ClientReference1 is required
Client reference or UDF is required and is either:
  1. Value is empty or null
  2. Value does not meet format setting
  3. Value is not in drop-down list. 
  4. Sometimes FADV might have a set up a list for the client reference fields, so CandidateInvitation API looks for a value in the list.  Ask FADV to turn it off the list.
E-104 Error occurred while processing your request Catch all error…
  1. <Quoteback> has Name instead of name.
  2. <HasSSN> should be Y, N or empty. It can't be any other value say 'true'
  3. <GovernmentId issuingAuthority is one of these enum values SSN, GOVT or PASSPORT >
  4. FADV Customer Preferences NOT setup correctly.
  5. FADV Customer site is NOT configured correctly. Check if Flow is tied to CandidateType in CDC Admin
  6. FADV XChange User NOT setup correctly
  7. FADV "Collect Int'l Data setting" for candidate type is set correctly  (if client sending Has SSN indicator as 'Y'.)
  8. Field value exceeds field size.  (Ex. Degree Name greater than 50 chars).
  9. Verify if all XML <Tags> in your request are valid. We have seen this error when a client sent candidate under <PersonData> instead of expected <PersonalData>
  10. Ensure <CountryCode>US</CountryCode> in <Licenses> and not something like <CountryCode>us</CountryCode>

 


 

FAQ

 

# Notes
FADV Maintenance Window
  • FADV Maintenance begins on Saturday at 6pm EST and ends on Sunday at 7am EST.
  • If FADV Service is down then Requests need to be resubmitted when Service comes back up.
  • If there's unscheduled maintenance and FADV Service is down - then Status Notifications will be queued and sent back to Workday once service is back up.
FADV Support Contact Information For FADV Screening Program Management Concerns please reach out to your FADV Customer Success Manager (CSM).Note If you are managed by FADV CSSB Team – please send an email to CSSB@fadv.comIf its an Integration Specific Issue reach out to integrationsupport@fadv.com - please make sure to copy your CSM or CSSB@fadv.com
FADV URL for Webhook For Customer Test: https://apicdntest.fadv.com/greenhouse/order
For Production: 
https://apicdn.fadv.com/greenhouse/order