Bullhorn REST API event subscriptions

What is an event subscription

Event subscriptions in the Bullhorn REST API allow for the generation of events to occur in the system based on the subscribed entity and event types. These events can be related to changes in data, such as when a record is created, updated, or deleted.

Getting started with event subscriptions

The following topics provide examples to get you up and running quickly with event subscriptions:

• Create an event subscription
• Retrieve data from an event subscription
• How to use the data within events
• Delete an event subscription

Create an event subscription

To create an event subscription, you need to know which entities you want to subscribe to, and the event types (INSERTED, UPDATED, DELETED) to generate. You can create an event subscription against multiple entities and event types. In the below example, we’re creating an event subscription that will generate events when a Candidate or Placement is created or updated.

Request URI (PUT):
https://rest6.bullhornstaffing.com/rest-services/ABC123/event/subscription/subscriptionID?type=entity\&names=Candidate,Placement\&eventTypes=INSERTED,UPDATED

Replace subscriptionID with the name/identifier of your event subscription.

Example Response:

{
    "lastRequestId": 0, 
    "subscriptionId": "subscriptionID", 
    "createdOn": 1335285871323, 
    "jmsSelector": "JMSType='ENTITY' AND BhCorpId=12345 AND BhEntityName='Candidate','Placement' AND BhEntityeventType IN ('INSERTED','UPDATED')"
}

Retrieve data from an event subscription

When a call to consume events is made, the events will be purged from the event subscription. You should be retrieving events from the event subscription at a regular cadence (IE: hourly, or every 30 minutes). Please keep in mind the following:

• events will expire and be purged if they’re not consumed within 7 days
• You can only have a maximum of 15 event subscriptions per database
• You can only request a maximum of 100 events at a time
• events can’t be limited to specific fields; you’ll need to ignore them programmatically if they’re of no importance to your integration.
• The events will provide the field names in updatedProperties. You’ll need to use the information in the events to make a request to the entity to pull the field’s new value.

The following example request will consume events from the event subscription

Request URI (GET):
https://rest6.bullhornstaffing.com/rest-services/ABC123/event/subscription/subscriptionID?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": "Candidate",
            "entityId": 8592,
            "entityEventType": "UPDATED",
            "updatedProperties": [
                "status",
                "email"
            ]
        }
    ]
}

How to use the data within events

Using the above response, we can determine that PERSON_ID (userID) 1314 updated the entityName (Candidate) and the updatedProperties indicate that the Candidate’s status and email has changed. The eventTimestamp is the epoch value of when the change took place. You can then make a request to pull this data from the record.

Request URI (GET):
https://rest6.bullhornstaffing.com/rest-services/ABC123/entity/Candidate/8592?fields=status,email

Example Response:

{
    "status": "Placed",
    "email": "testcandidate@yopmail.com"
}

Delete an event subscription

To delete an event subscription, simply make a DELETE call to the event subscription. An example of the request is below.

Request URI (DELETE):
https://rest6.bullhornstaffing.com/rest-services/ABC123/event/subscription/subscriptionID

Replace subscriptionID with the name/identifier of your event subscription.

Example Response:

{
    "result": true
}