NAV
shell

Introduction

This reference guide provides general information about the Bullhorn REST API and specific information about each API operation and supported entity type.

Other Guides: - Entity Reference Guide available: here

General Conventions

Whenever possible, the REST API will follow specifications, conventions and practices of HTTP and the web in general. This includes things like case sensitivity of URLs, character encodings, HTTP methods, and so forth. Additional recommended practices for REST APIs are also observed whenever appropriate.

URLs

Web URLs are case-sensitive, except for machine names. We shall follow that practice. All REST API URLs should be considered case-sensitive.

All URLs are namespaced by corporation. The first path element of all API URLs, after any context root, will be an identifier for a corporation. For example:

https://rest.bullhornstaffing.com/e999/entity/Candidate

Where e999 is the corporation identifier.

Data-center-specific base URLs

Use the following base URL that applies to your geographic location and swimlane.

U.S. East Coast Data Center

(CLS4, CLS5, CLS2, CLS20, CLS6, CLS7) https://rest.bullhornstaffing.com

U.S. West Coast Data Center

(CLS30, CLS31, CLS32, CLS33) https://rest-west.bullhornstaffing.com

UK Data Center

(CLS21, CLS22) https://rest-emea.bullhornstaffing.com

Entities

Bullhorn uses the term entity to refer to a type represented in the Bullhorn system. Candidate, ClientContact, JobOrder, and Placement are examples of entities. Entities capture the core concepts within the Bullhorn system and provide an organization for storing staffing data and applying the rules and processing that comprise the Bullhorn system.

JSON

The REST API f the specifications and conventions of the JavaScript Object Notation (JSON) data format and any related Javascript syntax specifications. For more information, see the following articles:

JSONP

The REST API supports JSONP. To enable JSONP for any request to the API, provide a value for the optional callback parameter. This changes the API’s response as follows:

  1. The API wraps its response in a Javascript method call. The name of the method is the same as the value of the callback parameter.
  2. The response HTTP Content-Type is "text/javascript" instead of "application/json".

For more information about JSONP, see the following article: http://en.wikipedia.org/wiki/JSONP

API Operations

There are several API operations for retrieving entity data: entity, search, query, and meta. These calls share some common parameters and behavior. * Use the entity operation to create, update, and get entities by id; use the PUT, POST, and GET HTTP verbs to create, update and get entities, respectively. * Use the search operation to search for entities in a Lucene search index, and return them by id. Use the search operation with search/{EntityType} and no query parameters to return data that describes the structure of the Lucene index fields for the entity. * Use the query operation to query for entities with the Java Persistence Query Language (JPQL), and return them by id. * Use the meta operation to return entity metadata data that describes the structure of returned entity data. You can also return entity metadata on any entity, search, or query call by including the meta query parameter on the call; See Meta for details.

Entity ids

All entities have a field named id that is the primary key of the entity. When selecting to-one and to-many association fields on an entity, id is automatically included if no sub-fields are specified.

Notes

Authorization

User authorization and session management use the following flow:

  1. An OAuth 2.0 access token is returned though the OAuth 2.0 authorization flow. For more information about the OAuth flow, see Getting Started with REST
  2. A REST API login call that contains the access token as a query parameter is made. If this call is sucessful, a token named BHRestToken is returned. This token represents a session established by the login process; it must be sent along with all subsequent requests to the REST API. The BhRestToken can be provided in a URL query string, a cookie, or an HTTP header.
  3. The login call also returns a base URL with which all subsequent API requests must be prefixed.

Unauthorized requests

If a client makes a request and does not include a BhRestToken, the server sends a response with HTTP status 412 (precondition failed). If a client request contains an invalid session key, the server returns response status 401 (unauthorized). For more information on HTTP status codes see Errors.

Session key

The REST API has the concept of a client “session”. This is essentially a method for allowing clients to authenticate themselves once and then be free of the need to authenticate for subsequent calls to the API. Since REST is a stateless protocol, there must be a mechanism for clients to identify themselves upon each request, so the requests can be tied to an established session. This is what the session key provides. Login calls return, as part of their responses, a session key that represents a successful authorization and can be used to make further calls without having to authenticate.

This key must be provided in HTTP requests in at least one of the following places:

  1. A query parameter named BHRestToken on the request URL.
  2. An HTTP header named BHRestToken.
  3. A cookie named BHRestToken. This cookie is set by the API at login time as a convenience for browser-based clients.

General GET request options

You can use the following API commands to retrieve data:

These calls share some common parameters and behavior.

Entity fields

Each entity is composed of a distinct set of fields, or properties. When retrieving entities, you specify which fields to return in a query parameter named fields. The following types of values are supported in the fields parameter:

All fields

fields=*

Note: Use fields=* sparingly. The * value returns all fields, including one-to-many association fields. Each one-to-many field affects performance of the query. Use the /meta/{entityType} call to determine which fields are one-to-many fields.

Entity ids

All entities have a field named id, which is the primary key of the entity:

fields=id,owner(id),categories(id)

When selecting to-one and to-many association fields, id is automatically included if no subfield is specified:

fields=owner,categories

Is the same as:

fields=owner(id),categories(id)

Comma-separated list of fields

fields=id,name,address,owner,categories

Nested, to select sub-fields of composite, to-one and to-many associations( )

fields=id,name,address(city,zip),owner(corporation(name)),categories(name)

Note: For nested to-many associations for which the user does not have read entitlements, only data for predefined fields is returned. The other fields are returned with a value of “null”. The following entity fields are predefined:

Number of to-many entities to return [count]

fields=categories[3],jobSubmissions[5](dateAdded,jobOrder(name))

Note: The default count of to-many entities is 5. The maximum count is 10; if you specify a count greater than 15, a message at the end of the response indicates you have specified too many items.

Filter to-many entities with a sub-where clause

Use the following syntax to filter the to-many entities that are returned in a response. All three parts of the syntax are optional. The where-filter is delimited by curly braces.

fields=fieldName[count](sub-fields*){where-filter}*

Examples:

search/JobOrder?fields=id,businessSectors[3](name,id){name=‘Insurance’}

