Understanding API Usage Limits, Versioning, and Backward Compatibility

This article provides information on API Usage Limits, Versioning, and Backward Compatibility. To maintain a minimum level of performance and to ensure that the Bullhorn API is available to all of our customers, Bullhorn balances transaction loads by imposing limits on the following:

• Concurrent API session limits
• Total daily API request limits
• Per minute API request limits
• API Subscription limits - Think of a subscription as an application.
  • If you have one API key/user, you can use the same key/user for multiple applications.
  • If you use your API user for more than one application tied to Bullhorn, you will need to use the same API username/password across those multiple applications. This also means that when an API user appears in Bullhorn's edit history, you'll be unable to differentiate which API subscription was responsible for creating that edit history.
• Time To Live (TTL) for unused subscriptions
• TTL for unretrieved events
• These limits are set according to the edition in use by your company.

Bullhorn is also continually improving the functionality and quality of the Bullhorn APIs through new releases and bug fixes. Bullhorn uses version numbers to separate releases that may change an interface already in use by existing customer applications.

Versions are designated by a change in the web service URL. For instance, version 1.0 of the API was available at https://api.bullhornstaffing.com/webservices-1.0/?wsdl while version 1.1 is available at https://api.bullhornstaffing.com/webservices-1.1/?wsdl. Any change in the number represents a change in version.

Usage Limits

Corporate Edition - Limited API Access*

• Your company can have up to 25 concurrent API sessions at any point in time.
• The total calls cannot exceed 100,000 per day.
• Maximum number of calls per minute is 700.
• The maximum number of API Subscriptions allowed is five.
• Time To Live (TTL) for unused subscriptions is seven days.
• TTL for unretrieved events is seven days.

Enterprise Edition - Full API Access

• Your company can have up to 50 concurrent API sessions at any point in time.
• The total calls cannot exceed 2,000,000 per day.
• Maximum number of calls per minute is 1500.
• The maximum number of API Subscriptions allowed is 15.
• Time To Live (TTL) for unused subscriptions is seven days.
• TTL for unretrieved events is seven days.

Compatibility Between Versions

The API is backward compatible in that an application created to work with a given API version will continue to work with that same API version as long as that version is supported. Any change to existing API versions that results in a downstream effect in client applications will be resolved via Bullhorn's defect escalation and fix channels.

Bullhorn does not guarantee that applications built with one version of the API will work against future versions of the API. Bullhorn strives to minimize the cost of upgrading applications between versions; changes in interfaces or behavior may require rework before an application can use a newer version of the API.

When building new applications, customers should always use the newest version of the APIs, as these represent the most recent set of functionality and will provide the longest window of support.

Each version of the Bullhorn APIs will be supported for at least 3 years after the release of a newer version. For example, version 1.0 will continue to be supported for at least 3 years after the release of version 1.1, and version 1.1 will continue to be supported for at least 3 years after the release of version 2.0.

API Version End-of-Life

When an API version is schedule for end-of-life, Bullhorn will post a notice on the Bullhorn Resource Center at least 6 months prior to support being ended. As stated previously, end-of-life will occur no sooner than 3 years after a version has been superseded by a more recent version. It is the customer's responsibility to migrate existing applications to a new version of the API before a version becomes unsupported.

*With limited access, as an example, you could build a job page to customize how your website integrates candidate applications into Bullhorn.