NAV
shell
API Reference Guide
Entity Reference Guide
REST API Change Log

Introduction

Bullhorn Data Hub is a flexible data structure to store data for reporting and analytics across Bullhorn, marketplace partners, and external sources. It is built directly within the Bullhorn ATS Platform to help customers consolidate their staffing and relevant business data in a single location. This reference guide provides information about each Data Hub API operation and supported entity type.

Data Hub Entities

EdsSourceSystem

Represents the external system sending data. This entity’s name is represented as sourceSystem when making Data Hub API requests. See POST / PUT /data-hub/sourceSystem section of Data Hub API for more details.

EdsSourceSystem field Type Description Not null Read-only
name String(64) Name of the source system. X
display String(64) How the source system will be displayed. X

EdsEntityType

Represents a category of data in the source system. This entity’s name is represented as entityType when making Data Hub API requests. See POST / PUT /data-hub/entityType section of Data Hub API for more details.

EdsEntityType field Type Description Not null Read-only
sourceSystem To-one association Source system associated with entity type. X
name String(64) Name of the entity type. X
display String(64) How the entity type will be displayed. X
isPrivate Boolean Determines whether an entity type is private or not. X

EdsEntityTypeSchemaVersion

Represents the structure of data for an entity type. This entity’s name is represented as entityTypeSchemaVersion when making Data Hub API requests. See POST / PUT /data-hub/entityTypeSchemaVersion section of Data Hub API for more details.

EdsEntityTypeSchemaVersion field Type Description Not null Read-only
entityType To-one association Entity type associated with schema version. X
schema String The structure of data for an entity type. X
description String Description of the schema version. X
name String(64) Name of the schema version. X

EdsData

Represents an individual data entry identified by entity type ID and source ID. This entity’s name is represented as data when making Data Hub API requests. See POST /data-hub/data section of Data Hub API for more details.

EdsData field Type Description Not null Read-only
sourceId String(64) Unique identifier for records within a source system. X
entityType To-one association Entity type associated with data record. X
entityTypeSchemaVersion To-one association Schema version associated with data record. X
sourceId String(64) Unique identifier for records within a source system. X
dateAddedInSourceSystem Timestamp Date the record was added in source system. X
dateLastModifiedInSourceSystem Timestamp Date the record was last updated in source system. X
payload String JSON object defined by entity type schema. X
isDeleted Boolean Indicates whether this record has been marked as deleted. X
placementId Integer Identifier for placement.
candidateId Integer Identifier for candidate.
clientContactId Integer Identifier for contact.
clientCorporationId Integer Identifier for corporation.
jobOrderId Integer Identifier for job.
jobSubmissionId Integer Identifier for job submission.
leadId Integer Identifier for lead.
opportunityId Integer Identifier for opportunity.
corporateUserId Integer Identifier for corporate user.
noteId Integer Identifier for note.
appointmentId Integer Identifier for appointment.
payableChargeId Integer Identifier for payable charge.
billableChargeId Integer Identifier for billable charge.

Data Hub API

The Data Hub API allows partners to pass customer data to Data Hub where it is replicated onwards to Bullhorn Analytics and Data Replicator. All Data Hub API calls must be made with a valid BH REST Token and accepts UTF-8 encoded JSON via HTTP. This will section list examples of all the Data Hub endpoints.

The Data Hub API is secured in the same manner as the Bullhorn REST API. For a full guide on logging into the API and authorizing a request please follow this documentation: Authorization

POST /data-hub/data

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/data-hub/data

# Example Request
[
    {
        "sourceSystem": "sourceSystemName",
        "entityType": "entityTypeName",
        "schemaVersion": "schemaVersionName",
        "items": [
            {
                "sourceId": 1,
                "dateAddedInSourceSystem": "2024-11-31T17:48:17.182+00:00",
                "dateLastModifiedInSourceSystem": "2024-11-31T17:48:17.182+00:00",
                "payload": "{ \"name\": \"bob\", \"age\": 25, \"address\": { \"street\": \"789 Main St\", \"city\": \"New York\", \"state\": \"NY\", \"postalCode\": \"10001\" }, \"hobbies\": [\"reading\", \"running\"] }",
                "isDeleted": false,
                "placementId": 107,
                "candidateId": 123,
                "clientContactId": 55,
                "clientCorporationId": 55,
                "jobOrderId": 123,
                "jobSubmissionId": 123,
                "leadId": 123,
                "opportunityId": 465,
                "corporateUserId": 123,
                "noteId": 123,
                "appointmentId": 123,
                "payableChargeId": 123,
                "billableChargeId": 134
            },
            {
                "sourceId": 2,
                "dateAddedInSourceSystem": "2024-11-31T17:48:17.182+00:00",
                "dateLastModifiedInSourceSystem": "2024-11-31T17:48:17.182+00:00",
                "payload": "{ \"name\": \"sam\", \"age\": 30, \"address\": { \"street\": \"123 Main St\", \"city\": \"Dallas\", \"state\": \"TX\", \"postalCode\": \"75001\" }, \"hobbies\": [\"gaming\", \"running\"] }",
                "isDeleted": false,
                "placementId": 107,
                "candidateId": 123,
                "clientContactId": 55,
                "clientCorporationId": 55,
                "jobOrderId": 123,
                "jobSubmissionId": 123,
                "leadId": 123,
                "opportunityId": 465,
                "corporateUserId": 123,
                "noteId": 123,
                "appointmentId": 123,
                "payableChargeId": 123,
                "billableChargeId": 134
            }
            // up to 100 items
        ]
    }
]