search/Candidate?fields=id,lastName,primarySkills(name,id){name IN (Java, 'SAP’)}

To-many fields can only appear at the top level with no nesting

Bad: fields=categories(children)

Bad: fields=owner(categories)

Entity metadata

You can include metadata, data that describes the structure of returned entity data, in responses that the REST API returns.

The following two tables describe the entity and entity property metadata types.

* Fields that are returned only if meta=full.

Entity metadata Description
entity Entity name; for example, Candidate, JobOrder.
label Entity display label from the private label attribute “EntityTitleXxx”; may be missing.
fields Array of property metadata (see table below).

Entity property metadata

Description

name Property name; for example, firstName.
Label Property display label from fieldmap; may be missing.
type Property type, one of ID, SCALAR, COMPOSITE, TO_ONE, or TO_MANY.
dataType Property data type: Integer, BigDecimal, Double, String, Boolean, Timestamp, byte[], Address, Address1, AddressWithoutCountry (these are composite types), and LoginRestrictions.
maxLength Only present when dataType=“String”. The maximum authorized length for this String field.
dataSpecialization Finer definition of dataType. For example, dateType=Timestamp and dataSpecialization=DATE one of NUMERIC, INTEGER, FLOAT, MONEY, PERCENTAGE, PHONE, SSN, HTML, DATE, TIME, DATETIME, COLOR, SYSTEM, or VIRTUAL; may be missing.
* optional Is the property value optional (specified by Hibernate, typically means database nullability); also see required.
* required Is the property value required (specified by fieldmap); also see optional.
* readonly Is the property hidden (specified by fieldmap).
* multiValue Is the property multi-valued (specified by fieldmap); dataType must be String.
* inputType Suggested input type: CHECKBOX, RADIO, TEXTAREA, or SELECT; may be missing.
* optionsType For inputType SELECT only; for example, Country. may be missing.
* optionsUrl If optionsType is present, where to get the list of options (displays and values).
options The hard-coded options from fieldMap in an array of value/label pairs; may be missing.
* defaultValue Value type depends on dataType and dataSpecialization: may be missing.
If the defaultValue is not translatable, For example, cannot parse string to a date; it is ignored. If multiValue, returns as array.
fields Array of sub-fields property meta for COMPOSITE type.
associatedEntity Entity metadata for TO_ONE and TO_MANY type.

Bullhorn fieldmap edit types and REST metadata

The following table lists each Bullhorn fieldmap edit type and the corresponding dataSpecialization, inputType, and optionsType metadata values for the REST API.

Edit type

DataSpecialization

InputType

OptionsType

Color COLOR    
Date DATE    
Time TIME    
Date/Time DATETIME    
Float FLOAT    
Integer INTEGER    
Money MONEY    
Numeric NUMERIC    
Percentage PERCENTAGE    
Phone Number PHONE    
Text SSN SSN    
DHTMLEditor HTML  
DHTMLEditor - No Toolbar HTML    
Check Box   CHECKBOX  
Radio   RADIO  
Select   SELECT  
Text      
Text Block   TEXTAREA  
Text Block Large   TEXTAREA  
Drop Down   SELECT  
Mini Picker   SELECT  
Mini Picker - Text Block   SELECT  
Xxx - Drop Down   SELECT Country
State
Xxx - Mini Picker   SELECT Country
State

Picker:[OptionsType]

Stores data as an INT value unless it is a multi-picker, which stores a comma-separated list of Integers in a string field.

  SELECT BillRateCategory
BusinessSector
Candidate
Category
Certification
Client
ClientCorporation
HousingAmenity
HousingComplex
HousingComplexUnit
CorporateUser (Internal)
JobOrder (Job Posting)
Person (People)
Shift
Skill (Skills)
Specialty
WorkersComp

Picker:Text:[OptionsType]

Stores data as a text value unless it is a multi-picker, which stores a comma-separated list of string values.

  SELECT BusinessSectorText
CandidateText
CategoryText
CertificationText
ClientText
ClientCorporationText
HousingComplexText
HousingComplexUnitText
CorporateUserText (Internal)
JobOrderText (Job Posting)
PersonText (People)
ShiftText
SkillText (Skills)
SpecialtyText
StateText
Custom Component      
Custom External Control      
Section Header      
System SYSTEM    
Virtual VIRTUAL    

Errors

The REST API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is no good
401 Unauthorized – Your API key is wrong or expired
403 Forbidden – The entity requested is hidden for administrators only
404 Not Found – The specified entity could not be found
405 Method Not Allowed – You tried to access a entity with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The entity requested has been removed from our servers
429 Too Many Requests – You’re requesting too much! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

allCorpNotes

GET /allCorpNotes

curl https://rest.bullhornstaffingcom/rest-services/e999/allCorpNotes?clientCorpId=4&fields=start=0&count=5

# Example Response
{
   "total": 9,
   "start": 3,
   "count": 4,
   "data":    [
            {
         "_score": 0.3471885,
         "id": 515,
         "action": "Outbound Call"
      },
            {
         "_score": 0.3091938,
         "id": 25,
         "action": "Outbound Call"
      },
            {
         "_score": 0.3091938,
         "id": 48,
         "action": "Outbound Call"
      },
...
   ]
}

Returns all Notes in the specified ClientCorporation. Specify the fields to be included in the response in the fields request parameter.

HTTP Request

{corpToken}/allCorpNotes/?fields={fieldList}

Parameter Required Description
fields yes Comma-separated list of field names. fields or layout is required.
layout yes Name of a configured layout. fields or layout is required.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.
clientCorpId yes id of a ClientCorporation entity.

Entitlements

GET /entitlements

curl https://rest.bullhornstaffing.com/rest-services/e999/entitlements/Candidate

# Example Response
[
    "CREATE",
    "READ",
    "READ_DEPARTMENT"
    "UPDATE",
    "DELETE"
]

Gets the entity entitlements of an entity for the current user. For GET, PUT, POST, and DELETE requests on entities, the user must have the appropriate entitlements for the action to succeed. PUT requests (adding records) require create entitlements. Read, update, and delete entitlements are divided into owned, department, and corporate entitlements. If a user tries to perform an action without the required entitlements, the call fails and an error is thrown. A user’s ability to perform file attachment GET, PUT, POST, and DELETE operations is based on the user’s entitlements for the entity to which the file attachment operation applies

List of Entitlements

Entitlement Description
CREATE User can create entities.
READ_CORPORATE Generally, user can read all entities. If the entity can be categorized into private and non-private, the user cannot read private entities owned by other users unless the user has the READ_PRIVATE entitlement.
READ_DEPARTMENT User can read entities owned by the current user AND owned by users from the same department(s).
READ User can read entities owned by the user only.
UPDATE_CORPORATE Generally, user can edit all entities. User must also have READ CORPORATE access level.
UPDATE_DEPARTMENT User can edit entities owned by the user AND owned by users from the same department(s). User must also have READ DEPARTMENT or READ CORPORATE access level.
UPDATE User can edit entities owned by the user only.
UPDATE_OWNER Applies to the following entities: Candidate, ClientContact, JobOrder, JobSubmission, Lead,and Opportunity. Without the UPDATE_OWNER entitlement, the user is not allowed to change the owner of an entity even if the user has update entitlements to the entity. If a user has the UPDATE_OWNER entitlement, but only has department-level edit access, the user is able to edit the owners of entities belonging to users in his or her department, but not those belonging to users in other departments.
DELETE_CORPORATE Generally, user can delete any entity. User must also have READ_CORPORATE access level.
DELETE_DEPARTMENT User can delete entities owned by the user AND owned by users from the same department(s). User must also have READ DEPARTMENT or READ CORPORATE access level.
DELETE User can delete entities owned by the user only.

File privacy entitlements

File privacy settings are enforced by a field isPrivate on the file entity. If a file is marked private, the user can only access that file if one of the following is true: - User has the View All Private Attachments entitlement - File is shared with the user - User is the owner or secondary owner of the entity to which the file is associated

Entity

GET /entity

curl https://rest.bullhornstaffing.com/e999/entity/Candidate/5059165?fields=firstName,lastName,address

# Example Response
{
  "id" : 5059165,
  "firstName" : "Alanzo",
  "lastName" : "Smith",
  "address" : {
    "address1" : "",
    "address2" : "",
    "city" : "Sacramento",
    "state" : "ca",
    "zip" : "",
    "countryID" : 1
  }
}

Run in Postman

Gets one or more entities or to-many associations.

Individual entity records are manifested as resources, where the entity type and id form the last two parts of the resource path.

Specify the fields to be included in the response using the fields request parameters. The id field is always returned, regardless of the fields requested. See for more detail on specifying fields.

NOTE: At least one of the required parameters(fields and layout) or both must be specified.

HTTP Request

{corpToken}/entity/{entityType}/{entityId}?fields={fieldList}

Param Required Description
fields yes Comma-separated list of field names. fields or layout is required.
layout yes Name of a configured layout. fields or layout is required.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. For more information, see .
showEditable no (true/false) Default value is false. Whether to show the _editable field in responses. The _editable field indicates whether an entity is editable. Setting showEditable to true results in slower performance; use this setting sparingly and only when needed.

Multiple Entities

curl https://rest.bullhornstaffing.com/e999/entity/Candidate/123,456?fields=id,firstName,lastName

# Example Response
{
    data: [
        {
          "id" : 123,
          "firstName" : "Alanzo",
          "lastName" : "Smith"
        }, {
          "id" : 456,
          "firstName" : "Janis",
          "lastName" : "Williams"
        }
    ]
}

This is an extension of the single GET and supports the same result set control parameters (count, start) as the query call. Id values are specified as a comma-separated list:

HTTP Request

{corpToken}/entity/{entityType}/{{entity-id},{entity-id},*}?fields={field-list}

Parameter Required Description
fields yes Comma-separated list of field names.
layout yes Name of a configured layout.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.
showReadOnly no (true/false) Whether to show read-only fields. Only applies when the layout parameter is used. NOTE: Read-only fields inside of composite properties (Address is the only instance of a composite property) do not obey visibility rules right now. They will always show, regardless of this setting. This is a known issue and there are plans to fix it in a future release.}}
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. For more information, see .
showEditable no (true/false) Whether to show the editable field in responses. The editable field indicates whether an entity is editable. Default value is false.

To-many Associations

curl https://rest.bullhornstaffing.com/e999/entity/ClientCorporation/5059165,2362648/clientContacts?fields=firstName,lastName,address&count=2

# Example Response
{
    ...
}

This is an extension of the single and multiple GETs that returns the to-many associated entities of the specified type for the specified entity ID(s). The call supports the same query parameters as the query call.

HTTP Request

{corpToken}/entity/{entityType}/{id}/{toManyFieldName}s?fields={field-list}

Parameter Required Description
fields yes Comma-separated list of field names.
layout yes Name of a configured layout.
start no From the set of matched results, return record numbers start through (start + count).
count no Limit on the number of records to return. If the set of matched results is larger than count, cap the returned results at size count.
orderBy no Name of property on which to base the order of returned entities.
showReadOnly no (true/false) Whether to show read-only fields. Only applies when the layout parameter is used. NOTE: Read-only fields inside of composite properties (Address is the only instance of a composite property) do not obey visibility rules right now. They will always show, regardless of this setting. This is a known issue and there are plans to fix it in a future release.}}
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. For more information, see .
showEditable no (true/false) Whether to show the editable field in responses. The editable field indicates whether an entity is editable. Default value is false.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /entity

curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"firstName" : "Alanzo", "lastName" : "Smith"}' \
     https://rest.bullhornstaffing.com/e999/entity/Candidate

# Example Response
{
  "changedEntityId": 1489,
  "changeType": "INSERT"
}

You can use HTTP PUT requests to create new entities. The URL looks the same as GET request URL, but without the last path element containing an entity ID. Place the data comprising the new entity to be inserted in JSON format in the request body. The structure of the JSON is identical to that returned in HTTP responses to GET requests, with a few additional restrictions:

Associations fields are set by giving as their values a JSON object containing one field, named ‘id’, and having value the id of the entity to associate.

If you specify fields that do not exist on the entity being created, returns a 400 error containing messaging about the unknown fields,

Most entities in the Bullhorn data model contains mandatory fields. Some of these mandatory fields have default values. All mandatory fields without default values must have values specified in the JSON body of the PUT request or returns a 400 error.

NOTE: When using an HTTP PUT request to create a Client Corporation entity an archived Client Contact entity, which belongs to this new Client Corporation, will automatically be created. This mirrors what is done through the ATS when creating a Client Corporation and allows the new Client Corporation to correctly follow ownership rules (where the ownership of a Client Corp is based on ownership of its Client Contacts) and belong to the person creating it. 

HTTP Request

{corpToken}/entity/{entityType}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Create To-many Associations

curl -X PUT \
     https://rest.bullhornstaffing.com/e999/entity/Candidate/3084/primarySkills/964,684,253

You can add to-many associations to an entity with a PUT request in which you specify entity IDs of the entities you want to associate. The call fails if any of the association entities you specify are already associated.

{corpToken}/entity/{entityType}/{entity-id}/{to-many-association-name}/{entity-id},*}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /entity

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{ "id" : 5059165, "firstName" : "Alanzo","lastName" : "Smith" }' \
     https://rest.bullhornstaffing.com/e999/entity/Candidate/5059165

     # Example Response
{
  "changedEntityId": 1489,
  "changeType": "UPDATE"
}

You can update entities with HTTP POST requests. The URL looks the same as the GET request URL. Place the data comprising the entity fields in JSON format in the request body. The structure of the JSON in a POST request is identical to that returned in HTTP responses to GET requests, but read-only properties cannot be changed.

You set association fields by giving as their values a JSON object that contains a field named 'id’, and providing the value the id of the entity to associate.

If you provide fields that do not exist on the entity being created, returns a 400 error containing messages about the unknown fields.

Most entities in the Bullhorn data model contain mandatory fields, some of which have default values. Returns a 400 error if you do not specify, in the JSON body of the PUT request, values for all mandatory fields that do not have default values.

HTTP Request

{corpToken}/entity/{entityType}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

To-many Associations - Special Case

# This example will create and associate a new customObject1s record.
curl -X PUT https://rest.bullhornstaffing.com/e999/entity/JobOrder/123

# This example will update an existing customObject1s record #1.
curl -X PUT https://rest.bullhornstaffing.com/e999/entity/JobOrder/123

For special to-many associations, like Custom Objects, we have the ability to create and associate in a single step.  These is due to the fact that we need to know their context to enforce security and data integrity.  You can add/update to-many associations with a POST request the same as if it was data directly on the parent entity. You can combine standard parent entity updates with special association add and edits.

HTTP Request

{corpToken}/entity/{parent-entity-name}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /entity

Deletes an entity or to-many association.

The API supports two types of delete requests: * Hard or soft delete using the DELETE verb * Soft delete using the POST verb.

Hard or Soft Delete via DELETE call

curl -X DELETE \
     https://rest.bullhornstaffing.com/e999/entity/NoteEntity/2552

Hard deletes a hard-deletable entity, which removes it from the database. Soft deletes a soft-deletable entity, which sets the isDeleted property of the entity to true.

