1. Home
  2. Getting Started
  3. Connecting to Bullhorn

Connecting to Bullhorn

Matador Jobs isn’t like every other job board for WordPress because it integrates with Bullhorn and automatically imports job data. To begin accessing these awesome features, we need to connect to Bullhorn.

To create this guide, we collected screenshots from a Matador Jobs Pro install on a standard, unaltered WordPress admin. Some web developers will modify the styling and theme of the WordPress admin area, so your site may appear differently than ours.

This guide assumes the following:

  1. That you are logged into your WordPress admin and have administrator capabilities on your user account.
  2. That a version of Matador Jobs is installed and activated on your site.

Before You Start

There are two known issues that can occur when users connect Matador Jobs to Bullhorn while they are also actively logged into or have an active or expired login cookie to the Bullhorn ATS. Both issues can be avoided by taking these simple precautions.

Before you begin the process of connecting to Bullhorn, if you’ve ever logged into the Bullhorn ATS from your computer, we strongly recommend you do one (and only one is necessary) of the following:

  • Access the Bullhorn ATS (including re-authorizing with your username and password if needed) and then explicitly log out by clicking or tapping Log Out in the top right. This removes the Bullhorn authentication cookie.
  • Use a Private Browsing or Incognito Browsing mode on your web browser to perform the Bullhorn Connection. In this mode, no Bullhorn authentication cookie exists.
  • Use an alternate web browser, eg: Firefox instead of Chrome, which you have not previously used when accessing the Bullhorn ATS. By using a different browser, no Bullhorn authentication cookie exists.
  • Delete all cookies and cached website content. This will delete the Bullhorn authentication cookie.

The Bullhorn Connection Assistant

To assist in connecting to Bullhorn, we built the Bullhorn Connection Assistant. Access it to begin connecting your site to Bullhorn.

Accessing the Connection Assistant

To access the Bullhorn Connection Assistant, hover over or tap on the Matador Jobs menu item in the main menu. In the sub menu that comes up, click or tap Settings.

Once on Matador Jobs settings, under the General tab, look for the Bullhorn API Connection section. You will see a button labeled Connection Assistant under a notice that begins with “Your site is not connected to Bullhorn.” Click on the button.

Screenshot of the General Tab of Matador Settings, with a focus on the Bullhorn API Connection setting
The General tab of Matador Settings where you will find the Connection Assistant button

Using the Connection Assistant

The Bullhorn Connection Assistant is meant to lead you through the steps of getting connected to Bullhorn. Each step explains what you need to do while also running behind the scenes health checks to guide you through.

The “Prepare” Step

In the “Welcome to Matador” step, we provide basic instructions for what you need to connect to Bullhorn. They are:

  • A Bullhorn ATS account with REST API enabled
  • A REST API Client ID
  • A REST API Client Secret
  • A REST API User ID
  • A REST API Password
  • The Matador Jobs API callback URI registered to the list of allowed callbacks URIs
  • Your Bullhorn account’s server cluster

Whether you don’t know what these are, aren’t sure, or know you have these things, select the appropriate option and click Next Step.

Screenshot of the Prepare step of the Bullhorn Connection Assistant tool
Select from the options that best describe your current status.

If you answered “I don’t have API access or I’m not sure”

If you answered “I don’t have API access or I’m not sure,” the Connection Assistant will generate a form email you can copy-and-paste to a new email, update, and send to Bullhorn technical support who will set you up with your credentials. You can safely leave this page and return when they reply!

If you answered “I have API access, but I forgot my credentials”

If you answered “I have API access, but I forgot my credentials,” the Connection Assistant will also generate a form email you can copy-and-paste to a new email, update, and send to Bullhorn technical support who will provide you with your credentials while adding the URL to the allowed endpoints list.

You can share REST API credentials between multiple Bullhorn REST API integrations, but as a best practice, one set for each application is ideal. This helps you not break your tech stack if you were to change a password for one integration without remembering to update it in another.

If you answered “I have everything I need, let’s go.”

If you answered “I have everything I need, let’s go” then you’ll be advanced to the next step.

