Berry Appleman & Leiden (BAL) integration

The Berry Appleman & Leiden (BAL) integration is a streamlined system designed to simplify the management of immigration processes and compliance requirements for companies hiring skilled foreign talent. With a focus on efficiency and user-friendliness, the BAL integration empowers HR and legal teams to navigate immigration complexities seamlessly, ensuring a smooth recruiting process and faster onboarding for new hires.

The integration of BAL with Greenhouse Recruiting enables recruiters to easily request pre-hire and new-hire immigration assessments directly from Greenhouse Recruiting. This integration enhances the candidate experience by expediting the onboarding process and ensuring compliance with immigration regulations.

Enable the BAL immigration integration

Contact your BAL representative to receive your API key. Once you have received your API key from BAL, click here to open a ticket with the Greenhouse Technical Support team.

The Greenhouse Technical Support team will respond with a SendSafety link for you to enter your API key from BAL. The Technical Support team will then enable the BAL Immigration Assessment stage for your organization.

Create a Harvest API key

Follow the steps in this article to create the key, and verify that the permissions of the API key is as follows:


  • API type: Harvest
  • Partner: BAL or Unlisted Vendor
  • Description: BAL Harvest API key


Verify that the following permissions are selected for the Harvest API key:

  • Applications
    • GET: Retrieve Application
    • GET: List Applications
  • Candidates
    • GET: Retrieve Candidate
    • GET: List Candidates
  • Job Posts
    • GET: List Job Posts
    • GET: Retrieve Job Post for Job
    • GET: List Job Posts for Job
  • Offers
    • GET: List Application’s Offers
    • GET: Retrieve Application’s Current Offer
    • GET: Retrieve Offer
    • GET: List Offers
  • Offices
    • GET: Retrieve Office
    • GET: List Offices
  • Tags
    • GET: List Tags Applied to Candidate
    • GET: List Candidate Tags

Create a webhook

Follow the following article to create a webhook and use the below values to set up the integration.

This webhook is used to initiate a new-hire case when a candidate accepts an offer.

  • Name: BAL Offer Updated
  • When: Offer updated
  • Endpoint URL:
  • Secret key: [Provided by your BAL representative]
  • Username: [Provided by your BAL representative]
  • Password: [Provided by your BAL representative]

Create custom fields

Follow the steps in this article to create a custom candidate field using the following information.

You'll need to create three fields for the integration. The field names must exactly match for the integration to function.

Custom field 1: Require immigration sponsorship candidate

Note: If the “Requires Immigration Sponsorship” candidate custom field is left blank or marked as No, then an error will occur when sending a test.

  • Field Name: Requires Immigration Sponsorship
  • Type: Yes/No

Custom field 2: Salary offers offer

  • Field Name: Salary
  • Field Type: Currency

Custom field 3: Candidate workday location offer

  • Field Name: Candidate Workday Location
  • Field Type: Short textbox

Note: The Candidate Workday Location and Salary offer custom fields are optional. These values are sent to BAL when a new-hire assessment is initiated.

Use the BAL Integration with Greenhouse Recruiting

Now that you are all set up, you can send tests to your candidates that require immigration sponsorship.

Step one: Confirm the candidate requires immigration sponsorship

When a candidate indicates that they now or will in the future require immigration sponsorship, make sure to indicate this under the Details tab of their candidate profile.

Step two: Send the immigration assessment to candidate

You can send the assessment to a candidate by moving the candidate to the BAL Immigration Assessment stage and clicking on the Send Test button.

Note: When you send a test in Greenhouse Recruiting, the instructions are actually sent by BAL.

After it has been sent, an assessment’s status will display in Greenhouse Recruiting.

Once the candidate has submitted their test, the Interview Kit will contain a link to view the submitted test in the BAL application.

To see a candidate’s results in BAL, click View Report .

Additional resources

For additional information not covered here, reach out to