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.

Related:

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

API users should use data-center-specific URLs for login workflows based on the results of making a GET rest-services/loginInfo request with the API_Username to return the list of correct URLs for that user: https://rest.bullhornstaffing.com/rest-services/loginInfo?username={API_Username}

If you do not use the correct URLs for a user, you will receive a 307 redirect to the correct data center. Your code must be written to handle that 307 redirect.

Web URLs are case-sensitive, except for machine names. 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{swimlane#}.bullhornstaffing.com/rest-services/{corptoken}/entity/Candidate

Where {corptoken} is the corporation identifier.

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 follows 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.

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: Other than for /meta/{entityType}, the fields=* syntax is now deprecated because of negative performance impact. Calls using this syntax will be blocked.

Use the /meta/{entityType} call with fields=* to see the full entity model, including association 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)

Note: The only exception to this is PlacementRateCard’s placementRateCardLineGroup and placementRateCardLine & JobOrderRateCard’s jobOrderRateCardLineGroup and jobOrderRateCardLine fields.

Acceptable: fields=placementRateCardLineGroup(placementRateCardLine(*))

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 an 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 Rate Limited – Wait 1 second then retry request. Repeat until successful.
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{swimlane#}.bullhornstaffing.com/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.

association

POST /association

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{ "ids": [7681,2625,1464], "showTotalMatched": true, "start": 0, "count": 3}' \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/association/Candidate/primarySkills

# Example Response
{
    "total": 24,
    "data": [
        [
            7681,
            10115
        ],
        [
            2625,
            19739
        ],
        [
            1464,
            241506
        ]
    ]
}

Retrieves a list of associated entity ids for a given entity. The association field can be a to-many or to-one association.

HTTP Request

{corpToken}/association/{entity}/{association field}

Note: The ids parameter is the only required parameter and must be set in the request body as JSON. All other parameters can be set in the request body or as query parameters on the URL.

Parameter Required Description
ids yes List of entity ids. Must be set in the body of the request rather than in a URL query parameter.
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. The Max allowed count is 10000.
start no From the set of matched results, return record numbers start through (start + count).
showTotalMatched no (true/false) When set to true, the total count of matching items is returned.
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.

entitlements

GET /entitlements

curl https://rest{swimlane#}.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:

entity

GET /entity

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/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 Meta.
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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{swimlane#}.bullhornstaffing.com/rest-services/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 Meta.
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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{{swimlane#}.bullhornstaffing.com/rest-services/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 Meta.
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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/rest-services/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 contain 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 return 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/rest-services/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/rest-services/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/rest-services/e999/entity/JobOrder/123

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

For special to-many associations, like Custom Objects, you can create and associate in a single step. You can add or update to-many associations with a POST request as if the data is 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 hard or soft delete using the DELETE verb. You can also use a standard update request with the POST verb to set the isDeleted property of a soft-deletable entity to true.

Hard or Soft Delete via DELETE call

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

Hard deletes one or more hard-deletable entities, which removes it from the database. Soft deletes one or more soft-deletable entities, 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 nor soft-deletable. Immutable entities include the following:

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/rest-services/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/rest-services/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},*}

Effective-dated entity

Effective-dated entities are entities that are versioned by a specific date (the effectiveDate of the version). By maintaining multiple versions of an entity, users can track historical data and the context of an entity on a specific date.

Create first version

curl -X PUT \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location

Sample Request Body
{
  "clientCorporation" : { "id": 123 },
  "effectiveDate" : "2020-1-1",
  "title" : "My location title",
  "address" : {
    "address1" : "200 S Main",
    "city" : "Clayton"
  }
}

You can use HTTP PUT requests to create new effective-dated entities much like standard entities. The URL looks the same as a GET request URL, but without the last path element that contains an entity ID. Place the data comprising the new entity to be inserted in JSON format in the request body.

All effective-dated entities have a required effectiveDate field. The effectiveEndDate and viewableStartDate fields are calculated based on the versions that exist on this root entity.

One key difference between effective-dated entities and standard entities is that effective-dated entities return both a changedEntityId and a changedVersionId in the response. This is because an update to an effective-dated entity involves two entities. For example, the Location entity involves the root Location entity and the LocationVersion version entity.

Create subsequent versions

curl -X POST \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location/1234

Sample Request Body
{
  "effectiveDate" : "2020-1-1",
  "title" : "My location title",
  "address" : {
    "address1" : "200 S Main",
    "city" : "Clayton"
  }
}

Creating additional versions on an existing effective-dated entity is considered both an update and create action because you update the root entity while creating a new version.

Use a POST request to create one or more additional versions. The URL looks the same as a PUT request URL, but includes the ID of the root entity you are updating as the last path parameter of the URL. The JSON data is the same as that of the PUT request and no version ID is included.

Not all fields in the JSON are unique to the version entity, so requests against these fields update the root entity rather than create a new version. The Location clientCorporation field is an example of this. It is a required field on initial Root create but not on subsequent create calls for Versions.

Update specific version

curl -X POST \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location/1234

Sample Request Body
{
  "versionID": 7654,
  "customText1": "my custom text"
}

Use a POST request to update an existing version. Place the data comprising the entity fields in JSON format in the request body.

Due to the double-entity nature of effective-dated entities, you must pass both the entity ID and version ID that you want to update in this request.

Delete a version

curl -X DELETE \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location/1234

Sample Response
{
   "message": "Successfully deleted 1 Location entities."
}

Use a DELETE request to delete a version on an effective-dated entity. When you delete a version, it is hard-deleted from the database but edit history for that version is not deleted. When attempting to delete the only version(s) of an effective-dated entity, we block the hard deletion and instead cause the root entity to be soft-deleted to remove it from the user’s view in the user interface while maintaining historical context for how it was used.

Read a version

There are multiple ways to read an effective-dated entity and the versions on it. All of these involve making a GET request as described below.

When requesting the root entity, we return the root entity ID and the version ID. These IDs are important when making updates to this version. By default, the viewableStartDate, effectiveDate, and effectiveEndDate fields are also returned.

Today’s version

When making a GET request for an entity, the version that is effective today according to the user’s local computer time is returned.

curl -X GET \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location/1234?fields=address

Sample Response
{
  "id" : 5059165,
  "versionId" : 123,
  "viewableStartDate" : '2020-1-1',
  "effectiveDate" : '2020-1-1',
  "effectiveEndDate" : '2021-1-1',
  "address" : {
    "address1" : "123 Whatever St"
  }
}

Version effective on specific date

This effectiveOn value defaults to today but you can use the effectiveOn query parameter to return a different version.

curl -X GET \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location/1234?fields=address&effectiveOn=2027-12-31

All versions

curl -X GET \
     https://rest.bullhornstaffing.com/rest-services/e999/entity/Location/1234/versions?fields=address

Sample Response
data: [{
  "id" : 5059165,
  "versionId" : 123,
  "viewableStartDate" : '1900-1-1',
  "effectiveDate" : '2020-1-1',
  "effectiveEndDate" : '2024-12-31',
  "address" : {
    "address1" : "1234 Whatever St."
  }
},
{
  "id" : 5059165,
  "versionId" : 124,
  "viewableStartDate" : '2025-1-1',
  "effectiveDate" : '2025-1-1',
  "effectiveEndDate" : '2030-1-1',
  "address" : {
    "address1" : "1234 Whatever St."
  }
}
}]

You can request all versions that exist on the effective-dated entity.

Associated effective-dated entity fields

curl -X GET \
    https://rest.bullhornstaffing.com/rest-services/e999/entity/Placement/1?fields=location&effectiveOn=2021-12-31
curl -X GET \
    https://rest.bullhornstaffing.com/rest-services/e999/query/Placement?where=firstName='Bob'&fields=location&effectiveOn=2027-12-31
curl -X GET \
    https://rest.bullhornstaffing.com/rest-services/e999/search/Placement?fields=location&effectiveOn=2021-12-31&query=id>0

When requesting effective-dated entity fields via an associated object, use the effectiveOn parameter to limit the request to a specific date.

In the examples, Location is an effective-dated entity field requested from an associated Placement. The effectiveOn value is applied to the requested Location.

departmentEntities

GET /department{Entity}s

curl https://rest{swimlane#}.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, 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 Comma-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.

myEntities

GET /my{Entity}s

curl https://rest{swimlane#}.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, 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 Comma-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.

file

GET /file

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/file/Candidate/3835/231

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

Returns an attached file as base64-encoded text.

Note: The optional “raw” path parameter returns a multipart-encoded version of the file. This path parameter exists for convenience. When an API user makes a call of this form in a browser, it appears that the browser has downloaded the file.

Files can be attached to the following types of entities:

HTTP Request

{corpToken}/file/{entityType}/{entityId}/{fileId}(/raw)

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

(deprecated; replaced by /entity/{entityType}/{entityId}/fileAttachments)

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/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:

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.

GET /entity/{entityType}/{entityId}/fileAttachments

curl https://rest{{swimlane#}.bullhornstaffing.com/rest-services/e999/entity/JobOrder/203866/fileAttachments?fields=id

# Example Response
{
  "start" : 0,
  "count" : 1,
  "data" : [ {
    "contentSubType" : "plain",
    "contentType" : "text",
    "dateAdded" : 1530815115887,
    "departmentsSharedWith" : {
      "total" : 0,
      "data" : [ ]
    },
    "description" : null,
    "directory" : "4659/2018.07/",
    "distribution" : "internal",
    "externalID" : "Portfolio",
    "fileExtension" : ".txt",
    "fileOwner" : null,
    "fileSize" : 23,
    "fileType" : "SAMPLE         ",
    "isCopied" : false,
    "isDeleted" : false,
    "isEncrypted" : true,
    "isExternal" : false,
    "isOpen" : true,
    "isPrivate" : false,
    "isSendOut" : false,
    "jobOrder" : {
      "id" : 232625,
      "title" : "Greatest Job"
    } ]
}

Returns metadata for attached files.

Files can be attached to the following types of entities:

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:

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.
fileExtension no Extension of the file. For example, .doc or .jpg.
fileType yes Always use the value “SAMPLE”.
name yes File name. If a file extension is included as part of the name and the fileExtension field is not set, the file extension in the name is used.
description no Description of the file.
contentType no Type/subtype of the file content.type
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 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 /file


# Base64-encoded file request

curl -X POST \
     -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/1234

# Multipart/form (raw) file request

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

# Example Response
No response body; returns 200 on successful update.

Updates a file attachment. You can update a file as base64-encoded text or multipart/form data (raw). Files attachments can be updated for the following types of entities:

HTTP Request for base64-encoded file

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

Request body field Required Description
externalID yes External identifier for the file.
fileContent yes Base64-encoded string of the file content.
fileExtension no Extension of the file. For example, .doc or .jpg.
fileType yes Always use the value “SAMPLE”.
name yes File name. If a file extension is included as part of the name and the fileExtension field is not set, the file extension in the name is used.
description no Description of the file.
contentType no Type/subtype of the file content.type
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 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 /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{swimlane#}.bullhornstaffing.com/rest-services/e999/find?query=smith&countPerEntity=3

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

FastFind is a 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{swimlane#}.bullhornstaffing.com/rest-services/{corpToken}/"
}

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{{swimlane#}.bullhornstaffing.com/rest-services/e999/logout

# Example Response
{
    logout: "OK"
}

Log out and invalidate your REST session.

massUpdate

GET /massUpdate

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/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

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{swimlane#}.bullhornstaffing.com/rest-services/e999/massUpdate/JobOrder

# 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{swimlane#}.bullhornstaffing.com/rest-services/e999/massUpdate/JobOrder

# Example Response
{
    "count": 2
}

Performs a massUpdate on all entity records of the specified type for which the entity id is included in the request body.
Note: Use the GET /massUpdate/{entityType} request to see the list of entity properties for which mass update is supported on the specified entity type.
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{swimlane#}.bullhornstaffing.com/rest-services/e999/meta

# Example Response
[
    {
        "entity": "Appointment",
        "metaUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/meta/Appointment?fields=*"
    },
    {
        "entity": "BusinessSector",
        "metaUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/meta/BusinessSector?fields=*"
    },
    {
        "entity": "Candidate",
        "metaUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/meta/Candidate?fields=*"
    },
    {
        "entity": "Category",
        "metaUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/meta/Category?fields=*"
    },
    {
        "entity": "ClientContact",
        "metaUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/meta/ClientContact?fields=*"
    },
    {
        "entity": "ClientCorporation",
        "metaUrl": "https://rest{swimlane#}.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{swimlane#}.bullhornstaffing.com/rest-services/e999/meta/Candidate?fields=*
# Example Response
{
  "entity" : "Candidate",
  "entityMetaUrl" : "https://rest{swimlane#}.bullhornstaffing.com/rest-services/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
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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{{swimlane#}.bullhornstaffing.com/rest-services/e999/options

# Example Response
{
  "data" : [ {
    "optionsType" : "BillRateCategory",
    "optionsUrl" : "https://rest{swimlane#}.bullhorn.com/rest-services/e999/options/BillRateCategory"
  }, {
    "optionsType" : "BusinessSector",
    "optionsUrl" : "https://rest{swimlane#}.bullhorn.com/rest-services/e999/options/BusinessSector"
  }, {
    "optionsType" : "BusinessSectorText",
    "optionsUrl" : "https://rest{swimlane#}.bullhorn.com/rest-services/e999/options/BusinessSectorText"
  }, {
    "optionsType" : "Candidate",
    "optionsUrl" : "https://rest{swimlane#}.bullhorn.com/rest-services/e999/options/Candidate"
  }, {
    "optionsType" : "CandidateText",
    "optionsUrl" : "https://rest{swimlane#}.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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/e999/query/ClientContact?fields=firstName,lastName&where=lastName='smith'&count=3

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

Retrieves a list of entities. To avoid hitting URL length limits, always use the POST version of the query call rather than this GET version for where values that exceed 7500 characters in length. The query is performed against the database. The where parameter accepts Java Persistance Query Language (JPQL) syntax, which is similar SQL syntax. Accessing data via that database is only performant when you query very specific data. Otherwise, it is preferable to use the Search call when 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.
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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.
totalOnly no (true/false) When set to true, only the total count of records matching the where parameter is returned. In this scenario, only the where parameter is required and all others are ignored.
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 /query

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"where": "id IN (10125, 10126, 10127, 10128, 10129, 10130, 10131, 10132, 10133, 10134, 10135, 10136, 10137, 10138, 17376, 26865, 67604, 67605, 80203, 80204, 80205, 80206, 80207, 80208, 80209, 80210, 80211, 80212, 80213, 80214)"}' \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/query/ClientContact?fields=id,firstName,lastname&count=3

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

Retrieves a list of entities. To avoid hitting URL length limits, always use this version of the query call rather than the GET version for where values that exceed 7500 characters in length. The query is performed against the database. The where field in the request body accepts Java Persistance Query Language (JPQL) syntax, which is similar SQL syntax. Accessing data via that database is only performant when you query very specific data. Otherwise, it is preferable to use the Search call when it is available for the entity type for which you want to search.

HTTP Request

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

Parameter Required Description
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.
totalOnly no (true/false) When set to true, only the total count of records matching the where body is returned. In this scenario, only the where body is required and all other parameters are ignored.
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{swimlane#}.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{swimlane#}.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{swimlane#}.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{swimlane#}.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{swimlane#}.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{swimlane#}.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.

savedSearch

GET /savedSearch

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/savedSearch

or:

curl https://rest{swimlane#}.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{swimlane#}.bullhornstaffing.com/rest-services/e999/mySavedSearch

or:

curl https://rest{swimlane#}.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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.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{swimlane#}.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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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{swimlane#}.bullhornstaffing.com/rest-services/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. To avoid hitting URL length limits, always use the POST version of the search call rather than this GET version for query values that exceed 7500 characters in length. The search call is performed against a Lucene index. 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{swimlane#}.bullhornstaffing.com/rest-services/e999/search/Candidate?query=isDeleted:0

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

HTTP Request

{corpToken}/search/{entity}?query={lucene}&fields={fields}&sort={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
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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.

POST /search

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"query": "id:10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 17376 26865 67604 67605 80203 80204 80205 80206 80207 80208 80209 80210 80211 80212 80213 80214"}' \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/search/Candidate?fields=id,firstName,lastname&count=3

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

Retrieves a list of entities. To avoid hitting URL length limits, always use this version of the search call rather than the GET version for query values that exceed 7500 characters in length. Place the query in JSON format in the request body. For example: {"query": "id:10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 17376 26865 67604 67605 80203 80204 80205 80206 80207 80208 80209 80210 80211 80212 80213 80214"}

The search call is performed against a Lucene index. 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.

HTTP Request

{corpToken}/search/{entity}?fields={fields}&sort={fields}&count={count}&start={start}

Parameter Required Description
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
privateLabelId no Integer. Default is primary private label ID. Filters results based on the specified primary or secondary private label ID.
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.

services

POST /services/CCPA/notifyOnCapture

The California Consumer Privacy Act (CCPA) is a bill meant to enhance privacy rights and consumer protection for residents of California and goes into effect on January, 2020. Notify on Capture is a feature of this bill that notifies a person in the system that their data is being captured for the purposes of serving them as a staffing agency. An email is sent and a note is added to the person record for tracking. The staffing agency is responsible for knowing if and when to send Notify on Capture emails.

The email body and subject line are pulled from system settings (private label attributes) that are specific to the person record:

After the email is successfully sent a note is added to the person record with an action type from the: dataCaptureNotificationNoteType system setting.

curl -X POST \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/services/CCPA/notifyOnCapture

# Example Response
{
    "results": {
        "SUCCESS": [
            123,
            456
        ],
        "FAILURE": []
    },
    "overallStatus": "SUCCESS",
    "message": "Notify on capture email has been sent and note added.",
    "successIds": [
        123,
        456
    ],
    "failureIds": []
}

HTTP Request

{corpToken}/services/CCPA/notifyOnCapture

Parameter Required Description
entity yes One of: “Candidate”, “ClientContact”, or “Lead”.
ids yes List of IDs of the given type of entity, a maximum of 500 per call.
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 / PUT /services/DirectDepositAccount

The Direct Deposit Account service allows for the creation of direct deposit accounts attached to a single candidate.

curl -X POST / PUT \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/services/DirectDepositAccount

# Example Request
{
    "candidate": {
        "id": 36432821
    },
    "directDepositAccounts": [
        {
            "amount": 1000,
            "remainder": false,
            "currencyUnit": {
                "id": 166,
                "minorUnits": 0
            },
            "bankName": "Chase Bank",
            "accountNumber": "111",
            "transitNumber": "021000021",
            "directDepositAccountTypeLookup": {
                "id": 1,
                "label": "Checking"
            },
            "paymentOrder": 1
        },
        {
            "amount": 500,
            "remainder": false,
            "currencyUnit": {
                "id": 166,
                "minorUnits": 0
            },
            "bankName": "Bank of America",
            "accountNumber": "112",
            "transitNumber": "011401533",
            "directDepositAccountTypeLookup": {
                "id": 2,
                "label": "Savings"
            },
            "paymentOrder": 2
        },
        {
            "remainder": true,
            "currencyUnit": {
                "id": 166,
                "minorUnits": 0
            },
            "bankName": "Wells Fargo",
            "accountNumber": "113",
            "transitNumber": "091000019",
            "directDepositAccountTypeLookup": {
                "id": 3,
                "label": "Pay Card"
            },
            "paymentOrder": 3
        }
    ]
}

# Example Response
[
    {
        "changedEntityType": "DirectDepositAccount",
        "changedEntityId": 22538,
        "changeType": "INSERT",
        "data": {

        }
    },
    {
        "changedEntityType": "DirectDepositAccount",
        "changedEntityId": 22539,
        "changeType": "INSERT",
        "data": {

        }
    },
    {
        "changedEntityType": "DirectDepositAccount",
        "changedEntityId": 22540,
        "changeType": "INSERT",
        "data": {

        }
    }
]

HTTP Request

{corpToken}/services/DirectDepositAccount

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 /services/IssueReport

The Issue Report service allows for creation of issues to be presented to the user. These user-facing issues will be related to existing entities, and provide data on what the issue is and how to fix it.

curl -X PUT \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/services/IssueReport

# Example Request
{
    "issues": [
        {
            "action": "New Hire Export",
            "actionEntity": "Placement",
            "actionEntityId": 4,
            "externalSystemName": "ACME HR",
            "issueItems": [
                {
                    "severity": "Error",
                    "errorType": "MISSING-DATA",
                    "fieldReference": "zip",
                    "description": "Work location zip code is missing."
                },
                {
                    "severity": "Error",
                    "errorType": "INVALID-DATA",
                    "fieldReference": "status",
                    "description": "Invalid status 'Mostly Active'. Valid statuses are 'Active', 'Inactive', 'Other'."
                }
            ]
        }
    ]
}

# Example Response
[
    {
        "changedEntityType": "Issue",
        "changedEntityId": 1234,
        "changeType": "INSERT",
        "data": {}
    }
]

HTTP Request

{corpToken}/services/IssueReport

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 /services/PlacementChangeRequest/approve/

curl -X POST \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/services/PlacementChangeRequest/approve/123

# Example Response
{
    "message": "success",
    "placementID": 70695,
    "placementChangeRequest": {
        "requestStatus": "Approved",
        "id": 123
    }
}

Approves a PlacementChangeRequest and updates the associated placement with the fields changes specified on the PlacementChangeRequest.

The PlacementChangeRequest requestStatus is changed to the value stored in the placementApprovalStatus private label attribute.

HTTP Request

{corpToken}/services/PlacementChangeRequest/approve/{placementChangeRequestId}

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 /services/RevenueRecognition/BillMasterTransactionDistributionBatch

Handles the creation of a BillMasterTransactionDistributionBatch and its subsequent association to BillableCharges.

curl -X PUT \
      https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/services/RevenueRecognition/BillMasterTransactionDistributionBatch

# Example Request
{
    "billableChargeIds":[1118]
}

# Example Response
{
    "changedEntityType":"BillMasterTransactionDistributionBatch",
    "changedEntityId":178,
    "changeType":"INSERT",
    "data":{}
}

HTTP Request

{corpToken}/services/RevenueRecognition/BillMasterTransactionDistributionBatch

Parameter Required Description
BhRestToken yes 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 /services/RevenueRecognition/UnbilledRevenueDistributionBatch

Handles the creation of an UnbilledRevenueDistributionBatch and its subsequent association to UnbilledRevenueDistributions.

curl -X PUT \
      https://rest{swimlane#}.bullhorn.com/rest-services/e999/services/RevenueRecognition/UnbilledRevenueDistributionBatch 

# Example Request
{
    "billableChargeIds":[1110]
}

# Example Response
{
    "changedEntityType":"UnbilledRevenueDistributionBatch",
    "changedEntityId":58,
    "changeType":"INSERT",
    "data":{}
}

HTTP Request

{corpToken}/services/RevenueRecognition/BillMasterTransactionDistributionBatch

Parameter Required Description
BhRestToken yes 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 /services/RevenueRecognition/UpdateTransactionExportStatus

Allows the API user to update the unbilledRevenueGeneralLedgerExportStatus for one or more BillMasterTransactions.

curl -X POST \
      https://rest{swimlane#}.bullhorn.com/rest-services/e999/services/RevenueRecognition/UpdateTransactionExportStatus 

# Example Request
{
    "billMasterTransactionIDs": [1110],
    "unbilledRevenueGeneralLedgerExportStatusLookupID": 2
}

# Example Response
{
    "changedEntityType": "BillMasterTransaction",
    "changeType": "UPDATE",
    "data": {
        "billMasterTransactionIDs": [
            1110
        ]
    }
}

HTTP Request

{corpToken}/services/RevenueRecognition/UpdateTransactionExportStatus

Parameter Required Description
BhRestToken yes 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 /services/PayExportBatch/batchExportStatus

Allows a user to update the status of a PayExportBatch.

NOTE: If you submit a batch export status update where there is only a single failed record with an entity name of PayExportBatch and the entityId matches the sourceBatchId, then we will treat the request as if you had asked our system to fail every PayMasterTransaction associated with that PayExportBatch. Issue creation logic will be unaffected.

curl -X POST \
      https://rest{swimlane#}.bullhorn.com/rest-services/e999/services/PayExportBatch/batchExportStatus

# Example Request
{
    "exportType": "payroll",
    "sourceBatchID": 5577,
    "successfulRecords": [
        {
            "status": "ACME_SUCCESS",
            "entityName": "~PayrollTimeSheet",
            "entityIds": [
                100, 101
            ],
            "externalBatchID": "BULLHORN_BATCH_ID_5577"
        }
    ],
    "failedRecords": [
        {
            "entityName": "~PayrollTimeSheet",
            "entityId": 102,
            "exception": "Some exception",
            "issues": [
                {
                    "severity": "Error",
                    "externalSystemName": "Charles HR",
                    "actionEntity": "PayExportBatch",
                    "actionEntityId": 1084,
                    "issueItems": [
                      {
                        "sourceEntity": "Placement",
                        "sourceEntityId": 57,
                        "severity": "Error",
                        "fixableByUser": false,
                        "process": "Payroll Export",
                        "comments": "PayExportBatch #1084",
                        "fixInBullhorn": false,
                        "externalEntityName": "Charles HR",
                        "referenceUrlStatusCode": "200",
                        "errorType": "SYSTEM-ERROR",
                        "description": "Fake Description.",
                        "referenceUrl": "https://www.google.com",
                        "referenceUrlMethod": "POST",
                        "externalEntityId": "104",
                        "referenceUrlResponse": "Fake Response",
                        "fieldReference": ""
                      }
                    ],
                    "action": "Payroll Export"
            }
        ]
        },
        {
            "entityName": "~PayrollTimeSheet",
            "entityId": 103,
            "error": "Some exception"
        }
    ]
}

# Example Response
{
    "changedEntityType": "ExternalBatchStatusRequest",
    "changedEntityId": 28,
    "changeType": "INSERT",
    "messages": [
        {
            "detailMessage": "ExternalBatchStatusRequest is queued up for processing",
            "severity": "WARNING",
            "type": "LOCALIZED_PERSISTENCE_MESSAGE"
        }
    ],
    "data": {}
}

HTTP Request

{corpToken}/services/RevenueRecognition/UpdateTransactionExportStatus

Parameter Required Description
BhRestToken yes 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{swimlane#}.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{swimlane#}.bullhornstaffing.com/rest-services/e999/settings"

# Example Response
{
  "data": [
    {
      "name": "accountLockoutDuration",
      "valueUrl": "http://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/settings/accountLockoutDuration",
      "valueType": "INTEGER",
      "isArray": false
    }, {
      "name": "allDeptIds",
      "valueUrl": "http://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/settings/allDeptIds",
      "valueType": "INTEGER",
      "isArray": true
    }, {
      "name": "allPrivateLabelIds",
      "valueUrl": "http://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/settings/allPrivateLabelIds",
      "valueType": "INTEGER",
      "isArray": true
    }, {
      "name": "commentActionList",
      "valueUrl": "http://rest{swimlane#}.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{swimlane#}.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{swimlane#}.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{swimlane#}.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 Required 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{swimlane#}.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.

userHeadshotFile

GET /userHeadshotFile

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/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:

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{swimlane#}.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:

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{swimlane#}.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:

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{swimlane#}.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.