This operation is available for all entity types except immutable entities, which are neither hard-deletable or soft-deletable. Immutable entities include the following: * BusinessSector * Category * Country * Skill * Specialty * State * TimeUnit

HTTP Request

{corpToken}/entity/{entityType}/{entity-id}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

To delete an entity with children, explicitly delete all the children before attempting to delete the root entity.

Soft delete via POST (update) call

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{ "isDeleted" : true }' \
     https://rest.bullhornstaffing.com/e999/entity/ClientContact/1804

When you soft delete an entity, it is not removed from the database. A soft delete operation is actually an update (for example, POST) that sets the isDeleted property of the entity to true.

HTTP Request

{corpToken}/entity/{entityType}/{entity-id}

Disassociate To-many Associations

curl -X DELETE \
     https://rest.bullhornstaffing.com/e999/entity/Candidate/3084/primarySkills/253

Removes or “disassociates” a to-many association relationship on an entity.

{corpToken}/entity/{entityType}/{entity-id}/{to-many-association-name}/{entity-id},*}

Department Entities

GET /department{Entity}s

curl https://rest.bullhornstaffing.com/rest-services/e999/departmentClientContacts?fields=firstName,lastName,address&start=0&count=5

# Example Response
{
   "data":    [
            {
         "lastName": "Burns",
         "address":          {
            "address1": "2 Olive Lane",
            "address2": "",
            "city": "Ridgefield",
            "state": "CT",
            "zip": "06877",
            "countryID": 1
         }
      },
            {
         "lastName": "Rackley",
         "address":          {
            "address1": "00 Jeffrey Way, Suite 400 |",
            "address2": "",
            "city": "Round Rock",
            "state": "TX",
            "zip": "78665",
            "countryID": 1
         }
      },
            {
         "lastName": "Smith",
         "address":          {
            "address1": "700 Jeffrey Way, Suite 400",
            "address2": "",
            "city": "Round Rock",
            "state": "TX",
            "zip": "78664",
            "countryID": 1
         }
      },
            {
         "lastName": "Lemon",
         "address":          {
            "address1": "700 Jeffrey Way, Suite 400",
            "address2": "",
            "city": "Round Rock",
            "state": "TX",
            "zip": "78665",
            "countryID": 1
         }
      }
   ],
   "count": 4,
   "start": 0
}


Returns the entities for the departments to which the current user belongs, for the following entity types: Candidate, ClientContact, ClientCorporation, JobOrder, Placement, and Note. For Candidate and Note requests, an _score field is included in each item returned; this is the Lucene search score.

HTTP Request

{corpToken}/department{Entity}s/?fields={fieldList}

Parameter Required Description
fields yes Comma-separated list of field names. fields or layout is required.
layout yes Name of a configured layout. fields or layout is required.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.
departmentIds no iComma-separated list of department ids. When not specified, the call returns entities from all of the user’s departments.
count no Limit on the number of entities to return. If the set of matched results is larger than the count value, the returned results is capped at the count value.

The default count is 20. The maximum count is 500; if you specify a count greater than 500, a message at the end of the response indicates you have specified too many items. The response also includes the actual number of items returned and the start value of the request. This is useful when you want to make calls to page additional sets of data. start | no | FFrom the set of matched results, returns item numbers start through (start + count). sort | no | Field to sort result on. Precede with minus sign to perform ascending search. Applies to Candidate and Note entities only. query | no | Lucene query string. Applies to Candidate and Note entities only. where | no | JPQL query string. Does not apply to Candidate or Note entities. meta | no | off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. showEditable | no | (true/false) Default value is false. Whether to show the _editable field in responses. The _editable field indicates whether an entity is editable. Setting showEditable to true results in slower performance; use this setting sparingly and only when needed.

My Entities

GET /department{Entity}s

curl https://rest.bullhornstaffing.com/rest-services/e999/myClientContacts?fields=firstName,lastName,address&start=0&count=5

# Example Response
{
   "data":    [
            {
         "lastName": "Burns",
         "address":          {
            "address1": "2 Olive Lane",
            "address2": "",
            "city": "Ridgefield",
            "state": "CT",
            "zip": "06877",
            "countryID": 1
         }
      },
            {
         "lastName": "Rackley",
         "address":          {
            "address1": "00 Jeffrey Way, Suite 400 |",
            "address2": "",
            "city": "Round Rock",
            "state": "TX",
            "zip": "78665",
            "countryID": 1
         }
      },
            {
         "lastName": "Smith",
         "address":          {
            "address1": "700 Jeffrey Way, Suite 400",
            "address2": "",
            "city": "Round Rock",
            "state": "TX",
            "zip": "78664",
            "countryID": 1
         }
      },
            {
         "lastName": "Lemon",
         "address":          {
            "address1": "700 Jeffrey Way, Suite 400",
            "address2": "",
            "city": "Round Rock",
            "state": "TX",
            "zip": "78665",
            "countryID": 1
         }
      }
   ],
   "count": 4,
   "start": 0
}


Returns the entities for which the current user is the owner, for the following entity types: Candidate, ClientContact, ClientCorporation, JobOrder, Placement, and Note. For Candidate and Note requests, an _score field is included in each item returned; this is the Lucene search score.

HTTP Request

{corpToken}/my{Entity}s/?fields={fieldList}

Parameter Required Description
fields yes Comma-separated list of field names. fields or layout is required.
layout yes Name of a configured layout. fields or layout is required.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.
departmentIds no iComma-separated list of department ids. When not specified, the call returns entities from all of the user’s departments.
count no Limit on the number of entities to return. If the set of matched results is larger than the count value, the returned results is capped at the count value.

The default count is 20. The maximum count is 500; if you specify a count greater than 500, a message at the end of the response indicates you have specified too many items. The response also includes the actual number of items returned and the start value of the request. This is useful when you want to make calls to page additional sets of data. start | no | From the set of matched results, returns item numbers start through (start + count). sort | no | Field to sort result on. Precede with minus sign to perform ascending search. Applies to Candidate and Note entities only. query | no | Lucene query string. Applies to Candidate and Note entities only. where | no | JPQL query string. Does not apply to Candidate or Note entities. meta | no | off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. showEditable | no | (true/false) Default value is false. Whether to show the _editable field in responses. The _editable field indicates whether an entity is editable. Setting showEditable to true results in slower performance; use this setting sparingly and only when needed.

Events

GET /event/subscription

curl https://rest.bullhornstaffing.com/rest-services/e999/event/subscription/Abcde?maxEvents=100

# Example Response
{{
    "requestId": 1,
    "events": [
        {
            "eventId": "ID:JBM-40000517",
            "eventType": "ENTITY",
            "eventTimestamp": 1495559294820,
            "eventMetadata": {
                "PERSON_ID": "1314",
                "TRANSACTION_ID": "c8d8f9ea-5ae6-4346-831c-29b91fcb703d"
            },
            "entityName": "ClientContact",
            "entityId": 8592,
            "entityEventType": "UPDATED",
            "updatedProperties": [
                "username",
                "password"
            ]
        }
    ]
}

Lets you get entity events, field map change events, and job match search events.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}

Parameter Required Description
maxEvents yes Integer specifying the maximum number of events to be returned.
requestId no Integer specifying an event requestId. Lets you reget events.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

HTTP Response

Field Description
eventID Unique identifier for the event.
eventMetaData Contains metadatata key/value pairs. PERSON_ID: User associated with the event. TRANSACTION_ID: For entities that have edit history, a TRANSACTION_ID represents a specific change that happened in the Bullhorn system, triggering an event in the subscription queue. TRANSACTION_IDs are returned as part of the subscription event data and can be used to associate a specific event to the state of a record at that stage.
eventTimestamp The date and time at which the event occurred.
entityEventType Integer specifying the maximum number of events to be returned.
eventType Always “ENTITY” for entity events.
entityID The unique identifier for the entity instance that was affected.
entityName The name of the entity that was affected.
updatedProperties If the event type is UPDATED, this parameter indicates which properties of the entity were modified.

GET /event/subscription/lastRequestId

curl https://rest.bullhornstaffing.com/rest-services/e999/event/subscriptioN/Abcde/lastRequestId

# Example Response
{'result': 1}

Lets you get entity events, field map change events, and job match search events.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}/lastRequestId

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /event/subscription

curl -X PUT \
     -H "Content-Type: application/json" \
     https://rest.bullhornstaffing.com/rest-services/e999/event/subscription/Abcde?type=entity&names=Candidate
&eventTypes=INSERTED,UPDATED,DELETED

# Example Response
{'lastRequestId': 0,
 'subscriptionId': 'abcde',
 'createdOn': 1335285871323,
 'jmsSelector': "JMSType='ENTITY' AND BhCorpId=44 AND BhEntityName='Candidate' AND BhEntityEventType IN ('UPDATED','INSERTED','DELETED')"}

Lets you subscribe to event types.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}

Parameter Required Description
type yes entity
names yes Required with “entity” type. A comma-separated list of entity names.
eventTypes yes RRequired with “entity” type. A comma-separated list of entity event types: INSERTED, UPDATED, DELETED.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /event/subscription

curl https://rest.bullhornstaffing.com/rest-services/e999/event/subscription/Abcde
&eventTypes=INSERTED,UPDATED,DELETED

# Example Response
{'result': True}

Lets you unsubscribe from event types.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

File

GET /file

curl https://rest.bullhornstaffing.com/e999/file/Candidate/3835/231

# Example Response
{"File": {
   "contentType": "text/plain",
   "fileContent": "VGhpcyBpcyBhIHZlcnkgc21hbGwgdGV4dCBmaWxlLg0KDQpTbWFsbFRleHRGaWxl",
   "name": "SmallFile.txt"
}}

Returns an attached file as base64-encoded text. Files can be attached to the following types of entities: * Candidate * ClientContact * ClientCorporation * JobOrder * Opportunity * Placement

HTTP Request

{corpToken}/file/{entityType}/{entityId}/{fileId}

Param Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

GET /entityFiles

curl https://rest.bullhornstaffing.com/e999/entityFiles/Candidate/203866

# Example Response
{"EntityFiles": [
      {
      "id": 201,
      "type": null,
      "name": "File1.txt",
      "description" : "Resume file for candidate.",
      "contentType": "text",
      "contentSubType": "plain"
   },
      {
      "id": 202,
      "type": null,
      "name": "File2.txt",
      "description": null,
      "contentType": "text",
      "contentSubType": "plain"
   }
]}

Returns metadata for attached files. Files can be attached to the following types of entities: * Candidate * ClientContact * ClientCorporation * JobOrder * Opportunity * Placement

HTTP Request

{corpToken}/entityFiles/{entityType}/{entityId}

Param Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /file


# Base64-encoded file request

curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"externalID" : "portfolio", "fileContent" : "VGhpcyBpcyBhIHZlcnkgc21hbGwgdGV4dCBmaWxlLg0KDQpTbWFsbFRleHRGaWxl", \
        "fileType" : "SAMPLE", "name" : "TestResumeFile.txt", "contentType" : "text/plain",\
        "description" : "Resume file for candidate.", "type" : "cover"}' \
     https://rest.bullhornstaffing.com/rest-services/e999/file/Candidate/5097909

# Multipart/form (raw) file request

curl -X PUT \
    -F "file=@samplefile.txt" \
    https://rest.bullhornstaffing.com/rest-services/e999/file/Candidate/5097909/raw?filetype=SAMPLE&externalID=portfolio

# Example Response
{"fileId": 178}

Attaches a file to an entity. You can send a file as base64-encoded text or multipart/form data (raw). Files can be attached to the following types of entities: * Candidate * ClientContact * ClientCorporation * JobOrder * Opportunity * Placement

HTTP Request for base64-encoded file

{corpToken}/file/{entityType}/{entityId}

Request body field Required Description
externalID yes External identifier for the file.
fileContent yes Base64-encoded string of the file content.
fileType yes Always use the value “SAMPLE”.
name yes File name.
contentType no Type/subtype of the file content.
description no Comment that describes the file.
type no Type of file that is attached.
Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

HTTP Request for multipart/form (raw) file

{corpToken}/file/{entityType}/{entityId}/raw

Parameter Required Description
externalID yes External identifier for the file.
fileType yes Always use the value “SAMPLE”.
name yes File name.
contentType no Type/subtype of the file content.
description no Comment that describes the file.
type no Type of file that is attached.BhRestToken

DELETE /file

curl -X DELETE \
     https://rest.bullhornstaffing.com/rest-services/e999/file/Candidate/3835/231

     # Example Response
{
   "fileId": 178,
   "changeType": "DELETED"
}

Soft deletes a file attachment. The actual file remains on the server.

HTTP Request

{corpToken}/file/{entityType}/{entityId}/{fileId}}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Find

GET /find

curl https://rest.bullhornstaffing.com/e999/find?query=smith&countPerEntity=3

# Example Response
{
    "data": [{
      "id" : 5059165,
      "firstName" : "Alanzo",
      "lastName" : "Smith"
    }]
}

FastFind is anized type of search that attempts to detect the kind of information contained in the search query. It then searches against entity fields that contain that type of information. Since FastFind attempts to detect the intent of a search query, it requires no special query language or syntax. Queries consist of only the words or numbers for which a user wants to search.

(FastFind) Searches the following entity types given a string containing search terms:

The results are returned in a flat list, with results from each entity type grouped together.

HTTP Request

{corpToken}/find?query={query-text}&countPerEntity={entity-max-results}

Parameter Required Description
query yes Text of search query.
countPerEntity no Maximum number of results to return for each entity type
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. For more information, see
showEditable no (true/false) Whether to show the editable field in responses. The editable field indicates whether an entity is editable. Default value is false.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Field type detection

FastFind classifies a search query as one of the following types depending of the structure of the text in the query:

FastFind performs classification by checking the query against the following patterns, in the order listed:

Query patterns

Email address

Any combination of a-z,A-Z,0-9,!,#,$,%, &, ’, *, +, -, /, =, ?, ^, _ or ` but not ., followed by @, followed by any combination of a-z, A-Z, 0-9, _, -, +, ., *

For example:

joe_smith@something-else.com or jon33@foo.bar

U.S. phone number

