Documentation
Connecting Bullhorn
Your site connects straight to your own Bullhorn account with credentials Bullhorn issued to you. There is no W3Bullhorn relay in between, and we never hold a credential that reaches your data.
Before you start
What you need from Bullhorn first
Ask your Bullhorn account manager for these if you do not have them.
- API access on your account. Not every Bullhorn subscription has it enabled. Your account manager can confirm.
- A client ID and client secret. Issued by Bullhorn for your organisation. These are yours and stay on your own site.
- A Bullhorn user for the integration. The connection acts as a Bullhorn user. Use one intended for this rather than a person who may leave.
If Bullhorn asks what redirect or callback address to register, the Bullhorn Connection screen shows the exact value for your site. Copy it from there rather than typing it, because it must match character for character.
Connecting
Four steps on the Bullhorn Connection screen
W3Bullhorn → Bullhorn Connection.
-
Credentials
Enter your credentials
Client ID and client secret. They are stored on your own site, for this site only.
-
Bullhorn
Authorise
You are sent to Bullhorn to sign in and approve the connection, then returned to your site.
-
Verify
Verify
The screen checks the connection against Bullhorn and reports what it found, rather than assuming it worked.
-
Fields
Essential Fields
Confirm the handful of fields a job page cannot do without, discovered from your own Bullhorn configuration.
How it connects
What happens underneath, and why there is no swimlane to enter
Useful if you have set up Bullhorn’s own career portal plugin before, or if a reviewer asks how the connection is established.
Bullhorn does not serve every customer from the same place. Accounts live on different data centres — Bullhorn calls one a <strong>swimlane</strong> — and the addresses an integration has to talk to depend on which one you are on.
Bullhorn’s own Open Source Career Portal plugin, the one configured with the <code>[oscp]</code> shortcode, asks you to supply that swimlane yourself along with a corporation token. W3Bullhorn has no field for either, because it asks Bullhorn instead: it looks your username up against Bullhorn’s own discovery service and configures itself from the answer. Exactly one address is fixed in the plugin — Bullhorn’s published discovery endpoint, which is universal rather than a data-centre choice — and every address used after that comes from Bullhorn’s response and is checked against a list of permitted Bullhorn hosts before anything is sent to it.
| What you supply | A client ID, a client secret, and a Bullhorn user for the integration to act as |
|---|---|
| What you do not supply | The swimlane or data centre, the REST address, or the OAuth address. All three are discovered |
| Requests involved | Four: discovery, the authorisation step you complete in Bullhorn, the token exchange, and the REST login that returns your session |
| Corporation token | Used only for public job search, where it appears in the address by design. It is an identifier rather than a credential, and it is not what authenticates your connection |
| If discovery returns the wrong data centre | It is detected and corrected. See below |
Data centre migration
When Bullhorn’s own answer is out of date
A real case rather than a hypothetical one.
On 4 October 2026, against a real Bullhorn account, the discovery service named one data centre and every host in it answered with a redirect pointing at a different one. The account had been migrated and discovery had not caught up.
That is worse than it sounds, because three separate requests derive their addresses from that single answer. Correcting one of them in place leaves the next two pointing at the wrong place, so the connection fails at a different step each time — which is a miserable thing to diagnose from the outside.
W3Bullhorn treats the discovery result itself as the thing that was wrong. It reads which data centre the redirect names, rebuilds the addresses from its own templates rather than using the ones it was handed, validates each against the permitted-host list, and caches the corrected result. The token exchange and the REST login are then simply issued against the right place, with no special case anywhere else.
Why this is not just following the redirect
Because a request carrying your credentials is never replayed at whatever address a response happens to nominate. The redirect is read only as a hint about which Bullhorn data centre to use; the addresses are rebuilt from the plugin’s own templates and validated before anything is sent. The most that forging one could achieve is moving the connection to a different genuine Bullhorn data centre.
Setup
Essential Fields
Why there is a step for this at all.
Bullhorn installations differ. Agencies put the public job title in different places, use different fields for location and salary, and name their own custom fields whatever suits them. A plugin that assumed one layout would show the wrong things on your board.
So the connection step reads your own Bullhorn configuration and asks you to confirm which field is which. It is a short step and it only happens once, but it is the difference between a board that reads correctly and one that shows an internal reference where the job title should be.
Access
What the connection can and cannot do
The answer a security reviewer wants.
| Direction | Mostly read. Jobs and the related fields a job page needs are read from Bullhorn |
|---|---|
| What is written | Applications, and the canonical job address written back to the job record. Nothing else |
| Write safety | Writes go through one gateway with a field allowlist, so the plugin cannot write a field it was not built to write |
| Where credentials live | In your own site’s database, for that site only |
| Who else can reach them | Nobody. There is no central relay and no account of ours in the data path |
| Candidate access | No candidate ever authenticates to Bullhorn, including through the candidate portal |
If the connection stops working
Bullhorn access can be revoked, expire or be changed at the Bullhorn end. The plugin reports a broken connection in Site Health as the <code>w3rp_connection</code> check and on the Bullhorn Connection screen, and offers a reconnect rather than silently failing. Job pages already published stay published while the connection is down.