Note: Mapped Entities are currently open for Bullhorn1 Early Adopters implementing the Prism integration.

What are mapped entities?

Mapped entities are custom-configured entities for business-specific cases in which a combination of existing entities can be defined to represent a singular concept.

MappedEntityConfig is a new set of API services in Bullhorn that match a JSON mapping of Bullhorn fields to a configured name of your choosing. Third-party systems integrating to Bullhorn can use them to create a standard integration regardless of an individual customer’s field configuration within Bullhorn.

This configuration consists of the following fields:

  • mappedName - Unique per corporation, enforced at the database level. Read-only access to all mapped fields on the related Bullhorn records.
  • entityName - All mapped fields must trace back to this entity in a 1:1 relationship. For example, you cannot move from Candidate to Placement, because that is 1:N, but you could go from Placement to Candidate. API user must have access to this entity in order to access the mapped entity.
  • fields - Definition of the mapping in JSON format.
Sample mapped entity field definition
"fields": "[{\"mappedName\":\"address1\",\"parentEntitySimpleName\":\"Candidate\",\"originalFieldNameStack\":[\"candidate\",\"address\",\"address1\"],\"url\":\"\"}]"

Mapped entity configuration services

The following Bullhorn REST API services let you configure mapped entities.
For details on using the API generally, see Getting Started with REST.

Create a new mapped entity configuration entry:

PUT https://rest.bullhornstaffing.com/rest-services/{corpToken}/services/mappedEntityConfig/create

Get all existing mapped configurations:

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/services/MappedEntityConfig/all

Get a single existing mapped configuration:

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/MappedEntityConfiguration/{ID}?fields=*

Update an existing mapped configuration:

POST https://rest.bullhornstaffing.com/rest-services/{corpToken}/services/mappedEntityConfig/update

Delete an existing mapped configuration:

DELETE https://rest.bullhornstaffing.com/rest-services/{corpToken}/services/mappedEntityConfig/delete/{ID}

How many levels deep can the mapping go?

Mapped fields must trace down from the BH entityName specified. It currently supports up to 6 levels deep. For reference, traditional field requests only allow 3 levels deep.

For example:

1 2 3 4 5 6
payMasterTransaction .payMaster .payablecharge .placement .jobOrder .title

How do I get enabled for mapped entities?

Set the Corp Setting “enableMappedEntities” to “true.”

How do I query a mapped entity?

Mapped entities can be referenced in the API via their mappedName preceded by a ~.
For example, the following will query a configured mapped entity named “SomeMappedEntity”…

GET https://rest.bullhornstaffing.com/rest-services/{corpToken}/query/~SomeMappedEntity?where=candidate.id=1&fields=*

How do I update a mapped entity?

Mapped entities can be updated regularly via the REST API. If one does a PUT call against the mapped entity with a field in the mapping, it will update the root entity. For example, a POST call can be executed as shown below with a payload containing a field in the mapping

POST https://rest.bullhornstaffing.com/rest-services/{corpToken}/entity/~SomeMappedEntity/{ID}

payload:
{
    "candidate.email2": "work-test@example.com"
}