Whether you have new or existing API credentials, never use the API Username and API User Password to log into the Bullhorn ATS. This will cause your site to disconnect from Bullhorn at some time in the future due to security features at Bullhorn.

The “Datacenter” Step

The next step will ask you to select a Regional Datacenter. The datacenter for your connection will be based on the server cluster for your account. Typically, this information is provided in your REST API setup email response from Bullhorn.

In most cases, if you pick the wrong datacenter, your connection to Bullhorn will not fail, however, the overall speed of your Bullhorn sync may be affected if you choose a datacenter physically far from where your cluster is located. For example, it would be unwise to choose Australian datacenters when your account is based in Germany, but it may not affect your speed if you choose Northeast USA (Boston) instead of Eastern USA (North Carolina).

Screenshot of the Regional Datacenter step of the Bullhorn Connection Assistant tool
The Regional Datacenter step

After you select the actual (or best guess) datacenter for your account, click or tap Next Step.

The “Credentials” Step

In this step, you’ll enter the REST API credentials you got from Bullhorn. Copy-and-paste the items exactly and try to avoid copying any spaces or line breaks that appear not to belong.

Screenshot of the Credentials step of the Bullhorn Connection Assistant
Fill out all the fields in the Credentials step

After you have completely filled out this form, click or tap on Next Step to continue the connection assistant.

At this point, Matador Jobs will run several checks on your credentials. The software is able to determine, at this point, if the provided credentials contain a valid Client ID and valid Client Secret. In the event you are returned to this screen, the Bullhorn Connection Assistant will be able to tell you what is invalid. Re-check you copied it exactly, and if you did, you may need to reach out to Bullhorn support asking them to re-issue your credentials.

The “Callback URI” Step

When Matador communicates with Bullhorn, it sends a special behind-the-scenes request asking for permission to access your data via the API. Bullhorn, instead of simply replying “yes” or “no”, will give its answer in a redirect to a callback URI. Matador creates a special hidden place on your website to listen for those “answers” from the Bullhorn API and begin communicating with it when the answer is yes.

Many of the terms in this section are included in our Glossary, in case some of the terms are unfamiliar to you.

This step will check if your callback URI is authorized. In most cases, the step will tell you yes, and if so, you can simply click or tap on Next Step. If not, it will provide instructions including a form letter you can copy-and-paste and use to send a request to Bullhorn support.

Screenshot of the Callback URI step of the Bullhorn Connection Assistant
The Callback URI step showing the confirmation the URI is registered and allowed at Bullhorn

The “Authorize” Step

We’ve made it now to the final step! At this point, simply click or tap on the Authorize Site button to connect your site to Bullhorn.

Screenshot of the Authorize step of the Bullhorn Connection Assistant showing the Authorize Site button.
The Authorize step of the Bullhorn Connection Assistant showing the Authorize Site Button

You will either be redirected to a Bullhorn login screen or return immediately to a completed Bullhorn Connection Assistant.

If you’ve never authorized your site before, you will be redirected to a Bullhorn login screen and asked to enter your API username and API password on the Bullhorn site. Use the same ones you provided in the Credentials step.

Screenshot of the Bullhorn login presented to users during an initial Bullhorn API login.
The Bullhorn API Authorization Dialogue

Despite our warnings above, it is okay to use your API Username and API Password here. This is not an ATS login but an API login.

Do not you use your regular username and password at this screen! While your Matador connection may initially work, the next time you change your password your site will be disconnected. Make sure you use only your API Username and API Password.

You may further be asked in this process to accept the API Terms of Service. Make sure you do this.

Upon completing these steps, you will be redirected to your Bullhorn Connection Assistant.

Screenshot of the Authorize Step of the Bullhorn Connection Assistant after successfully connecting to Bullhorn.
The Authorize Step of the Bullhorn Connection Assistant following a successful connection.

Congratulations, you are now connected to Bullhorn! Click Complete Connection Assistant, and on the next screen Exit Connection Assistant to exit to Matador Jobs settings.

Troubleshooting

Here are some common issues, and how to solve them.

What’s Next

We recommend you perform your first manual sync, review basic Matador Jobs settings, and set up your jobs page!

Updated on August 24, 2020

Was this article helpful?

Related Articles

Leave a Comment