An Inside look into Bullhorn’s Internal APIs

Introduction

Thank you to everyone that came to Engage 2016 and visited us in the Bullhorn Connect room. This was our first year with a developer track and we hope you found it informative and useful.

Abstract

Internally at Bullhorn we have to open new pages within the CRM from different contexts of the application or externally from emails or from other products offerings. This API is publicly accessible and can be used by our partners as well.

Use Cases

The API lives under one endpoint, all you need to do you open a new browser window to the following urls. If Bullhorn is running in another tab then the window will close and the page will open within the current Bullhorn context. If Bullhorn is not running the user will be prompted to login before being brought to the page.

https://www.bullhornstaffing.com/BullhornStaffing/OpenWindow.cfm

Every OpenWindow calls has a few required params:

ParamsDescriptionentityDefine the Entity type for the page you want to openviewThe tab, section, or view to open, eg. Add, Edit, Notes

Opening Add Forms

Candidate:         /OpenWindow.cfm?entity=Candidate&view=Add
ClientContact:     /OpenWindow.cfm?entity=ClientContact&view=Add
ClientCorporation: /OpenWindow.cfm?entity=ClientCorporation&view=Add
JobOrder:          /OpenWindow.cfm?entity=JobOrder&view=Add
Placement:         /OpenWindow.cfm?entity=Placement&view=Add
Opportunity:       /OpenWindow.cfm?entity=Opportunity&view=Add
Lead:              /OpenWindow.cfm?entity=Lead&view=Add

If you want to add a note to any of the top level entities you can use the AddNote view:

/OpenWindow.cfm?entity=Candidate&view=AddNote

Or alternatively you can use the Note entity and pass all of the references yourself:

/OpenWindow.cfm
    ?entity=Note
    &view=Add
    &action=Phone Call
    &comments=Really interesting message
    &personReferenceID=123       // About
    &otherPersonReferenceIDs=1   // Candidate, Lead, Contact 
    &jobOrderReferenceID=1       // Job references
    &opportunityID=456           // Opportunity references
    &placementReferenceID=1      // Placement references

Overview Pages

The same concept can be applied for the overview pages using the Overview view parameter, just make sure you remember to include an id parameter as well:

/OpenWindow.cfm?entity=Candidate&id=12345&view=Overview

If you want to open a the activity tab on the overview you can use the Activity view parameter. Additionally you can use the expandedSection parameter to have a specific section open:

/OpenWindow.cfm?entity=Candidate&id=12345&view=Activity&expandedSection=Interviews

The Edit tab can be opened with specific Edit view parameters:

/OpenWindow.cfm?entity=Candidate&id=12345&view=Edit

Disclaimer

The OpenWindow API has been changed frequently over the years as new entities and sections of the application get added or updated. The API is stable and no foreseeable changes are planned. This Article does not include all of the features in the OpenWindow API or any of the nuances that might exist just the most common use cases. If you have any question or need to open a window that is not listed please ask them in our Gitter channel.

Bullhorn’s OpenWindow API was originally published in Bullhorn Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

What is the Bullhorn REST API?

The Bullhorn REST API gives partner a simple yet powerful way to interact with the Bullhorn system. Because it uses HTTP requests, responses, and standard data structures, the REST API is accessible from many programming languages and is particularly well-suited to mobile applications and applications that use the most current web technologies.

What is Postman?

The idea for Postman arose while the founders were working together and were frustrated with the existing tools for testing APIs. They felt that there should be a better language for developers to use to communicate with APIs. This led to the creation of Postman. Postman helps you build, test, and document APIs faster.

Get it here!

Get Started with Postman

Download the Bullhorn REST API Configuration

We have created a bundle that includes all of the commonly used API calls with the REST API. This is the first step in getting started with the Bullhorn REST API.

Download it here!

Import Configuration into Postman

Once you have the configuration file downloaded, you can import it into Postman by clicking on the “Import” button located in the header of the application. This will open the import menu and you should be able to load the file you downloaded in the previous step.

Setup your Environment

Now we almost ready to get started. The last step is to setup your environment. From the environments drop down in the upper right of the application, select “Manage Environments.” As in the screenshot below, you need to add a “server” environment variable to connect.

Using OAuth to connect to Bullhorn

Now you have Postman all setup to connect to the Bullhorn API. From the Authentication section select the OAuth2 Login call. In the Builder view, select “OAuth 2.0” from the type drop down in the Authorization tab. The values should all be pre-populated.

1. Now press “Request Token”, this will open a new window for you to enter your OAuth credentials.

2. Once you logged in you will see a BullhornAccessToken available, click on this to add it to the end of the login url.

3. Once the token is added, press Send to login to the REST API.

You will have to repeat these steps every time your token expires. Your ACCESS_TOKEN is only valid for 5 minutes, so it will have to request a new token.

Start making API calls

Now you are ready to make api calls. Within each section, some calls need to be run first in order to populate environment variables to make subsequent calls. You can use these variables or replace them with the values you need when exploring your data.

Get access to the Bullhorn REST API

Bullhorn uses OAuth 2.0 as the authorization mechanism for the Bullhorn REST API. See OAuth authorization for the Bullhorn REST API for high-level information about how Bullhorn uses OAuth with the REST API. Bullhorn customers can obtain OAuth keys for developing applications with the Bullhorn REST API by creating a support ticket via the Bullhorn Resource Center.

Exploring the Bullhorn API with Postman was originally published in Bullhorn Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.