Three digits followed by any of [-.* or space, optionally followed by three more digits followed by [-.* or space, optionally followed by four digits.

For example:

23- or 123-456 or 123-456-7890

International phone number

Either of the following two patterns will match:

For example: +1-234-56*

For example:

1-234-567-8901

Entity ID

Only numeric characters For example: 1234567

Person or company name

One or more contiguous words that contain any combination of a-z, A-Z, 0-9, separated by any number of spaces. For multi-word queries, FastFind uses the first word to search the first name of Candidates and ClientContacts, and the remaining words to search the last name. FastFind searches JobOrders using the attached ClientContact names with the same rules.

Wildcards

You can use the * character as a wildcard inside or at the end of any word in a query.  Using a wildcard changes the fields that are searched for some entity types.  See the field type mappings table for details.

Query logic

The following table plots the fields that are searched for a given query classification and entity type:

Detected type Candidate Contact Corporation JobOrder Lead Opportunity
email email1
email2
email3
email1
email2
email3
  clientContact.email1
clientContact.email2
clientContact.email2

email1

email2

email3

 
phone phone
phone2
phone3
mobile
phone
phone2
phone3
mobile
phone
billingPhone
clientContact.phone
clientContact.phone2
clientContact.phone3
clientContact.mobile

 phone

phone2

phone3

mobile

ID id id id id id id
multi-word
name
firstName (first word)
lastName (remaining words)
firstName (first word)
lastName (remaining words)
name title (all words)
clientContact.firstName (first word)
clientContact.lastName (remaining words)
clientCorporation.name (all words)

firstName (first word)

middleName(second word, if 3 words)

lastName(second word, 3rd word if 3 words)

title (all words)

clientContact.firstName (first word)

clientContact.lastName (remaining words)

clientCoporation.name (all words)

single-word
name
lastName lastName name title
clientContact.lastName
clientCorporation.name
lastName

title

clientContact.lastName

clientCorporation.name

single-word
name with wildcard
firstName firstName name title
clientContact.firstName
clientCorporation.name
firstName

title

clientContact.firstName

clientCorporation.name

Login

Partner login using OAuth

curl https://rest.bullhornstaffing.com/login?access_token=xxx&version=*

# Example Response
{
  "BhRestToken" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "restUrl" : "https://rest.bullhornstaffing.com/rest-services/[corporation-token]/"
}

Log in and get a REST session. This is the only supported login process in a production environment.

Parameter Required Description
access_token yes Access token obtained from OAuth authorization
version yes Version of the API to use (* is a wildcard for latest version).
ttl no Session time-to-live in minutes.

Logout

curl https://rest.bullhornstaffing.com/e999/logout

# Example Response
{
    logout: "OK"
}

Log out and invalidate your REST session.

Lookup

GET /lookup

curl https://rest.bullhornstaffing.com/e999/lookup?filter=smith&entity=Candidate,ClientContact&start=0,10&count=10

# Example Response
{
    "data": [{
      "_score": 1.70002,
      "id" : 5059165,
      "firstName" : "Alanzo",
      "lastName" : "Smith"
    }]
}

curl https://rest.bullhornstaffing.com/e999/lookup/Candidate/12345

# Example Response
{
    "data": [{
      "id" : 5059165,
      "firstName" : "Alanzo",
      "lastName" : "Smith"
    }]
}

Searches using FastFind for FastFind-able entities, else uses custom Lucene or Hibernate queries. Returns a standardized set of data per EntityType.

Uses search implementations for:

Uses Hibernate queries for:

A call to search returns an _id, _entityType, and _label specific to each entity.

A details call returns a subset of the entity’s data. Each entity has a different set of data returned. This is the equivalent of a call which has had its fields parameter specified.

HTTP Requests

Lookup

../lookup?filter={terms}&entity={comma,separated,entity,names}&count={num}&start=one,number,per,entity

Lookup Details

../lookup/{entity}/{id}

Parameter Required Description
filter no The search terms, such as the name or title.
entity no A comma-separated list of entity names to search on using the given filter.
count no The total number of results to return.
start no A comma-separated list of start values for pagination of given entities. This list’s size should be the same as the length of the entity parameter. Defaults to 0.
privateLabelID no The private label id to use.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Mass Update

GET /massUpdate

curl https://rest.bullhornstaffing.com/e999/massUpdate

# Example Response
[
"Candidate",
"ClientContact",
"ClientCorporation",
"JobOrder",
"JobSubmission",
"Lead",
"NPSUserInfo",
"Opportunity",
"Placement",
"Task",
"Tearsheet"
]

Returns the list of entity types that support mass update.

HTTP Request

{corpToken}/massUpdate/{entityType}

Param Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

GET /massUpdate/{entityType}

curl https://rest.bullhornstaffing.com/e999/massUpdate/entity

# Example Response
[ {
  "propertyName" : "assignedUsers",
  "entitlementRequired" : "Mass Update Job Assignment"
}, {
  "propertyName" : "isDeleted",
  "entitlementRequired" : "Mass Delete Job"
}, {
  "propertyName" : "isOpen",
  "entitlementRequired" : "Mass Open/Close Job"
}, {
  "propertyName" : "owner",
  "entitlementRequired" : "Mass Update Job Owner"
}, {
  "propertyName" : "status",
  "entitlementRequired" : "Mass Update Job Status"
} ]

Returns the list of entity properties for which mass update is supported on the specified entity type. Also returns the entitlement required for updating each property.

HTTP Request

{corpToken}/massUpdate/{entityType}

Param Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /massUpdate/{entityType}

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"ids": [789,790], "status": "active"}' \
     https://rest.bullhornstaffing.com/e999/massUpdate/JobOrder

# Example Response
{
    "count": 2
}

Performs a massUpdate on all entities of the specified type for which the entity id is included in the request body. The request body uses the following syntax:

{
  "ids" : [id, id, id],
  "{property}" : value,
  "toOneProperty" : id,
  "{toManyProperty}" : [ id, id, id],
  "{toManyProperty}" : {
                       "add" : [id, id, id],
                       "remove" : [id, id, id]
                     }
}

The response contains the count of updated entities: { "count" : n }

Meta

GET /meta

curl https://rest.bullhornstaffing.com/rest-services/e999/meta

# Example Response
[
    {
        "entity": "Appointment",
        "metaUrl": "https://rest.bullhornstaffing.com/rest-services/e999/meta/Appointment?fields=*"
    },
    {
        "entity": "BusinessSector",
        "metaUrl": "https://rest.bullhornstaffing.com/rest-services/e999/meta/BusinessSector?fields=*"
    },
    {
        "entity": "Candidate",
        "metaUrl": "https://rest.bullhornstaffing.com/rest-services/e999/meta/Candidate?fields=*"
    },
    {
        "entity": "Category",
        "metaUrl": "https://rest.bullhornstaffing.com/rest-services/e999/meta/Category?fields=*"
    },
    {
        "entity": "ClientContact",
        "metaUrl": "https://rest.bullhornstaffing.com/rest-services/e999/meta/ClientContact?fields=*"
    },
    {
        "entity": "ClientCorporation",
        "metaUrl": "https://rest.bullhornstaffing.com/rest-services/e999/meta/ClientCorporation?fields=*"
    },
    ...
]

Calling /meta with no entity name will return the list of available entities and their respective base URLs.

Read-only system fields ( fields with names prefixed with _ ) are not represented in entity metadata ever, even with * calls.

GET /meta/{Entity}

curl https://rest.bullhornstaffing.com/e999/meta/Candidate?fields=*
# Example Response
{
  "entity" : "Candidate",
  "entityMetaUrl" : "https://rest.bullhornstaffing.com/e999/meta/Candidate?fields=*",
  "label" : "Candidate",
  "fields" : { {
    "name" : "id",
    "type" : "ID",
    "dataType" : "Integer"
  }, {
    ...
  }]
}

Returns entity and property metadata for the specified entity type.

HTTP Request

GET {corporation-token}/meta/{entity-name}/?fields={field-list}&meta={ basic or full }

Parameter Required Description
fields yes Comma-separated list of field names.
layout yes Name of a configured layout. A field list, layout name or both may be specified.
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. For more information, see
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Property Metadata

name

Property name; for example, firstName.

label

Property display label from fieldmap; may be missing.

type

Property type, one of ID, SCALAR, COMPOSITE, TO_ONE, or TO_MANY.

dataType

Property data type: Integer, BigDecimal, Double, String, Boolean, Timestamp, byte[], Address, Address1, AddressWithoutCountry (these are composite types), and LoginRestrictions (!! may change).

maxLength

Only present when dataType=“String”. The maximum authorized length for this String field.

dataSpecialization

Finer definition of dataType, e.g. dateType=Timestamp and dataSpecialization=DATE one of NUMERIC, INTEGER, FLOAT, MONEY, PERCENTAGE, PHONE, SSN, HTML, DATE, TIME, DATETIME, COLOR, SYSTEM, or VIRTUAL: may be absent.

optional

Is the property value optional (specified by Hibernate, typically means database nullability); also see required.

required

Is the property value required (specified by fieldmap); also see optional.

readonly

Is the property hidden (specified by fieldmap).

multiValue

Is the property multi-valued (specified by fieldmap); dataType must be String.

inputType

Suggested input type: CHECKBOX, RADIO, TEXTAREA, or SELECT; may be missing.

optionsType

For inputType SELECT only; for example, Country. may be missing.

optionsUrl

If optionsType is present, where to get the list of options (displays and values).

options

The hard-coded options from fieldMap in an array of value/label pairs; may be missing.

defaultValue

Value type depends on dataType and dataSpecialization: may be missing.
If the defaultValue is not translatable, For example, cannot parse string to a date; it is ignored. If multiValue, returns as array.

fields

Array of sub-fields property meta for COMPOSITE type.

associatedEntity

Entity metadata for TO_ONE and TO_MANY type.

Options

GET /options

curl https://rest.bullhornstaffing.com/e999/options

# Example Response
{
  "data" : [ {
    "optionsType" : "BillRateCategory",
    "optionsUrl" : "https://rest.bullhorn.com/rest-services/e999/options/BillRateCategory"
  }, {
    "optionsType" : "BusinessSector",
    "optionsUrl" : "https://rest.bullhorn.com/rest-services/e999/options/BusinessSector"
  }, {
    "optionsType" : "BusinessSectorText",
    "optionsUrl" : "https://rest.bullhorn.com/rest-services/e999/options/BusinessSectorText"
  }, {
    "optionsType" : "Candidate",
    "optionsUrl" : "https://rest.bullhorn.com/rest-services/e999/options/Candidate"
  }, {
    "optionsType" : "CandidateText",
    "optionsUrl" : "https://rest.bullhorn.com/rest-services/e999/options/CandidateText"
  },
...
]

Gets the list of supported option types (value/label pairs) for list-based entities.

HTTP Request

{corpToken}/options

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

GET /options/{optionsType}

curl https://rest.bullhornstaffing.com/e999/options/Country

# Example Response
{
{"data": [
      {
      "value": 2378,
      "label": "- None Specified -"
   },
      {
      "value": 2185,
      "label": "Afghanistan"
   },
...
          ]
    }
}

Gets the list of value/label pairs (options) for a list-based entity. If the option is of type text, a list of input value/label pairs is returned where the label is set to the input value.

HTTP Request

{corpToken}/options//{optionType}

or:

{corpToken}/options//{optionType}/value1,*}

Parameter Required Description
filter no Filter on the label, prefix with an asterisk (*) to find word begins. For example, filter=foo returns all options where label starts with “foo”, such as “Fool”. filter=*foo returns all options where any word in the label starts with “foo”, such as “A Fool”. Some labels are composed of two or more parts. For example, a name is composed of firstname and lastname separated by a space. In these cases, filtering is based on each part of the label. For example, filter=Ba, will find any part of a label that starts with Ba. Therefore, the results could include “Bailey Hutchinson” as well as “Sam Bailey”.
type-specific parameters no Some option types accept additional parameters. For example, State has an optional “country” parameter.
count no Limit on the number of entities to return. If the set of matched results is larger than count, caps the returned results at size count. The default count is 20. The maximum count is 300; if you specify a count greater than 300, a message at the end of the response indicates you have specified too many items.
start no From the set of matched results, return item numbers start through (start + count).
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Option Types List

Option type Description
BillRateCategory Same as Category where type = ‘Bill Rate’
BusinessSector / BusinessSectorText BusinessSector id and name / name and name
Candidate / CandidateText Candidate id and firstName + lastName / firstName + lastName, and firstName + lastName
Category / CategoryText Category id and name / name and name; Extra params: optional “type” to restrict categories of type
Certification / CertificationText Certification id and name / name and name
Client / ClientText (alias ClientContact / ClientContactText) ClientContact id and firstName + lastName / firstName + lastName and firstName + lastName
ClientCorporation / ClientCorporationText ClientCorporation id and name / name and name
CorporateUser / CorporateUserText CorporateUser id and firstName + lastName / firstName + lastName and firstName + lastName
CorporationDepartment CorporationDepartment id and name
Country Country id and name
HousingAmenity HousingComplexAmenity id and amenityName / amenityName and amenityName
HousingComplex /HousingComplexText HousingComplex id and name / name and name
HousingComplexUnit /HousingComplexUnitText HousingComplexUnit id and name / name and name
JobOrder / JobOrderText JobOrder id and title / title and title
Lead Lead id and firstName + lastName
Opportunity Opportunity id and title
Placement Placement id and candidate.firstName candidate.lastName - jobOrder.title
Person / PersonText Person id and firstName + lastName / firstName + lastName and firstName + lastName
Shift / ShiftText Shift id and name / name and name
Skill / SkillText Skill id and name / name, and name
Specialty / SpecialtyText Specialty id and name / name, and name
State / StateText State id and name / name and name; extra parameters: optional “country” to restrict to states within that country, two-character ISO country code.
NorthAmericaState State id and name (hard-coded)
WorkersComp WorkersCompensation id and name / name and name

Ping

GET /ping

curl https://rest.bullhornstaffing.com/e999/ping

# Example Response
{
  "sessionExpires" : 1323449994922
}

Returns the date of the calling client’s session expiration. You can use this call to test whether the client’s session is valid. If the session is not valid, the response is the standard response for unauthenticated clients.

Parameter Required Description
BhRestToken true Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Query

GET /query

curl https://rest.bullhornstaffing.com/e999/query/Candidate?fields=firstName,lastName&where=lastName='smith'&count=3

# Example Response
{
    "data": [{
        "id" : 5059165,
        "firstName" : "Alanzo",
        "lastName" : "Smith"
    }]
}

Retrieves a list of entities. The query is performed against the database. The where parameter accepts Java Perstance Language (JPQL) syntax, which is similar SQL syntax. Access the data via that database is only performant when you query very specific data. Otherwise it is preferred that you use the Search call if it is available for the entity type for which you want to search.

HTTP Request

{corpToken}/query/{entity}?where={query-text}&fields={fields}&orderBy={fields}&count={count}&start={start}

Parameter Required Description
where yes SQL-style filter clause
fields yes* Comma-separated list of field names. Use fields or layout, but not both.
layout yes* Name of a configured layout. Use fields or layout, but not both.
showReadOnly no (true/false) Whether to show read-only fields. Only applies when the layout parameter is used.
count no Limit on the number of records to return. If the set of matched results is larger than count, cap the returned results at size count.
start no From the set of matched results, return record numbers start through (start + count)
orderBy no Name of property on which to base the order of returned entities.
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data.
showEditable no (true/false) Whether to show the _editable field in responses. The _editable field indicates whether an entity is editable. Default value is false.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Query where parameter

You can use the following syntax in the where query parameter:

Simple comparisons

property = value property <> value property < value property <= value property > value property >= value

May use compound property names (not for to-many properties)

owner.lastName = ‘Smith’ owner.corporation.name = 'Acme’

IS [NOT] NULL

property IS NULL property IS NOT NULL

IS [NOT] EMPTY (only for to-many properties)

categories IS EMPTY categories IS NOT EMPTY

[NOT] IN

property IN (value, value) property NOT IN (value, value)

[NOT] MEMBER OF (only for to-many properties)

id-value MEMBER OF categories id-value NOT MEMBER OF categories

Logical Expressions: NOT, AND, OR

predicate AND predicate predicate OR predicate NOT predicate

Grouping by parentheses

predicate AND ( predicate OR predicate ) (( predicate OR predicate ) AND NOT ( predicate OR predicate )) OR predicate  

Boolean values

true | false Examples enabled = true willingToRelocate = false

Datetime values

Resume

POST /resume/parseToCandidate

curl -X POST \
     -F "file=@sampleresume.html" \
     https://rest.bullhorn.com/rest-services/e999/resume/parseToCandidate?format=text&populateDescription=html

# Example Response
{
   "candidate":    {
      "address":       {
         "address1": "123 Osoite Katu",
         "address2": "Apartment 1",
         "city": "Kaupunki",
         "state": "MA",
         "zip": "02210",
         "countryID": 1
      },
        "description": "<html xmlns=\"http://www.w3.org/1999/xhtml\">\r\n\t<head>\r\n\t\t \
        <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" \
         />\r\n\t\t<meta http-equiv=\"Content-Style-Type\" content=\"text/css\" /> \
         \r\n\t\t\r\n\t</head>\r\n\t<body>\r\n\t\t<div>\r\n\t\t\t<p style=\"margin-top:0pt; \
         margin-bottom:0pt; text-indent:36pt; text-align:center; font-size:11pt\"> \
         \r\n\t\t\t\t<span style=\"font-family:Calibri\">Dr. Minun Keskimm\u00e4inen Nimi</span></p>"
   ...
   },
   "candidateEducation":    [
            {
         "startDate": 978368400000,
         "endDate": 1104598800000,
         "graduationDate": 1104598800000,
         "school": "Berkeley State University",
         "city": "Santa Cruz",
         "state": "CA",
         "degree": "B.Sc",
         "major": "COMPUTER SCIENCE",
         "gpa": 4
      }
   ],
   "candidateWorkHistory":    [
            {
         "startDate": 1015002000000,
         "endDate": 1188662400000,
         "comments": "MA    Bop  Hop  Hip"
      }
      }
   ]
}

The parseToCandidate operation parses a resume to unsaved Candidate data. A typical use case for this operation is to use parts of the response in the bodies of calls to create new Candidate, CandidateWorkHistory, and CandidateEducation entities. The parseToCandidate operation lets you send a resume as a file attached as multipart/form-data. The parseToHrXml operation sends a resume as a file attached as multipart/form-data. The attached file must be a non-base64-encoded file. Takes one file per request. To send a block of text rather than a file, use the parseToCandidateViaJson operation.

HTTP Request

{corpToken}/resume/parseToCandidate

Parameter Required Description
format yes Input format for the resume. Value can be html or text.
populateDescription no Including this parameter fills the Candidate description field with the text or html format of the resume. Value must be text or html. The primary use case for this parameter is to send the resume in the description field for a new Candidate in a PUT /entity/Candidate call. The text or HTML content returned in the description field of the response is JSON-encoded. When the resume is used in a request body, it must be JSON-encoded. If you have parsed the response to an object for manipulation, you must re-encode the value of the “description” as JSON before using it in a request body of another call. For example, in Groovy you can use the groovy.json.JsonOutput.toJson(java.lang.String s) method to Json-encode a string.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /resume/parseToCandidateViaJson

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"resume" : "\r\n\r\nDr. Minun Keskimm\u00E4inen Nimi\r\n123 Osoite Katu\r\nApartment 1\r\nKaupunki, MA 02210\r\nHome: 466-346-4663 \u00A0Business: 387-438-3874 ext. 89 \u00A0Mobile: 662-466-6624\r\nTelephone: 835-383-8353 ext. 90 \u00A0VoiceNumber: 864-386-8643\r\nFax: 329-329-3290 \u00A0Pager: 724-772-7247\r\nMinun.Nimi@finland.com ...}' \
     \
     https://rest.bullhorn.com/rest-services/e999/resume/parseToCandidateViaJson?format=text&populateDescription=html

# Example Response
{
   "candidate":    {
      "address":       {
         "address1": "123 Osoite Katu",
         "address2": "Apartment 1",
         "city": "Kaupunki",
         "state": "MA",
         "zip": "02210",
         "countryID": 1
      },
        "description": "<html xmlns=\"http://www.w3.org/1999/xhtml\">\r\n\t<head>\r\n\t\t \
        <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" \
         />\r\n\t\t<meta http-equiv=\"Content-Style-Type\" content=\"text/css\" /> \
         \r\n\t\t\r\n\t</head>\r\n\t<body>\r\n\t\t<div>\r\n\t\t\t<p style=\"margin-top:0pt; \
         margin-bottom:0pt; text-indent:36pt; text-align:center; font-size:11pt\"> \
         \r\n\t\t\t\t<span style=\"font-family:Calibri\">Dr. Minun Keskimm\u00e4inen Nimi</span></p>"
   ...
   },
   "candidateEducation":    [
            {
         "startDate": 978368400000,
         "endDate": 1104598800000,
         "graduationDate": 1104598800000,
         "school": "Berkeley State University",
         "city": "Santa Cruz",
         "state": "CA",
         "degree": "B.Sc",
         "major": "COMPUTER SCIENCE",
         "gpa": 4
      }
   ],
   "candidateWorkHistory":    [
            {
         "startDate": 1015002000000,
         "endDate": 1188662400000,
         "comments": "MA Bop Hop Hip"
      }
      }
   ]
}

