Payroll Providers and Pay Check Information

Summary

Payroll providers can send pay check details through the Bullhorn REST API and attach them to Candidate records in the Bullhorn system. This data can be viewed from the PAYCHECKS tab on a Candidate record.

Paycheck visibility is currently only enabled by Bullhorn Support. If your client would like to view pay check data within the Bullhorn application, please instruct the client to contact Bullhorn Support and request the Paycheck Visibility tab on Candidate records.

Getting started with Paychecks

The JSON payload sent to Bullhorn consists of two parts: deduction category payload and paychecks payload. The examples below show accurate data to populate the User Interface for this feature.

Deduction Category Payload

The deduction category payload is used to send any additional deduction category types the payroll provider uses. Bullhorn provides three deduction category types:

• Tax
• Deduction
• Other

Note: Payroll providers must submit a new Deduction Payload for each Bullhorn client.

Deduction Category Types must be added before the Paychecks Payload in order to utilize and reference any new deduction types. Sending a Paychecks Payload with a Deduction Category Type that doesn’t exist will result in an error being thrown by the REST API.

Bullhorn will send an error message and prevent the Paychecks Payload from being posted if a Deduction Type is referenced in the Paychecks Payload without being added with the Deduction Category Payload first.

If your payroll provider needs to add additional deduction categories beyond Tax, Deduction, and Other the following call must be done before sending a call for adding Paycheck information for each account. Deduction categories are unique for each Client Corporation.

Make a PUT call to the following endpoint.

Note: Bullhorn supports create/PUT, update/POST, and get/GET requests. Bullhorn does not support delete/DELETE requests.

https://rest{cls}.bullhornstaffing.com/rest-services/{token}/entity/DeductionCategoryLookup

The following example shows a deduction category payload:

{
    "isDeleted": false,
    "label": "Example Category Label"
}

Below is an example of the REST API response::

{
    "changedEntityType": "DeductionCategoryLookup",
    "changedEntityId": 123,
    "changeType": "INSERT",
    "data": {
        "isDeleted": false,
        "label": "Example Category Label"
    }
}

Paychecks Payload

The paychecks payload is used to send over paycheck data to Bullhorn. It supports multiple paycheck submissions in a single payload.

The checkNumber field is the unique identifier for this feature. If the payroll provider sends multiple paychecks, this is the field Bullhorn checks to display unique data. If the next paycheck sends with the same checkNumber, Bullhorn currently ignores it and does nothing.

The employeeTotalDeduction field should be provided by the payroll provider and lists the total amount of the deductions listed in the employeeTaxDeduction array. Bullhorn will not do any validations to verify that this equals the sum of the individual deductions that will be displayed to the customer.

Make a PUT call to the following endpoint.

Note: Bullhorn does not support update/POST or delete/DELETE requests.

https://rest{cls}.bullhornstaffing.com/rest-services/{token}/services/PayCheck

The following example shows a paychecks payload:

{
    "payChecks": [
        {
            "voucherID": "009212",
            "payExportBatchExternal": null,
            "type": "ACH",
            "checkNumber": "910002",
            "checkDate": 1579478400,
            "isVoid": false,
            "payDate": 1579478400,
            "externalPayrollEmployeeID": "Y22449",
            "candidateID": 1199,
            "payPeriod": "C",
            "periodStartDate": 1579478400,
            "periodEndDate": 1579478400,
            "grossPay": 20000,
            "netPay": 0,
            "fitTaxableAmount": 20000,
            "earnAmount": 20000,
            "otherEarnAmount": 0,
            "employeeTaxDeductions": [
                {
                    "code": "00-15",
                    "description": "FEDERAL INCOME TAX",
                    "taxableAmount": 20000,
                    "taxAmount": 3500.50,
                    "overLimitAmount": 0,
                    "deductionCategoryLookup": {
                        "deductionCategoryLookupID": 3
                    }
                },
                {
                    "code": "00-14",
                    "description": "401 K Retirement",
                    "taxableAmount": 20000,
                    "taxAmount": 1500,
                    "overLimitAmount": 0,
                    "deductionCategoryLookup": {
                        "deductionCategoryLookupID": 1
                    }
                }
            ],
            "employerContributions": [
                {
                    "code": "Dental",
                    "description": "Dental Insurance",
                    "amount": 5
                }
            ],
            "employeePays": [
                {
                    "earnCodeName": "REG",
                    "chargeDate": 1579478400,
                    "hoursUnits": 36,
                    "hoursWorked": 40,
                    "unitRate": 250,
                    "amount": 9000,
                    "jobCode": "BAKER",
                    "shift": "",
                    "department": "DEPT1",
                    "location": "Bullhorn Boston",
                    "glCode": "",
                    "workCompID": "8810",
                    "projWork": "",
                    "projPhase": ""
                }
            ],
            "employeeTotalDeduction": 5300
        }
    ]
}