How can we help you?

Data Facts




  1. SET UP A USER ACCOUNT – this is the name that shows who made the change on the record.  This name is given to Data Facts on the order and set up sheet
  2. USER ACCOUNT – use a fictitious name needs with minimal authority    
    1. SUGGESTED USER SET UP: FName: Integration  Lname: Background
  1. When API token is used to write into Greenhouse it requires “what user is doing this”  - this is the user account that will show who made the change on a candidate –Numeric ID
  2. USER needs minimal rights it is only to write “who made the change” when results are posted back into Greenhouse


2. Setup Webhook

Create Web Hook

  1. Name - “Background check” or something similar (for assessments integration) or "New Hire Sync" (for hiring integration)
  2. When - set to “Candidate has changed stage” (for most assessments integrations) or “Candidate has been hired” (for hiring integration and for some assessments integration). If you use the changed stage event, we will need to know which specific stage triggers the integration.
  3. Endpoint URL - for Production:  (“Candidate has changed stage”) WILL BE PROVIDED /ApplicantEvent
    NOTE:  Production host is assigned at go-live.  
    The 'N' in apiaN is specifically assigned (apia1,  apia2, etc.) at go-live
  4. Secret Key is the XML username setup for the integration[a][b]
  5. Error recipient email should go to a responsible party from the client, and other parties that need to be notified of Greenhouse errors[c][d]

Best Practice:   DISTRIBUTION LIST for  GO LIVE and a person or two while testing

  1. Disabled - No
  2. Click “Update Web Hook”.
  3. When we need to switch the URL click the pencil icon to open the existing configuration for edit


Click Configure -> Web Hooks -> Web Hooks






3. Create API USER  - OPTIONAL step if client requests assistance setting up use cases and custom fields from Integration team.  This is separate and distinct from normal users

API Credentials.  Email for API User will be   [e][f]



  1. From the previous page. Click “API Credentials” on the left.
  2. Then Click “Create New API Key” at the top.
  3. Description: “Background Integration”, "Hiring integration" or something similar.
  4. Type: “Harvest”
  5. That should take you to the API Key Permissions page. Make sure the below fields are selected. Be sure to copy the API key and keep it handy. It is needed for the developers to access these fields.










4.  Create Custom Fields

  Click Configure -> Custom Options -> Candidate -> Add Field




  1. Field: “Background Package”
  2. Type “single select”
  3. Check Mark Private
  4. Click “save”
  5. Click add field again
  6. Field: “Background Report”
  7. Type “URL”
  8. Check Mark Private
  9. Click Save
  10. Do this next step for each field.
  11. Click the Pencil and copy the “Immutable field Key”. Our developers will need these as well

  1. Using the candidate has been hired option.
  1. Once the hired button has been clicked it will trigger the integration.
    1. Who will notifications be sent to at client or screening company - TBD
  1. Once the integration has been triggered
  1. An email will be sent to the applicant from the screening platform to fill out their authorizations and disclosures and enter their information.
  2. Once they are done and the report is complete updates will be sent back to Greenhouse in the activity feed.
  2. Secret Key cannot be blank put random characters




FIRST CHOOSE THE PACKAGE (important that this be done before moving them to background check stage)


SECOND – after the package is chosen then Navigate to Candidate and move them to the proper Stage  (note that the call out to integration is as SOON as the stage is moved – that is trigger) therefore if the stage id moved before the package is chosen the package is NOT in the web call yet.    If this inadvertently happens then go change the stage backwards. Pick the package and then move them back – it will retrigger.