The parseToCandidateViaJson operation parses a resume to unsaved Candidate data. A typical use case for this operation is to use parts of the response in the bodies of calls to create new Candidate, CandidateWorkHistory, and CandidateEducation entities. The parseToCandidateViaJson operation lets you send a resume as JSON-encoded text, which is useful for scenarios where you want to parse a block of text rather than a file.

HTTP Request

{corpToken}/resume/parseToCandidateViaJson

Parameter Required Description
format yes Input format for the resume. Value can be html or text.
populateDescription no Including this parameter fills the Candidate description field with the text or html format of the resume. Value must be text or html. The primary use case for this parameter is to send the resume in the description field for a new Candidate in a PUT /entity/Candidate call. The text or HTML content returned in the description field of the response is JSON-encoded. When the resume is used in a request body, it must be JSON-encoded. If you have parsed the response to an object for manipulation, you must re-encode the value of the “description” as JSON before using it in a request body of another call. For example, in Groovy you can use the groovy.json.JsonOutput.toJson(java.lang.String s) method to Json-encode a string.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /resume/parseToHrXml

curl -X POST \
     -F "file=@sampleresume.pdf" \
     https://rest.bullhorn.com/rest-services/e999/resume/parseToHrXml?format=pdf
# Example Response
{"hrXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Resume \
 xmlns=\"http://ns.hr-xml.org\" xmlns:hr=\"http://ns.hr-xml.org/PersonDescriptors\" \
 xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xml:lang=\"ENGLISH\">\n \
 <ResumeId idOwner=\"Resume Mirror\">\n \
 <IdValue name=\"RESUME ID\"/>\n  <\/ResumeId>\n  <StructuredXMLResume>\n \
 <ContactInfo>\n <PersonName>\n \
 <FormattedName>Dr. Minun Keskimmäinen Nimi<\/FormattedName>\n <GivenName>Minun<\/GivenName>\n  \
 <MiddleName>Keskimmäinen<\/MiddleName>\n <FamilyName>Nimi<\/FamilyName>\n  \
 <Affix type=\"formOfAddress\">DR.<\/Affix>\n  <\/PersonName>\n <ContactMethod>\n  \
 /UserArea>\n<\/Resume>"}

The parseToHrXml operation sends a resume as a file attached as multipart/form-data. The attached file must be a non-base64-encoded file. Takes one file per request.

{corpToken}/resume/parseToXrXml

Parameter Required Description
format yes Input format for the resume. Value can be text, html, pdf, doc, docx, rtf, or odt.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /resume/parseToHrXmlViaJson

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"resume" : "\r\n\r\nDr. Minun Keskimm\u00E4inen Nimi\r\n123 \
     Osoite Katu\r\nApartment 1\r\nKaupunki, MA 02210\r\nHome: 466-346-4663 \
     \u00A0Business: 387-438-3874 ext. 89 \u00A0Mobile: 662-466-6624\r\n \
     Telephone: 835-383-8353 ext. 90 \u00A0VoiceNumber: 864-386-8643\r\n \
     Fax: 329-329-3290 \u00A0Pager: 724-772-7247\r\nMinun.Nimi@finland.com ...}' \
     \
     https://rest.bullhorn.com/rest-services/e999/resume/parseToHrXmlViaJson?format=text&format=html

# Example Response
{"hrXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Resume \
 xmlns=\"http://ns.hr-xml.org\" xmlns:hr=\"http://ns.hr-xml.org/PersonDescriptors\" \
 xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xml:lang=\"ENGLISH\">\n \
 <ResumeId idOwner=\"Resume Mirror\">\n \
 <IdValue name=\"RESUME ID\"/>\n  <\/ResumeId>\n  <StructuredXMLResume>\n \
 <ContactInfo>\n <PersonName>\n \
 <FormattedName>Dr. Minun Keskimmäinen Nimi<\/FormattedName>\n <GivenName>Minun<\/GivenName>\n  \
 <MiddleName>Keskimmäinen<\/MiddleName>\n <FamilyName>Nimi<\/FamilyName>\n  \
 <Affix type=\"formOfAddress\">DR.<\/Affix>\n  <\/PersonName>\n <ContactMethod>\n  \
 /UserArea>\n<\/Resume>"}

The parseToHrXmlViaJson operation send plain text or HTML as a JSON-encoded string. This call is useful for sending resume content that a user pastes into a browser form.

HTTP Request

