Introduction

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

Other Guides: - Entity Reference Guide available: here

General Conventions

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

URLs

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:

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.
The response HTTP Content-Type is "text/javascript" instead of "application/json".

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

API Operations

There are several API operations for retrieving entity data: entity, search, query, and meta. These calls share some common parameters and behavior.

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

Entity ids

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

Notes

to-many association fields only appear at the top level (no nesting).
to-many associated entities that are soft-deleted (deletion is indicated by the isDeleted field) are not returned.

Authorization

User authorization and session management use the following flow:

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

A query parameter named BHRestToken on the request URL.
An HTTP header named BHRestToken.
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:

/entity
/query
/meta
/search

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:

Candidate: id, firstName, lastName
Contact: id, firstName, lastName
Job: id, Job Title
ClientCorporation: id, Name
Placement: id

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:

User has the View All Private Attachments entitlement
File is shared with the user
User is the owner or secondary owner of the entity to which the file is associated
File is shared with a department of which the user is a member
If file ownership is enabled, the user is the owner (uploader) of the file; otherwise, the user is the owner or secondary owner of the entity to which the file is associated

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
  }
}

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:

You cannot create to-many associations on the entity being inserted. You must create them in a subsequent “associate” call.
You can create to-one associations. The associations can only be to existing entities; You cannot create new associated entities while creating the main entity.

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 cannot create to-many associations on the entity being updated. You must create to-many associations in a subsequent “associate” call.
You can create to-one associations.

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:

BusinessSector
Category
Country
ClientCorporation
Skill
Specialty
State
TimeUnit

HTTP Request

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

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

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

Soft delete via POST (update) call

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{ "isDeleted" : true }' \
     https://rest.bullhornstaffing.com/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:

Candidate
ClientContact
ClientCorporation
JobOrder
Opportunity
Placement

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:

Candidate
ClientContact
ClientCorporation
JobOrder
Opportunity
Placement

HTTP Request

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

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

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:

Candidate
ClientContact
ClientCorporation
JobOrder
Opportunity
Placement

HTTP Request

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

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

PUT /file


# Base64-encoded file request

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

# Multipart/form (raw) file request

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

# Example Response
{"fileId": 178}

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

Candidate
ClientContact
ClientCorporation
JobOrder
Opportunity
Placement

HTTP Request for base64-encoded file

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

Request body field	Required	Description
externalID	yes	External identifier for the file.
fileContent	yes	Base64-encoded string of the file content.
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:

Candidate
ClientContact
ClientCorporation
JobOrder
Opportunity
Placement

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:

ClientContact
JobOrder
Candidate
ClientCorporation
Lead (if leadsAndOpportunitiesEnabled = true)
Opportunity (if leadsAndOpportunitiesEnabled = true)

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:

entity ID
US or International phone number
person or company name
email address

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:

followed by any combination of 0-9, -, *, (, ), . or space, followed by *

For example: +1-234-56*

Exactly 10 digits, separated by any combination of +, -, *, (, ), . or space

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

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}/"
}

Never assume that a REST session will not expire.
Perform a ping request to return the timestamp of the REST session expiration.
Perform a refresh token request when a REST API request returns a 401 status code that indicates the session is expired. See Use a refresh token to get a new access token in Getting Started with REST.

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]
                     }
}

“ids” is a list of entity ids to mass update. (mandatory, 10000 limit)
For to-one properties, supply the associated entity id as value. For example, “owner” : 123
For to-many properties:
- Use the first form to replace the entire association. For example: “assignedUsers”: [123, 456]
- Use the second form to add or remove associations. For example: “assignedUsers”: { “add” : [123], “remove” : [456] }
- You must specify “add” or “remove” or both.

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

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

UNIX long millis. For example, dateAdded > 1324579022

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.

{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

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}

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

GET /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:

candidateDataCaptureNotificationEmailBody / candidateDataCaptureNotificationEmailSubjectLine
contactDataCaptureNotificationEmailBody / contactDataCaptureNotificationEmailSubjectLine
leadDataCaptureNotificationEmailBody / leadDataCaptureNotificationEmailSubjectLine

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:

Candidate
ClientContact
CorporateUser

HTTP Request

{corpToken}/userHeadshotFile/entityId}}

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

PUT /userHeadshotFile


# Base64-encoded userHeadshotFile request

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

# Multipart/form (raw) userHeadshotFile request

curl -X PUT \
    -F "file=@headshotfile.jpg" \
    https://rest{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:

Candidate
ClientContact
ClientCorporation
JobOrder
Opportunity
Placement

HTTP Request for base64-encoded user headshot file

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

Request body field	Required	Description
externalID	yes	External identifier for the file.
fileContent	yes	Base64-encoded string of the file content.
fileType	yes	Always use the value “SAMPLE”.
name	yes	File name.
contentType	no	Type/subtype of the file content.
description	no	Comment that describes the file.
type	no	Type of file that is attached.

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

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

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

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

POST /userHeadshotFile


# Base64-encoded user headshot file request

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

# Multipart/form (raw) userHeadshotFile request

curl -X POST \
    -F "file=@headshotfile.jpg" \
    https://rest{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:

Candidate
ClientContact
ClientCorporation

HTTP Request for base64-encoded user headshot file

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

Request body field	Required	Description
externalID	yes	External identifier for the file.
fileContent	yes	Base64-encoded string of the file content.
fileType	yes	Always use the value “SAMPLE”.
name	yes	File name.
contentType	no	Type/subtype of the file content.
description	no	Comment that describes the file.
type	no	Type of file that is attached.

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

HTTP Request for multipart/form (raw) file

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

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

DELETE /userHeadshotFile

curl -X DELETE \
     https://rest{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.

Introduction

General Conventions

URLs

Entities

JSON

JSONP

API Operations

Entity ids

Notes

Authorization

Unauthorized requests

Session key

General GET request options

Entity fields

All fields

Entity ids

Comma-separated list of fields

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

Number of to-many entities to return [count]

Filter to-many entities with a sub-where clause

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

Entity metadata

Entity property metadata

Description

Bullhorn fieldmap edit types and REST metadata

Edit type

DataSpecialization

InputType

OptionsType

Errors

allCorpNotes

GET /allCorpNotes

HTTP Request

association

POST /association

HTTP Request

entitlements

GET /entitlements

List of Entitlements

File privacy entitlements

entity

GET /entity

HTTP Request

Multiple Entities

HTTP Request

To-many Associations

HTTP Request

PUT /entity

HTTP Request

Create To-many Associations

POST /entity

HTTP Request

To-many Associations - Special Case

HTTP Request

DELETE /entity

Hard or Soft Delete via DELETE call

HTTP Request

Soft delete via POST (update) call

HTTP Request

Disassociate To-many Associations

Effective-dated entity

Create first version

Create subsequent versions

Update specific version

Delete a version

Read a version

Today’s version

Version effective on specific date

All versions

Associated effective-dated entity fields

departmentEntities

GET /department{Entity}s

HTTP Request

myEntities

GET /my{Entity}s

HTTP Request

file

GET /file

HTTP Request

GET /entityFiles