Workvisa.io allows your recruiters to request pre-hire immigration assessments directly from Greenhouse for faster onboarding and a better candidate experience. To set up the integration, you’ll need user permissions in Greenhouse to create custom fields, configure web books, and retrieve API keys.
Step 1: Enable the Workvisa.io Stage
To start, contact your Workvisa.io representative to receive your API key. Once you have received your API key, fill out the form at www.greenhouse.io/asksupport or click here to open a ticket.
Note: Do not send the API key in this initial email.
The Greenhouse Support Team will respond with a SendSafely link for you to enter your API key. A notification will be sent to the Greenhouse Support Team after you have entered your API key and they will email you to confirm that your API key has been set up in your account and your integration is enabled.
Note: To verify your identity, the Greenhouse Support Team might request you provide a Support Verification Code before adding the API key to your organization's account.
You can then add the stage “Pre-Hire Immigration Assessment” to your interview plan.
Step 2: Configure Custom Candidate Field
From your Greenhouse Dashboard, click the gear icon in the top-right corner and navigate to Custom Options > Company Custom Fields > Candidates. Click the “Add Field” button to create a custom candidate field.
Enter in the following information below for the Field Name and Type. Use the words exactly as shown below, including capitalization and spaces!
Field Name: Requires Immigration Sponsorship
Type: Yes/No
Click “Save.” Your newly created field will now be part of the company’s library of candidate fields and be shown under the Details tab of a candidate’s profile.
Step 3: Configure Web Hooks
From your Greenhouse Dashboard, click the gear icon in the top-right corner and navigate to Custom Options > Dev Center > Web Hooks > Web Hooks. You will create two Web Hooks. Click “Create Web Hook” at the bottom of the form after creating the first one to save your changes.
Web Hook #1
- Name this web hook: create_candidate
- When: Candidate has changed stage
- Endpoint URL: https://app.immidee.com/
webhook/create_candidate - Secret key: (To be provided)*
- Error recipient email: support@workvisa.io
Advanced Settings
- Username: (To be provided)*
- Password: (To be provided)*
- Maximum Attempts: 3
Web Hook #2
- Name this web hook: update_candidate
- When: Candidate or Prospect updated
- Endpoint URL: https://app.immidee.com/
webhook/update_candidate - Secret key: (To be provided)*
- Error recipient email: support@workvisa.io
Advanced Settings
- Username: (To be provided)*
- Password: (To be provided)*
- Maximum Attempts: 3
* These values are unique to your account and will be provided by your external partner.
Step 4: Retrieve and Send Harvest API Key
From your Greenhouse Dashboard, click the gear icon in the top-right corner and navigate to Custom Options > Dev Center > API Credential Management. Click “Create New API Key” and enter Workvisa.io in the description, then click “Create.” On the next screen, select the below permissions from the list. These permissions grant Workvisa.io access to fetch the required candidate and job information for the assessment.
| Category | Permission | Fetches |
| Applications | GET: Retrieve Application | Application from application ID list |
| Applications | GET: List Applications | List of application IDs |
| Candidates | GET: Retrieve Candidate | Candidate from candidate ID list |
| Candidates | GET: List Candidates | List of candidate IDs |
| Job Posts | GET: List Job Posts | List of job post IDs |
| Job Posts | GET: Retrieve Job Posts for Job | Job posts from job post ID list |
| Job Posts | GET: List Job Posts for Job | Job name and job description |
| Offers | GET: List Application’s Offers | Offer status history |
| Offers | GET: Retrieve Application’s Current Offer | Current offer status for candidate |
| Offers | GET: Retrieve Offer | Offer ID for candidate |
| Offers | GET: List Offers | List of offer IDs by application ID |
| Offices | GET: Retrieve Office | Job location |
| Offices | GET: List Offices | List of job locations |
| Tags | GET: List Tags Applied to Candidate | Tags for data grouping (e.g. location, offer status) |
| Tags | GET: List Candidate Tags | List of candidate tags |
Once you’ve saved the permissions, copy the Harvest API key and securely send it to your external partner to complete the integration setup!
Questions? Contact support@workvisa.io.
Now that you’ve set up the integration, you can now move forward with requesting an assessment for any candidates who indicate they need immigration sponsorship.
Step 1: Confirm the Candidate Requires Immigration Sponsorship
When the candidate indicates that they now or will in the future require immigration sponsorship, make sure to indicate this under “Details” in their candidate profile by selecting “Yes” to the custom field indicated below.
Important Note: If you select “No” or leave the custom field indicated above blank, you will receive an error message and email notification indicating that you will not be able to send the Pre-Hire Immigration Questionnaire to the candidate.
Step 2: Initiate the Immigration Assessment Request
When you are ready to request an immigration assessment, move the candidate to the Pre-Hire Immigration Assessment stage. Once the candidate is moved to the Pre-Hire Immigration Assessment stage, click “Send Test” to send our questionnaire to the candidate.
The questionnaire will be emailed to the candidate, copying a primary contact and the assigned recruiter in Greenhouse.
Step 3: Receive the Immigration Assessment
The assessment will be issued based on the completed questionnaire, the candidate’s resume/CV, and the details of the offered position harvested from Greenhouse. The recruiter will then receive an email with the assessment.