{{corpToken}/resume/parseToHrXmlViaJson

Parameter Required Description
format yes Input format for the resume. Value can be html or text.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /resume/convertToText|Html

curl -X POST \
     -F "file=@sampleresume.pdf" \
     https://rest.bullhornstaffing.com/rest-services/e999/resume/convertToHtml?format=pdf

# Example Response
{
  "html" : "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0//EN\">\r\n<html>\r\n<head>\r\n\
     <title></title>\r\n    <meta name=\"Author\" content=\"RB\" />\r\n    \
     <meta http-equiv=\"content-type\" content=\"text/html; charset=UTF-16\" />\r\n \
     </head>\r\n<body>\r\n<div align=\"center\"><br /> \
     <font face=\"Times New Roman\" size=\"3\"> \
     Dr. Minun Keskimmäinen Nimi</font>\n<br /><font face=\"Times New Roman\" \
     size=\"3\">123 Osoite&nbsp;Katu</font>\n \
     <br /><font face=\"Times New Roman\" size=\"3\">Apartment 1</font>\n \
     <br /><font face=\"Times New Roman\" size=\"3\"> \
     Kaupunki, MA 02210</font>\n<br /><font face=\"Times New Roman\" size=\"3\"> \
     Home: 466-346-4663  Business: 387-438-3874 ext. 89  Mobile: \
      662-466-6624 </font>\n<br />
...
<font face=\"Times New Roman\" size=\"3\"> \
Dean s List: Fall 2005 and Spring 2006</font>\n<br /> \
&nbsp;<br />&nbsp;</body>\r\n</html>"
}

The convertToText|Html operations converts a resume to JSON-encoded plain text or HTML text. A typical use case for this operation is to use the converted resume in the body of a call to update a Candidate description.

When the resume text in the response is used in a request body of another call, it must be JSON-encoded. If you have parsed the response to an object for manipulation, you must re-encode the resume as JSON before using it in the request body of another call. For example, in Groovy you can use the groovy.json.JsonOutput.toJson(java.lang.String s) method to Json-encode a string.

{corpToken}/resume/convertToText|Html

Parameter Required Description
format yes Input format for the resume. Value can be text, html, pdf, doc, docx, rtf, or odt.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /resume/convertToText|HtmlViaJson

The value of the “resume” field must be JSON-encoded text. Most programming languages provide utility classes for generating JSON-encoded text.

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"resume" : "\r\n\r\nDr. Minun Keskimm\u00E4inen Nimi\r\n123 Osoite Katu\r\nApartment 1\r\nKaupunki, MA 02210\r\nHome: 466-346-4663 \u00A0Business: 387-438-3874 ext. 89 \u00A0Mobile: 662-466-6624\r\nTelephone: 835-383-8353 ext. 90 \u00A0VoiceNumber: 864-386-8643\r\nFax: 329-329-3290 \u00A0Pager: 724-772-7247\r\nMinun.Nimi@finland.com ...}' \
     \
     https://rest.bullhorn.com/rest-services/e999/resume/convertToTextViaJson?format=html

# Example Response
{"text": "\r\n\r\nDr. Minun Keskimmäinen Nimi\r\n123 Osoite Katu\r\nApartment 1\r\nKaupunki, \
 MA 02210\r\nHome: 466-346-4663  Business: 387-438-3874 ext. 89  Mobile: 662-466-6624\r\n \
 Telephone: 835-383-8353 ext. 90  VoiceNumber: 864-386-8643\r\nFax: 329-329-3290  \
 Pager: 724-772-7247\r\nMinun.Nimi@finland.com            \
 mnimi2@finland2.com\r\n\r\nEmployment History\r\n\r\n  Eighties National Music Bank \
 Lexington, MA Jan. 1, 1980 - Dec. 31, 1989 \r\n  New Wave Musak Software Engineer\r\n\r\n \
 Listen\r\nLike\r\nLearn\r\n\r\n \r\n  Nineties Bank of Music  \
 Concord, MA  February 1991 - November 1998 \r\n Hip Hop 
...
"}

The convertToText|HtmlViaJson operations convert a resume to JSON-encoded plain text or HTML text. A typical use case for this operation is to use the converted resume in the body of a call to update a Candidate description. When the resume text in the response is used in a request body of another call, it must be JSON-encoded. If you have parsed the response to an object for manipulation, you must re-encode the resume as JSON before using it in the request body of another call. For example, in Groovy you can use the groovy.json.JsonOutput.toJson(java.lang.String s) method to Json-encode a string.

When the resume text in the response is used in a request body of another call, it must be JSON-encoded. If you have parsed the response to an object for manipulation, you must re-encode the resume as JSON before using it in the request body of another call. For example, in Groovy you can use the groovy.json.JsonOutput.toJson(java.lang.String s) method to Json-encode a string.

{corpToken}/resume/convertToText|HtmlViaJson

Parameter Required Description
format yes Input format for the resume. Value can be text or html.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Saved Search

GET /savedSearch

curl https://rest.bullhornstaffing.com/e999/savedSearch

or:

curl https://rest.bullhorn.com/rest-services/e999/savedSearch?entity=Candidate&entityId=20

# Example Response
{
  "data" : {
    "id" : 3,
    "name" : "nnn_candidate",
    "description" : "my description",
    "indexType" : "CANDIDATE",
    "data" : "data",
    "query" : "name:lv_",
    "ownerId" : 1314,
    "dateAdded" : "2013-01-31",
    "favorite" : false
  }, {
    "id" : 2,
    "name" : "nnn_job",
    "description" : "my description",
    "indexType" : "JOBORDER",
    "data" : "data",
    "query" : "name:lv_",
    "ownerId" : 1314,
    "dateAdded" : "2013-01-31",
    "favorite" : false
  } ],
  "start" : 0,
  "count" : 2
}

The savedSearch operation with no {savedSearchId} path parameter and no query parameters returns all saved searches in the user’s corporation to which the user has entitlements. Use the entity and entityId parameters to return the saved searches associated with a specific entity.

HTTP Request

{corpToken}/savedSearch

Param | Required | Description type | no | Returns only saved searches of the specified index type. entity & entitId | no | Returns only saved searches associated with the specified entity. Both parameters must be present. For information about associating a savedSearch with a specific entity, see PUT /savedSearchAssociation. start | no | From the set of matched results, returns item numbers start through (start + count). count | no | Limit on the number of items to return. If the set of matched results is larger than count, caps the returned results at size count. orderBy | no | Value can be id or name. Precede field name with a minus sign (-) or plus sign (+) to sort results in descending or ascending order based on that field; default value is “-id”. showTotalMatched | no | Default value is false. Displays count of matching records. BhRestToken | no | Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

GET /mySavedSearch

curl https://rest.bullhornstaffing.com/e999/mySavedSearch

or:

curl https://rest.bullhorn.com/rest-services/e999/mySavedSearch?entity=Candidate&entityId=20

# Example Response
{
  "data" : {
    "id" : 2,
    "name" : "nnn_job",
    "description" : "my description",
    "indexType" : "JOBORDER",
    "data" : "data",
    "query" : "name:lv_",
    "ownerId" : 1314,
    "dateAdded" : "2013-01-31",
    "favorite" : false
  } ],
  "start" : 0,
  "count" : 3
}

The mySavedSearch operation returns all saved searches that the user owns.

HTTP Request

{corpToken}/mySavedSearch

Param | Required | Description type | no | Returns only saved searches of the specified index type. entity & entitId | no | Returns only saved searches associated with the specified entity. Both parameters must be present. For information about associating a savedSearch with a specific entity, see PUT /savedSearchAssociation. start | no | From the set of matched results, returns item numbers start through (start + count). count | no | Limit on the number of items to return. If the set of matched results is larger than count, caps the returned results at size count. orderBy | no | Value can be id or name. Precede field name with a minus sign (-) or plus sign (+) to sort results in descending or ascending order based on that field; default value is “-id”. showTotalMatched | no | Default value is false. Displays count of matching records. BhRestToken | no | Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

GET /savedSearch/{savedSearchId}

curl https://rest.bullhornstaffing.com/e999/esavedSearch/4

# Example Response
{
  "data" : {
    "id"          : savedSearchId,
    "name"        : "general_ search",
    "description" : "my acme query",
    "indexType"   : "JOBORDER",
    "data"        : "data",
    "query"       : "name:acme”
    "ownerId"     : 1222,
    "dateAdded"   : "2013-01-31",
    "favorite"    : true
  }
}

Gets a saved Lucene search for any entity type for which the search operation is supported.

HTTP Request

{corpToken}/savedSearch/{savedSearchId}

Param | Required | Description BhRestToken | no | Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /savedSearch

curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"name"        : "my_note_search", \
        "description" : "my description", \
        "indexType"   : "NOTE", \
        "data"        : "data", \
        "query"       : "name:pinacle" \
        } \
       ' \
     https://rest.bullhornstaffing.com/e999/savedSearch

# Example Response
{
    "changedEntityType": "SavedSearch",
    "changedEntityId": 4,
    "changeType": "INSERT",
    "data": {

    }
}

Creates a saved Lucene search for a Lucene-indexed entity type. The name, indexType, data, and query fields are required in the request body. The user who creates a saved search always gets entitlements for all operations on that saved search; for more information about entitlements, see PUT /savedSearchGrant.

HTTP Request

