Download the PHP package darvis/bullhorn-api without Composer

Bullhorn REST API for PHP and Laravel

A PHP client for the Bullhorn REST API, the API of the Bullhorn staffing and recruitment CRM. It logs in with OAuth, keeps one session for all your requests, renews it safely when Bullhorn ends it, and gives you helpers that use Bullhorn's own verbs. The client is plain PHP; in Laravel it comes with a facade, an encrypted session cache and a connection test.

Features

• Is Bullhorn alive? isAlive() answers true or false and never throws: one line for a health check
• Examples for every common task: thirteen runnable scripts and a page of Laravel recipes, all commented step by step
• The whole login: loginInfo, authorize, token and REST login, on the first call and not before
• One shared session: in Laravel's cache or a file outside the web root, so Bullhorn sees one login instead of one per request
• Safe renewal: on a 401 the client takes the session another process renewed, or renews under a lock with the refresh token, and repeats the call once
• Bullhorn's verbs: createEntity() sends PUT, updateEntity() sends POST, plus entity(), search(), query(), meta() and upload()
• Failures you can act on: the whole response in the message, errorKey() and invalidFields(), and a separate AuthenticationException for a failed login
• Safe with your credentials: secrets and tokens are removed from every exception message
• Laravel: the Bullhorn facade, Http::fake() in your tests and php artisan bullhorn:test
• Plain PHP: no dependencies; cURL by default, or your own transport and store
• Laravel Boost: guideline and skill included, so an AI assistant in your app knows the pitfalls

Requirements

• PHP 8.2+
• Bullhorn REST API credentials: client id, client secret, API username and password
• For the Laravel integration: Laravel 11, 12 or 13
• Without Laravel: the cURL extension

Quick start (Laravel)

Quick start (plain PHP)

Is Bullhorn alive?

isAlive() logs in when needed, pings Bullhorn, and answers true or false. It never throws, so it fits in an if:

Without a session it costs a login, and Bullhorn limits logins. Keep the answer for a minute instead of asking on every page view:

isAlive() tells you that something is wrong. To see what, call ping(): it throws an AuthenticationException for a login problem and a BullhornException for anything else, with the reason in the message. On the command line, php artisan bullhorn:test does both and prints the reason.

Without Laravel it is the same method: $bullhorn->isAlive().

Examples

New to Bullhorn or to this package? Start here.

• examples/: thirteen small scripts, each doing one thing, commented step by step. Run the first one to check your credentials:

  The others read a candidate, search by email, list open jobs, page through results, create and update a candidate, handle a rejected update, add a note, apply for a job, parse a CV, attach a file and list the fields of an entity. The ones that change data refuse to run without --write.

• Examples page: the same tasks in a Laravel application, with a health check URL, a Livewire form, a queued job for applications and tests.

Documentation

The full documentation is at https://arviddejong.github.io/bullhorn-api/: installation, how the login and the shared session work, the API reference, testing, troubleshooting, and migrating from jonathanraftery/bullhorn-rest-client.

Laravel Boost

This package ships a guideline and a skill for Laravel Boost. Run php artisan boost:install, or php artisan boost:update --discover in a project that already uses Boost.

Testing

Changelog

See CHANGELOG.

Support the package

If darvis/bullhorn-api saves you time, buy me a beer 🍺: sponsor me on GitHub.

Contributing

See CONTRIBUTING.

Security

Please report a vulnerability privately, as described in SECURITY, not in the issue tracker.

License

The MIT License (MIT). See LICENSE.