# Example Response
{
    "statusCode": 200,
    "messages": [],
    "data": [
        {
            "entityType": "entityTypeName",
            "sourceSystem": "sourceSystemName",
            "totalSuccessfulItems": 1,
            "successfulItems": [
                {
                    "sourceId": "1",
                    "dataId": 1234
                },
                {
                    "sourceId": "2",
                    "dataId": 1235
                }
            ]
        }
    ]
}

Upserts up to 100 records to Data Hub. Payload must be formatted according to schema definition setup for the corporation.

HTTP Request

{corpToken}/data-hub/data

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 /data-hub/data/find

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/data-hub/data/find

# Example Request
{
    "criteria": {
        "and": [
            {
                "entityType.name": {
                    "equalTo": "entityTypeName"
                }
            },
            {
                "sourceId": {
                   "in": ["2","7"] 
                }
            },
            {
                "entityType.sourceSystem.name": {
                    "equalTo": "sourceSystemName"
                }
            }
        ]
    }
}

# Example Response
{
    "statusCode": 200,
    "messages": null,
    "data": {
        "start": 0,
        "count": 1,
        "total": 1,
        "data": [
            {
                "dataId": 1234,
                "sourceId": "2",
                "entityType": {
                    "entityTypeId": 241,
                    "name": "entityTypeName"
                },
                "entityTypeSchemaVersion": {
                    "entityTypeSchemaVersionId": 441,
                    "name": "schemaVersionName"
                },
                "dateAdded": "2025-01-10T22:56:18.012+00:00",
                "dateLastModified": "2025-01-10T22:56:18.012+00:00",
                "dateAddedInSourceSystem": "2024-12-01T17:48:17.000+00:00",
                "dateLastModifiedInSourceSystem": "2024-12-01T17:48:17.000+00:00",
                "payload": "{ \"name\": \"John Smith\", \"age\": 25, \"address\": { \"street\": \"789 Main St\", \"city\": \"New York\", \"state\": \"NY\", \"postalCode\": \"10001\" }, \"hobbies\": [\"reading\", \"running\"] }",
                "isDeleted": false,
                "candidateId": 123,
                "clientContactId": 10,
                "clientCorporationId": 456,
                "jobOrderId": 123,
                "jobSubmissionId": 123,
                "placementId": 123,
                "leadId": 123,
                "opportunityId": 123,
                "corporateUserId": 123,
                "noteId": 123,
                "appointmentId": 123,
                "payableChargeId": 123,
                "billableChargeId": 134,
                "entityId": 342
            }
        ]
    }
}

Used to lookup and view Data Hub records using adaptive query.

HTTP Request

{corpToken}/data-hub/sourceSystem

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 / PUT /data-hub/sourceSystem

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/data-hub/sourceSystem

# Example Request
{
    "name": "sourceSystemName",
    "display": "sourceSystemDisplay"
}

# Example Response
{
    "changedEntityType": "SourceSystem",
    "changedEntityId": 293,
    "changeType": "INSERT",
    "data": {
        "name": "sourceSystemName",
        "display": "sourceSystemDisplay"
    }
}

Used to add or update source systems.

HTTP Request

{corpToken}/data-hub/sourceSystem and {corpToken}/data-hub/sourceSystem/{sourceSystemId}

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 / PUT /data-hub/entityType

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/data-hub/entityType

# Example Request
{
    "sourceSystem": {
        "id": 293 // Can also associate source system using sourceSystem.name
    },
    "name": "entityTypeName",
    "display": "entityTypeDisplay",
    "isPrivate": true
}

# Example POST Response
{
    "changedEntityType": "EntityType",
    "changedEntityId": 311,
    "changeType": "INSERT",
    "data": {
        "display": "TiffTests33",
        "name": "TiffTestLetsGO!CertVid-2234",
        "sourceSystem": {
            "id": 293
        },
        "isPrivate": true
    }
}

Used to add or update entity types.

HTTP Request

{corpToken}/data-hub/entityType and {corpToken}/data-hub/entityType/{entityTypeId}

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 / PUT /data-hub/entityTypeSchemaVersion

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/data-hub/entityTypeSchemaVersion