{corpToken}/savedSearch/{savedSearchId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /savedSearch/{savedSearchId}

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name"        : "my_note_search", \
        "description" : "my description", \
        "indexType"   : "NOTE", \
        "data"        : "data", \
        "query"       : "name:pinacle" \
        } \
       ' \
     https://rest.bullhornstaffing.com/e999/savedSearch/4

# Example Response
{
    "changedEntityType": "SavedSearch",
    "changedEntityId": 4,
    "changeType": "UPDATE",
    "data": {

    }
}

Updates a saved Lucene search for Lucene-indexed entity types. The following fields are optional in the request body: name, description, indexType, data, and query.

HTTP Request

{corpToken}/savedSearch/{savedSearchId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /savedSearch/{savedSearchId}

curl -X DELETE \
https://rest.bullhornstaffing.com/e999/esavedSearch/4

# Example Response
TBD
{
    "changedEntityType": "SavedSearch",
    "changedEntityId": 4,
    "changeType": "DELETE",
    "data": {

    }
}

Deletes a saved Lucene search for any entity type for which the search operation is supported.

HTTP Request

{corpToken}/savedSearch/{savedSearchId}

Param | Required | Description BhRestToken | no | Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /savedSearchAssociation

curl -X PUT \
     https://rest.bullhornstaffing.com/e999/savedSearchAssociation/4/JobOrder/1495    

Creates an association between a saved search and a specified entity id.

HTTP Request

{corpToken}/savedSearchAssociation/{savedSearchId}/{entityName}/{entityId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /savedSearchAssociation

curl -X DELETE \
     https://rest.bullhornstaffing.com/e999/savedSearchAssociation/4/JobOrder/1495    

Deletes an association between a saved search and a specified entity id.

HTTP Request

{corpToken}/savedSearchAssociation/{savedSearchId}/{entityName}/{entityId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

GET /savedSearchGrants

curl https://rest.bullhorn.com/rest-services/e999/savedSearchGrants/4

# Example Response
[
  { "type"="CORP", "targetId"=null},
  { "type"="DEPT", "targetId"=12},  
  { "type"="USER", "targetId"=1333}
]

Returns entitlements for a saved search.

HTTP Request

{corpToken}/savedSearchGrants

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /savedSearchGrant

curl https://rest.bullhorn.com/rest-services/e999/savedSearchGrant/4/CORP

Deletes entitlements for a saved search.

HTTP Request

{corpToken}/savedSearchGrant/{savedSearchId}/CORP 
{corpToken}/savedSearchGrant/{savedSearchId}/DEPT/{departmentId} 
{corpToken}/savedSearchGrant/{savedSearchId}/USER/{corporateUserId} 
Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

FAVORITES

PUT /savedSearchFavorite

curl -X PUT \
     https://rest.bullhornstaffing.com/e999/savedSearchFavorite/4

Adds a saved search to saved search favorites.

HTTP Request

{corpToken}/savedSearchFavorite/{savedSearchId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /savedSearchAssociation

curl -X DELETE \
     https://rest.bullhornstaffing.com/e999/savedSearchAssociation/4/JobOrder/1495    

Deletes an association between a saved search and a specified entity id.

HTTP Request

{corpToken}/savedSearchAssociation/{savedSearchId}/{entityName}/{entityId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /savedSearchFavorite

curl -X PUT \
     https://rest.bullhornstaffing.com/e999/savedSearchFavorite/4

Adds a saved search to saved search favorites.

HTTP Request

{corpToken}/savedSearchFavorite/{savedSearchId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /savedSearchFavorite

curl -X DELETE \
     https://rest.bullhornstaffing.com/e999/savedSearchFavorite/4

Removes a saved search from saved search favorites.

HTTP Request

{corpToken}/savedSearchFavorite/{savedSearchId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Search

curl https://rest.bullhornstaffing.com/e999/search/Candidate?query=lastName:Smith&fields=id,firstName,lastname&count=3

# Example Response
{
    "data": [{
      "_score": 1.70002,
      "id" : 5059165,
      "firstName" : "Alanzo",
      "lastName" : "Smith"
    }]
}

Retrieves a list of entities. The search call is performed against a optimized index, therefore the query parameter should reflect Lucene Query Syntax. For information about the Lucene query syntax, see: Lucene Tutorial

Note that the response contains a _score field. This is the Lucene score. Also, if the database record for an entity id is missing, the response contains an _error field for that record.

curl https://rest.bullhornstaffing.com/e999/search/Candidate?query=isDeleted:0

# Example Response
{
    "data": [101,102,103,104,...,999]
}

HTTP Request

{corpToken}/search/{entity}?query={lucene}&fields={fields}&orderBy={fields}&count={count}&start={start}

Parameter Required Description
query yes Lucene-Style filter clause.
fields yes* Comma-separated list of field names. Use fields or layout, but not both.
layout yes* Name of a configured layout. Use fields or layout, but not both.
showReadOnly no (true/false) Whether to show read-only fields. Only applies when the layout parameter is used.
count no Limit on the number of records to return. If the set of matched results is larger than count, cap the returned results at size count.
start no From the set of matched results, return record numbers start through (start + count)
sort no Field to sort result on. Default sort order is ascending. Precede with minus sign to perform descending sort. 
meta no off, basic, or full. Default is off (no meta). Returns metadata that describes the structure of returned entity data. For more information, see
showEditable no (true/false) Whether to show the _editable field in responses. The _editable field indicates whether an entity is editable. Default value is false.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

Settings

GET /settings/setting1[,setting2…]

curl https://rest.bullhornstaffing.com/rest-services/e999/settings/allPrivateLabelIds,currencyFormat

# Example Response
{
    "allPrivateLabelIds":  [ 1, 2, 3],
    "currencyFormat": "USD"
}

Returns the value(s) of the specified system setting(s). The value type (Integer, String, Boolean, and so forth) depends on the specified setting name.

GET /settings

curl -X GET "http://rest.bullhornstaffing.com/rest-services/e999/settings"

# Example Response
{
  "data": [
    {
      "name": "accountLockoutDuration",
      "valueUrl": "http://rest.bullhornstaffing.com/rest-services/e999/settings/accountLockoutDuration",
      "valueType": "INTEGER",
      "isArray": false
    }, {
      "name": "allDeptIds",
      "valueUrl": "http://rest.bullhornstaffing.com/rest-services/e999/settings/allDeptIds",
      "valueType": "INTEGER",
      "isArray": true
    }, {
      "name": "allPrivateLabelIds",
      "valueUrl": "http://rest.bullhornstaffing.com/rest-services/e999/settings/allPrivateLabelIds",
      "valueType": "INTEGER",
      "isArray": true
    }, {
      "name": "commentActionList",
      "valueUrl": "http://rest.bullhornstaffing.com/rest-services/e999/settings/commentActionList",
      "valueType": "STRING",
      "isArray": true
    }
    ...
  ]
}

Returns a list of predefined setting names and their metadata.

Events

GET /event/subscription

curl https://rest.bullhornstaffing.com/rest-services/e999/event/subscription/Abcde?maxEvents=100

# Example Response
{{
    "requestId": 1,
    "events": [
        {
            "eventId": "ID:JBM-40000517",
            "eventType": "ENTITY",
            "eventTimestamp": 1495559294820,
            "eventMetadata": {
                "PERSON_ID": "1314",
                "TRANSACTION_ID": "c8d8f9ea-5ae6-4346-831c-29b91fcb703d"
            },
            "entityName": "ClientContact",
            "entityId": 8592,
            "entityEventType": "UPDATED",
            "updatedProperties": [
                "username",
                "password"
            ]
        }
    ]
}

Lets you get entity events, field map change events, and job match search events.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}

Parameter Required Description
maxEvents yes Integer specifying the maximum number of events to be returned.
requestId no Integer specifying an event requestId. Lets you reget events.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

HTTP Response

Field Description
eventID Unique identifier for the event.
eventMetaData Contains metadatata key/value pairs. PERSON_ID: User associated with the event. TRANSACTION_ID: For entities that have edit history, a TRANSACTION_ID represents a specific change that happened in the Bullhorn system, triggering an event in the subscription queue. TRANSACTION_IDs are returned as part of the subscription event data and can be used to associate a specific event to the state of a record at that stage.
eventTimestamp The date and time at which the event occurred.
entityEventType Integer specifying the maximum number of events to be returned.
eventType Always “ENTITY” for entity events.
entityID The unique identifier for the entity instance that was affected.
entityName The name of the entity that was affected.
updatedProperties If the event type is UPDATED, this parameter indicates which properties of the entity were modified.

GET /event/subscription/lastRequestId

curl https://rest.bullhornstaffing.com/rest-services/e999/event/subscriptioN/Abcde/lastRequestId

# Example Response
{'result': 1}

Lets you get entity events, field map change events, and job match search events.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}/lastRequestId

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /event/subscription

curl -X PUT \
     -H "Content-Type: application/json" \
     https://rest.bullhornstaffing.com/rest-services/e999/event/subscription/Abcde?type=entity&names=Candidate
&eventTypes=INSERTED,UPDATED,DELETED

# Example Response
{'lastRequestId': 0,
 'subscriptionId': 'abcde',
 'createdOn': 1335285871323,
 'jmsSelector': "JMSType='ENTITY' AND BhCorpId=44 AND BhEntityName='Candidate' AND BhEntityEventType IN ('UPDATED','INSERTED','DELETED')"}

Lets you subscribe to event types.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}

Parameter Required Description
type yes entity
names yes Required with “entity” type. A comma-separated list of entity names.
eventTypes yes RRequired with “entity” type. A comma-separated list of entity event types: INSERTED, UPDATED, DELETED.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /event/subscription

curl https://rest.bullhornstaffing.com/rest-services/e999/event/subscription/Abcde
&eventTypes=INSERTED,UPDATED,DELETED

# Example Response
{'result': True}

Lets you unsubscribe from event types.

HTTP Request

{corpToken}/event/subscription/{subscriptionId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

User Headshot File

GET /userHeadshotFile

curl https://rest.bullhornstaffing.com/e999/userHeadshotFile/Candidate/3835

# Example Response
<A multipart-encoded version of the file>

Returns a user headshot (profile picture) file attached to a Person entity. Headshot files can be attached to the following types of entities: * Candidate * ClientContact * CorporateUser

HTTP Request

{corpToken}/userHeadshotFile/entityId}}

Param Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

PUT /userHeadshotFile


# Base64-encoded userHeadshotFile request

curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"externalID" : "portfolio", "fileContent" : "VGhpcyBpcyBhIHZlcnkgc21hbGwgdGV4dCBmaWxlLg0KDQpTbWFsbFRleHRGaWxl", \
        "fileType" : "SAMPLE", "name" : "headshotfile.jpg", "contentType" : "image",\
        "description" : "Headshot file for candidate.", "type" : "headshot"}' \
     https://rest.bullhornstaffing.com/rest-services/e999/userHeadshotFile/Candidate/5097909

# Multipart/form (raw) userHeadshotFile request

curl -X PUT \
    -F "file=@headshotfile.jpg" \
    https://rest.bullhornstaffing.com/rest-services/e999/userHeadshotFile/Candidate/5097909/raw?filetype=SAMPLE&externalID=portfolio

# Example Response
{"fileId": 178}

Attaches a user headshot file (profile picture) to an entity. You can send a user headshot file as base64-encoded text or multipart/form data (raw). Files can be attached to the following types of entities: * Candidate * ClientContact * ClientCorporation * JobOrder * Opportunity * Placement

HTTP Request for base64-encoded user headshot file

{corpToken}/userHeadshotFile/{entityType}/{entityId}

Request body field Required Description
externalID yes External identifier for the file.
fileContent yes Base64-encoded string of the file content.
fileType yes Always use the value “SAMPLE”.
name yes File name.
contentType no Type/subtype of the file content.
description no Comment that describes the file.
type no Type of file that is attached.
Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

HTTP Request for multipart/form (raw) user headshot file

{corpToken}/userHeadshotFile/{entityType}/{entityId}/raw

Parameter Required Description
externalID yes External identifier for the file.
fileType yes Always use the value “SAMPLE”.
name yes File name.
contentType no Type/subtype of the file content.
description no Comment that describes the file.
type no Type of file that is attached.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

POST /userHeadshotFile


# Base64-encoded user headshot file request

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"externalID" : "portfolio", "fileContent" : "VGhpcyBpcyBhIHZlcnkgc21hbGwgdGV4dCBmaWxlLg0KDQpTbWFsbFRleHRGaWxl", \
        "fileType" : "SAMPLE", "name" : "headshotfile.jpg", "contentType" : "image",\
        "description" : "Headshot file for candidate.", "type" : "headshot"}' \
     https://rest.bullhornstaffing.com/rest-services/e999/userHeadshotFile/Candidate/5097909

# Multipart/form (raw) userHeadshotFile request

curl -X POST \
    -F "file=@headshotfile.jpg" \
    https://rest.bullhornstaffing.com/rest-services/e999/userHeadshotFile/Candidate/5097909/raw?filetype=SAMPLE&externalID=portfolio

# Example Response
{"fileId": 179}

Attaches a user headshot file (profile picture) to an entity. You can send a file as base64-encoded text or multipart/form data (raw). Files can be attached to the following types of entities: * Candidate * ClientContact * ClientCorporation

HTTP Request for base64-encoded user headshot file

{corpToken}/userHeadshotFile/{entityType}/{entityId}

Request body field Required Description
externalID yes External identifier for the file.
fileContent yes Base64-encoded string of the file content.
fileType yes Always use the value “SAMPLE”.
name yes File name.
contentType no Type/subtype of the file content.
description no Comment that describes the file.
type no Type of file that is attached.
Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

HTTP Request for multipart/form (raw) file

{corpToken}/userHeadshotFile/{entityType}/{entityId}/raw

Parameter Required Description
externalID yes External identifier for the file.
fileType yes Always use the value “SAMPLE”.
name yes File name.
contentType no Type/subtype of the file content.
description no Comment that describes the file.
type no Type of file that is attached.
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.

DELETE /userHeadshotFile

curl -X DELETE \
     https://rest.bullhornstaffing.com/rest-services/e999/userHeadshotFile/Candidate/3835

# Example Response
{
   "fileId": 178,
   "changeType": "DELETED"
}

Soft deletes a user headshot file. The actual file remains on the server.

HTTP Request

{corpToken}/userHeadshotFile/{entityType}/{entityId}

Parameter Required Description
BhRestToken no Token that represents a session established by the login process. Must be sent with all subsequent requests to the API. The session key can be provided in the BhRestToken query string, a cookie, or an HTTP header.