What is the association operation?
The REST association operation makes it quick and easy to get association ids for multiple parent entity ids in a single request.
An association is an entity field that is another entity type. An association can have a to-many or to-one relationship with the parent entity. For example, the Candidate entity has a to-many relationship with the primarySkills association field, which is of the entity type Skill.
Before the association operation was introduced, the process for getting association data was much more tedious. You would make a request for a specific entity id and the association field for which you want data. This means you had to repeat this request for all the entity ids for which you wanted association data. For example, you would repeat a request like this for each Candidate id for which you want primarySkills data:
GET https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/entity/Candidate/123/primarySkills
This is where an association request becomes useful. It is a POST request in which you provide a parent entity type and association type in the request URI and a list of parent entity ids in the request body. The request returns a list of parent entity id and association id pairs. You can use the returned data to make additional requests where you need the parent entity and association ids as input.
The only required parameter on an association request is the ids parameter, which is a list of entity ids in brackets that must be included the body of the request as JSON. Optional parameters include showTotalMatched, start, and count. You can set these parameters as query parameters on the URI or as JSON in the request body with the ids parameter.
Example request URI:
POST https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/association/Candidate/primarySkills
Body:
{ "ids": [7681,2625,1464], "showTotalMatched": true, "start": 0, "count": 3}
Response:
{
"total": 24,
"data": [
[
7681,
10115
],
[
2625,
19739
],
[
1464,
241506
]
]
}