# Example Request associating entity type by entityTypeId
{
    "entityType": {
        "id": 311
    },
    "schema": "{\n  \"$id\": \"https://example.com/person.schema.json\",\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"description\": \"Schema for a person with name, age, address, and hobbies\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"description\": \"Name of the person\"\n    },\n    \"age\": {\n      \"type\": \"integer\",\n      \"description\": \"Age of the person\"\n    },\n    \"address\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"street\": {\n          \"type\": \"string\",\n          \"description\": \"Street address\"\n        },\n        \"city\": {\n          \"type\": \"string\",\n          \"description\": \"City name\"\n        },\n        \"state\": {\n          \"type\": \"string\",\n          \"description\": \"State abbreviation\"\n        },\n        \"postalCode\": {\n          \"type\": \"string\",\n          \"description\": \"Postal code\"\n        }\n      },\n      \"required\": [\"street\", \"city\", \"state\", \"postalCode\"],\n      \"description\": \"Address of the person\"\n    },\n    \"hobbies\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"description\": \"List of hobbies\"\n    }\n  },\n  \"required\": [\"name\", \"age\", \"address\", \"hobbies\"]\n}",
    "description": "New Schema Version",
    "name":"schemaVersionName"
}

# Example Request associating entity type by entityTypeName and sourceSystemName
{
    "entityType": {
        "name": "entityTypeName",
         "sourceSystem": {
            "name": "sourceSystemName"
        }
    },
    "schema": "{\n  \"$id\": \"https://example.com/person.schema.json\",\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"description\": \"Schema for a person with name, age, address, and hobbies\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"description\": \"Name of the person\"\n    },\n    \"age\": {\n      \"type\": \"integer\",\n      \"description\": \"Age of the person\"\n    },\n    \"address\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"street\": {\n          \"type\": \"string\",\n          \"description\": \"Street address\"\n        },\n        \"city\": {\n          \"type\": \"string\",\n          \"description\": \"City name\"\n        },\n        \"state\": {\n          \"type\": \"string\",\n          \"description\": \"State abbreviation\"\n        },\n        \"postalCode\": {\n          \"type\": \"string\",\n          \"description\": \"Postal code\"\n        }\n      },\n      \"required\": [\"street\", \"city\", \"state\", \"postalCode\"],\n      \"description\": \"Address of the person\"\n    },\n    \"hobbies\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"description\": \"List of hobbies\"\n    }\n  },\n  \"required\": [\"name\", \"age\", \"address\", \"hobbies\"]\n}",
    "description": "New Schema Version",
    "name":"schemaVersionName"
}


# Example POST Response
{
    "changedEntityType": "EntityTypeSchemaVersion",
    "changedEntityId": 507,
    "changeType": "INSERT",
    "data": {
        "schema": "{\n  \"$id\": \"https://example.com/person.schema.json\",\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"description\": \"Schema for a person with name, age, address, and hobbies\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"description\": \"Name of the person\"\n    },\n    \"age\": {\n      \"type\": \"integer\",\n      \"description\": \"Age of the person\"\n    },\n    \"address\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"street\": {\n          \"type\": \"string\",\n          \"description\": \"Street address\"\n        },\n        \"city\": {\n          \"type\": \"string\",\n          \"description\": \"City name\"\n        },\n        \"state\": {\n          \"type\": \"string\",\n          \"description\": \"State abbreviation\"\n        },\n        \"postalCode\": {\n          \"type\": \"string\",\n          \"description\": \"Postal code\"\n        }\n      },\n      \"required\": [\"street\", \"city\", \"state\", \"postalCode\"],\n      \"description\": \"Address of the person\"\n    },\n    \"hobbies\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"description\": \"List of hobbies\"\n    }\n  },\n  \"required\": [\"name\", \"age\", \"address\", \"hobbies\"]\n}",
        "description": "New Schema Version",
        "name": "schemaVersionName",
        "entityType": {
            "id": 311
        }
    }
}

Used to add or update entity type schema versions.

HTTP Request

{corpToken}/data-hub/entityTypeSchemaVersion and {corpToken}/data-hub/entityTypeSchemaVersion/{schemaVersionId}

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.

GET /data-hub

curl https://rest{swimlane#}.bullhornstaffing.com/rest-services/e999/data-hub/entityType/311

# Example Response
{
    "data": {
        "entityTypeId": 311,
        "display": "entityTypeDisplay",
        "name": "entityTypeName",
        "sourceSystem": {
            "id": 293,
            "name": "sourceSystemName"
        },
        "isPrivate": true,
        "entityTypesSchemaVersions": {
            "data": [],
            "count": 1
        },
        "data": {
            "data": [],
            "count": 2
        }
    }
}

Used to retrieve information about a source system, entity type, or schema version.

HTTP Request

{corpToken}/data-hub/{entityName}/{entityId}

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.

Errors

The Data Hub API uses the following error codes:

Error Code Meaning
206 Partial Content – The request has only partially succeeded. One or more of the records in the request failed to be stored in Data Hub.
413 Request Entity Too Large – The request has more than 100 items and Data Hub will only process 100 records at a time.
400 Bad Request – The request was unsuccessful. All records failed to be processed.
401 Unauthorized – Your API key is wrong or expired
404 Not Found – The specified entity could not be found
500 Internal Server Error – We had a problem with our server.




shell