DEVELOPER

DEVELOPER

Use the REST API with custom objects

What are custom objects?

Custom objects are custom fields that extend the standard Bullhorn Candidate, ClientContact, ClientCorporation, JobOrder, Opportunity, and Placement entities. You can use custom objects to more closely match your business data requirements. These fields are entities and you can use the REST API to create, edit, and return instances of them. See the Bullhorn Resource Center for general information about custom objects, .

REST API calls for custom objects

Note: Before using the REST API, you must perform authorization and authentication. See Getting Started with the Bullhorn REST API for information about obtaining an OAuth 2.0 access token and logging in to the REST API.

The following topics provide REST API examples to get you up and running quickly with custom objects:

Get metadata for defined custom objects

Before working with custom objects with the REST API, you first must understand the structure of the custom objects assigned to an entity type. The REST /meta request returns information about the structure of the entity type, including its assigned custom objects.

Each entity can have customObject1s through customObject10s assigned as custom objects. To determine which customObjects are assigned to an entity type, request all fields with the * character as the following example shows. Only the assigned customObjects are returned in the list of entity fields.

Note: A custom object can be configured so that only users in specific departments can view that custom object or its metadata. If the current user does not have view entitlements to a custom object, a /meta call returns no metadata for that custom object.

Request URI:

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/meta/Candidate?
fields=*

Once you know the custom objects available on an entity type, you can get more information about those custom objects. The following request returns just the metadata for the custom object assigned to customObject2s on the Candidate entity type:

Request URI:

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/meta/Candidate?
fields=customObject2s(*)

Response:

{
"entity" : "Candidate",
"entityMetaUrl" : "http://mikep-backend:8181/rest-services/1yg8p/meta/Candidate?fields=*",
"label" : "Candidate",
"fields" : [ {
"name" : "customObject2s",
"type" : "TO_MANY",
"confidential" : false,
"label" : "Custom Object2s",
"optionsType" : "PersonCustomObjectInstance2",
"optionsUrl" : "http://mikep-backend:8181/rest-services/1yg8p/options/PersonCustomObjectInstance2",
"hideFromSearch" : false,
"associatedEntity" : {
"entity" : "PersonCustomObjectInstance2",
"entityMetaUrl" : "http://mikep-backend:8181/rest-services/1yg8p/meta/PersonCustomObjectInstance2?fields=*",
"label" : "RestAutomation1",
"fields" : [ {
"name" : "date1",
"type" : "SCALAR",
"dataType" : "Timestamp",
"confidential" : false,
"label" : "date1",
"hideFromSearch" : false
}, {
"name" : "dateAdded",
"type" : "SCALAR",
"dataType" : "Timestamp",
"confidential" : false,
"label" : "Date Added",
"hideFromSearch" : false
}, {
"name" : "float1",
"type" : "SCALAR",
"dataType" : "Float",
"confidential" : false,
"label" : "float1",
"hideFromSearch" : false
}, {
"name" : "int1",
"type" : "SCALAR",
"dataType" : "Integer",
"confidential" : false,
"label" : "int1",
"hideFromSearch" : false
}, {
"name" : "text1",
"type" : "SCALAR",
"dataType" : "String",
"maxLength" : 100,
"confidential" : false,
"label" : "text1a",
"options" : [ {
"value" : "sometext1",
"label" : "sometext1"
}, {
"value" : "sometext2",
"label" : "sometext2"
} ],
"hideFromSearch" : false
} ]
}
} ]
}

Create custom object on existing entity

The following example request creates a new custom object and adds it to an existing Candidate in a single REST call. Unlike other association properties, you do not need to create a custom object in a separate call before associating it with an existing entity. In this case, the custom object is assigned to the customObject2s field on the Candidate entity type.

Note: A custom object can be configured so that only users in specific departments can create or edit that custom object. If the current user does not have edit entitlements to a custom object, the user cannot create or edit that type of custom object.

Request URI:

POST https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate/12345
Content-Type: application/json

Request body:

{"customObject2s":[{"int1":2,"text1":"sample text"}]}

Create custom object on new entity

The following example request creates a new Candidate and also creates a new custom object and associates it with the new Candidate. Unlike other association properties, you do not need to create a custom object and an entity in separate calls before associating the custom object with the entity. In this case, the custom object is assigned to the customObject2s field on the Candidate entity type.

Note: A custom object can be configured so that only users in specific departments can create or edit that custom object. If the current user does not have edit entitlements to a custom object, the user cannot create or edit that type of custom object.

Request URI:

PUT https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate
Content-Type: application/json

Request body:

{
"customObject2s":[{"text1":"sometext2","int1":2,"date1": 1323811177770,"float1":2.9}],
"firstName": "TestFirst",
"lastName": "TestLast",
"name": "TestFirst TestLast",
"username": "TestCandidatexxx",
"status" : "active"
}

Response:

{
"changedEntityType": "Candidate",
"changedEntityId": 31918,
"changeType": "INSERT"
}

Update custom object on existing entity

The following example request updates an existing custom object on an existing Candidate. The example updates the int1 field of the custom object that has id 3649. In this case, the custom object is assigned to the customObject2s field on the Candidate entity type.

Note: A custom object can be configured so that only users in specific departments can create or edit that custom object. If the current user does not have edit entitlements to a custom object, the user cannot create or edit that type of custom object.

Request URI:

POST https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate/32031
Content-Type: application/json

Request body:

{"customObject2s":[{"id":3649,"int1":5}]}

Update and create custom objects on existing entity

The following example request updates an existing custom object and creates a new custom object on an existing Candidate. The example updates the int1 field of the custom object that has id 3649 and also creates a new custom object and sets its int1 value. In this case, the custom object is assigned to the customObject2s field on the Candidate entity type.

Request URI:

POST https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate/32039
Content-Type: application/json

Request body:

{"customObject2s":[{"id":3649,"int1":7},{"int1":4}]}

Search for entity based on custom object

The following example request performs a Candidate search based on the value of the text1 field of a custom object. In this case, the custom object is assigned to the customObject2s field on the Candidate entity type. The syntax used in the "query" parameter on the request is a lookup query, which is a SQL query on an indexed entity field; the indexed field is Candidate.id. The search returns all Candidates with ids where customObjects2.text1='sometext2'.

Request URI:

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/search/Candidate?
query=id:"^(customObject2s.text1='sometext2')"&fields=id,customObject2s(text1)
&useV2=true&sort=-id&count=5

Note: A custom object can be configured so that only users in specific departments can view that custom object. If the current user does not have view entitlements to a custom object, a search on that custom object returns no matching items.

Disassociate custom object from entity

The following example request disassociates an existing custom object from an existing entity in a standard disassociation request. This is the only way to dissassociate a custom object from an entity with the REST API.

Request URI:

DELETE https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate/32056
/customObject2s/3680

Query a custom object

The following example request performs a custom object query. This is the only way to query a custom object directly with the REST API.

Note: A custom object can be configured so that only users in specific departments can view that custom object. If the current user does not have view entitlements to a custom object, a query on that custom object returns no matching items.

Request URI:

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/query/PersonCustomObjectInstance2?
where=id=3684&fields=*&orderBy=-id&count=5