Payroll

There are four primary entities used in building the BambooHR paystub experience:

  • Raw paystub data
  • Pay period dates (past, current, and future)
  • Direct deposit settings
  • Tax withholding settings

All of the information displayed as part of the paystub experience is read-only, although employees may navigate through paystub history, view specific paystub details, and then download or print the paystub.

Raw paystub data (income, withholdings, deductions, etc.) and pay period data (past, present, and future) are required to generate the primary paystub experience in BambooHR. Direct deposit and tax withholding data completes the experience for the employee, but is not critical. If no direct deposit or tax withholding data are provided, those portions of the experience will not be displayed to the employee user.

Add an employee's default withholdings
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employee_withholding/{employeeId}
Success Response:
200 - Additionally, the saved values for the employee withholdings will be returned in JSON.
Failure Response:

403 - if the current user doesn't have access to add employee withholdings information.

400 - if an invalid employee ID is provided, or the posted JSON is not valid.

Sample Request:
POST /api/gateway.php/test/v1/employee_withholding/1234

Sample POST Data:

{
  "fedWithholding": 4,
  "stateWithholding": 4,
  "localWithholding": "0",
  "additionalFed": "0",
  "additionalState": "0",
  "additionalLocal": "0",
  "taxState": "UT",
  "taxLocal": ""
}
Get an employee's default withholdings
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employee_withholding/{employeeId}
Success Response:
200 - The response content will be an JSON document with the requested information.
Failure Response:

400 - Invalid employee ID is provided

Sample Request:
GET /api/gateway.php/test/v1/employee_withholding/1234

Sample Response:

{
  "Employee Withholdings": [
    {
      "fedWithholding": "4",
      "stateWithholding": "4",
      "localWithholding": "0",
      "additionalFed": "0",
      "additionalState": "0",
      "additionalLocal": "0",
      "taxState": "UT",
      "taxLocal": null
    }
  ]
}
Clear an employee's default withholdings
HTTP Method:
DELETE
Path:
/api/gateway.php/{company}/v1/employee_withholding/{employeeId}
Success Response:
200 - The response content will be an JSON success document.
Failure Response:

403 - if the API user doesn't have access to edit the employee withholdings information.

400 - Invalid employee ID is provided

Sample Request:
DELETE /api/gateway.php/test/v1/employee_withholding/1234

Sample Response:

{
  "success": true,
  "message": "Employee tax withholding data cleared"
}
Add an employee's direct deposit information
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employee_direct_deposit_accounts/{employeeId}
Notes:

There must be at least one account JSON object.

There can only be one BAL rule type for an employee and that must be the last depositOrder rule.

accountType: 'checking','savings','other'

maskedAccountNumber: in the following format X-nnnn

ruleType: 'FLAT' for a flat amount to deposit, 'PCT' For a percentage amount, 'BAL' for the balance

ruleAmount: Tied to the ruleType. Leave null for BAL rule type

All properties are required.

Success Response:
200 - The saved values for the employee's direct deposit declarations will be returned in JSON.
Failure Response:

403 - if the current user doesn't have access to update the employee's direct deposit declarations.

400 - if an invalid employee ID is provided, or the posted JSON is not valid.

Sample Request:
POST /api/gateway.php/test/v1/employee_direct_deposit_accounts/1234

Sample POST Data:

{
    "accounts": [
        {
            "accountType": "checking",
            "maskedAccountNumber": "X-8601",
            "bankName": "JP Morgan Chase Bank NA",
            "depositOrder": 0,
            "ruleType": "FLAT",
            "ruleAmount": 2000.00
        },
        {
            "accountType": "savings",
            "maskedAccountNumber": "X-2542",
            "bankName": "America First Credit Union",
            "depositOrder": 1,
            "ruleType": "PCT",
            "ruleAmount": 50.00
        },
        {
            "accountType": "checking",
            "maskedAccountNumber": "X-8601",
            "bankName": "Goldman Sacks",
            "depositOrder": 2,
            "ruleType": "BAL",
            "ruleAmount": null
        }
    ]
}

Sample Response:

{
  "Employee Id": "1234",
  "Employee Name": "Robert Binetti",
  "Employee Direct Deposit Accounts": [
    {
      "id": "1",
      "employeeId": "1234",
      "accountType": "checking",
      "maskedAccountNumber": "X-8601",
      "bankName": "JP Morgan Chase Bank NA",
      "depositOrder": "0",
      "ruleType": "FLAT",
      "ruleAmount": "2000.00",
      "createdAt": "2015-11-18 23:13:43",
      "updatedAt": null
    },
    {
      "id": "2",
      "employeeId": "1234",
      "accountType": "savings",
      "maskedAccountNumber": "X-2542",
      "bankName": "America First Credit Union",
      "depositOrder": "1",
      "ruleType": "PCT",
      "ruleAmount": "50.00",
      "createdAt": "2015-11-18 23:13:43",
      "updatedAt": null
    },
    {
      "id": "3",
      "employeeId": "1234",
      "accountType": "checking",
      "maskedAccountNumber": "X-8601",
      "bankName": "Goldman Sacks",
      "depositOrder": "2",
      "ruleType": "BAL",
      "ruleAmount": null,
      "createdAt": "2015-11-18 23:13:43",
      "updatedAt": null
    }
  ]
}
Get an employee's direct deposit information
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employee_direct_deposit_accounts/{employeeId}
Success Response:
200 - The response content will be an JSON document with the requested information.
Failure Response:

400 - Invalid employee ID is provided

Sample Request:
GET /api/gateway.php/test/v1/employee_direct_deposit_accounts/1234

Sample Response:

{
  "Employee Id": "1234",
  "Employee Name": "Robert Binetti",
  "Employee Direct Deposit Accounts": [
    {
      "id": "1",
      "employeeId": "1234",
      "accountType": "checking",
      "maskedAccountNumber": "X-8601",
      "bankName": "JP Morgan Chase Bank NA",
      "depositOrder": "0",
      "ruleType": "FLAT",
      "ruleAmount": "2000.00",
      "createdAt": "2015-11-18 23:13:43",
      "updatedAt": null
    },
    {
      "id": "2",
      "employeeId": "1234",
      "accountType": "savings",
      "maskedAccountNumber": "X-2542",
      "bankName": "America First Credit Union",
      "depositOrder": "1",
      "ruleType": "PCT",
      "ruleAmount": "50.00",
      "createdAt": "2015-11-18 23:13:43",
      "updatedAt": null
    },
    {
      "id": "3",
      "employeeId": "1234",
      "accountType": "checking",
      "maskedAccountNumber": "X-8601",
      "bankName": "Goldman Sacks",
      "depositOrder": "2",
      "ruleType": "BAL",
      "ruleAmount": null,
      "createdAt": "2015-11-18 23:13:43",
      "updatedAt": null
    }
  ]
}
Clear an employee's direct deposit information
HTTP Method:
DELETE
Path:
/api/gateway.php/{company}/v1/employee_direct_deposit_accounts/{employeeId}
Success Response:
200 - The response content will be an JSON success document.
Failure Response:

403 - if the API user doesn't have access to edit the employee's direct deposit declarations.

400 - Invalid employee ID is provided

Sample Request:
DELETE /api/gateway.php/test/v1/employee_direct_deposit_accounts/1234

Sample Response:

{
  "success": true,
  "message": "Employee direct deposit account data cleared"
}
Add an employee's unpaid paystubs
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employee_unpaid_pay_stubs
Notes:

All properties are required.

unpaidPeriods is an Array of unpaidPeriod JSON Objects

payDate: ISO Date Format (YYYY-MM-DD format)

Success Response:
200 - Additionally, the saved values for the employee's unpaid pay stubs will be returned in JSON.
Failure Response:

403 - if the current user doesn't have access to add employee unpaid pay stub information.

400 - if an invalid employee ID is provided, or the posted JSON is not valid.

Sample Request:
POST /api/gateway.php/test/v1/employee_unpaid_pay_stubs

Sample Request/Response:

{
    "employeeId": 1234,
    "unpaidPeriods": [
        {
            "payDate": "2015-11-20"
        },
        {
            "payDate": "2015-12-05"
        },
        {
            "payDate": "2015-12-20"
        }
    ]
}
Get an employee's unpaid paystubs
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employee_unpaid_pay_stubs/{employeeId}
Success Response:
200 - The response content will be an JSON document with the requested information.
Failure Response:

400 - Invalid employee ID is provided

Sample Request:
GET /api/gateway.php/test/v1/employee_unpaid_pay_stubs/1234

Sample Response:

{
    "employeeId": 1234,
    "unpaidPeriods": [
        {
            "payDate": "2015-11-20"
        },
        {
            "payDate": "2015-12-05"
        },
        {
            "payDate": "2015-12-20"
        }
    ]
}
Clear an employee's unpaid paystubs
HTTP Method:
DELETE
Path:
/api/gateway.php/{company}/v1/employee_unpaid_pay_stubs/{employeeId}
Success Response:
200 - The response content will be an JSON success document.
Failure Response:

403 - if the API user doesn't have access to edit the employee unpaid paystub information.

400 - Invalid employee ID is provided

Sample Request:
DELETE /api/gateway.php/test/v1/employee_unpaid_pay_stubs/1234

Sample Response:

{
  "success": true,
  "message": "Employee unpaid pay stubs deleted"
}
Add an employee's paystub
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employee_pay_stub
Notes:

The Sample Request below is what is the required minimum elements to create a paystub record

currencyCode: Please use the ISO 3 Character Currency Code

All dates need to be submitted in ISO Date Format. (YYYY-MM-DD format)

For proper grouping of wage types, taxes and deductions please keep your external IDs consistent.

maskedAccountNumber needs to be provided in the following format: X-nnnn

BambooHR does not provide any validation of YTD accumulators. the data is stored for display purposes only.

Success Response:
200 - Additionally, the saved values for the employee's paystub record will be returned in JSON along with its record ID.
Failure Response:

403 - if the current user doesn't have access to add an employee pay stub.

400 - if an invalid employee ID is provided, or the posted JSON is not valid.

Sample Request:
POST /api/gateway.php/test/v1/employee_pay_stub

Sample Request:

{
    "employeeId": 1234,
    "externalRecordId": "B45381984",
    "payPeriodFrom": "2015-08-16",
    "payPeriodTo": "2015-08-31",
    "payDate": "2015-09-05",
    "payorName": "BambooHR",
    "payorAdd1": "333 South 520 West",
    "payorAdd2": "Suite 200",
    "payorCity": "Lindon",
    "payorState": "UT",
    "payorZip": "84042-1911",
    "payeeName": "Robert M. Binetti",
    "currencyCode": "USD",
    "net": 3272.50,
    "gross": 5000.50,
    "totalTaxes": 795.12,
    "totalDeductions": 932.38,
    "ytdNet": 55632.50,
    "ytdGross": 85000.50,
    "ytdTaxes": 13517.04,
    "ytdDeductions": 15850.46,
    "fedWithholding": 4,
    "stateWithholding": 4,
    "localWithholding": null,
    "additionalFed": null,
    "additionalState": null,
    "additionalLocal": null,
    "taxState": "UT",
    "taxLocal": null,
    "wages": [
        {
            "externalWageId": "BASE",
            "wageDescription": "Salary",
            "wageAmount": 5000.00,
            "ytdWageAmount": 85000.00,
            "wageRate": 0.0,
            "hours": 0.0
        }
    ],
    "taxes": [
        {
            "externalTaxId": "FED",
            "taxDescription": "Federal Income Tax",
            "taxAmount": 278.93,
            "ytdTaxAmount": 4741.81
        },
        {
            "externalTaxId": "SS",
            "taxDescription": "Social Security",
            "taxAmount": 306.25,
            "ytdTaxAmount": 5206.25
        },
        {
            "externalTaxId": "MEDI",
            "taxDescription": "Medicaid",
            "taxAmount": 9.94,
            "ytdTaxAmount": 168.98
        },
        {
            "externalTaxId": "STATE-UT",
            "taxDescription": "Utah State Income Tax",
            "taxAmount": 200.00,
            "ytdTaxAmount": 3400.00
        }
    ],
    "deductions": [
         {
            "externalDeductionId": "MED-UHC-BASE-PPO",
            "deductionDescription": "Medical - UHC Traditional",
            "deductionAmount": 217.24,
            "ytdDeductionAmount": 3693.08
        },
        {
            "externalDeductionId": "DENTAL-VALUE",
            "deductionDescription": "Dental - Delta Value",
            "deductionAmount": 47.25,
            "ytdDeductionAmount": 803.25
        },
        {
            "externalDeductionId": "401K",
            "deductionDescription": "401(k)",
            "deductionAmount": 667.89,
            "ytdDeductionAmount": 11354.13
        }
    ],
    "deposits": [
        {
            "depositOrder": "1",
            "depositAmount": 2272.50,
            "maskedAccountNumber": "X-8601",
            "accountType": "checking"
        },
        {
            "depositOrder": "2",
            "depositAmount": 1000.00,
            "maskedAccountNumber": "X-7124",
            "accountType": "savings"
        }
    ]
}
Get an employee's paystub
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employee_pay_stub/{recordId}
Success Response:
200 - The response content will be an JSON document with the requested information.
Failure Response:

400 - Record ID is not found

Sample Request:
GET /api/gateway.php/test/v1/employee_pay_stub/1

Sample Response:

{
  "recordId": "1",
  "employeeId": "1234",
  "externalRecordId": "B45381984",
  "payPeriodFrom": "2015-08-16",
  "payPeriodTo": "2015-08-31",
  "payDate": "2015-09-05",
  "payorName": "BambooHR",
  "payorAdd1": "333 South 520 West",
  "payorAdd2": "Suite 200",
  "payorCity": "Lindon",
  "payorState": "UT",
  "payorZip": "84042-1911",
  "payeeName": "Robert M. Binetti",
  "currencyCode": "USD",
  "net": "3272.50",
  "gross": "5000.50",
  "totalTaxes": "795.12",
  "totalDeductions": "932.38",
  "ytdNet": "55632.50",
  "ytdGross": "85000.50",
  "ytdTaxes": "13517.04",
  "ytdDeductions": "15850.46",
  "fedWithholding": "4",
  "stateWithholding": "4",
  "localWithholding": null,
  "additionalFed": null,
  "additionalState": null,
  "additionalLocal": null,
  "taxState": "UT",
  "taxLocal": null,
  "wages": [
    {
      "externalWageId": "BASE",
      "wageDescription": "Salary",
      "wageRate": null,
      "hours": null,
      "wageAmount": "5000.00",
      "ytdWageAmount": "85000.00"
    }
  ],
  "taxes": [
    {
      "externalTaxId": "FED",
      "taxDescription": "Federal Income Tax",
      "taxAmount": "278.93",
      "ytdTaxAmount": "4741.81"
    },
    {
      "externalTaxId": "SS",
      "taxDescription": "Social Security",
      "taxAmount": "306.25",
      "ytdTaxAmount": "5206.25"
    },
    {
      "externalTaxId": "MEDI",
      "taxDescription": "Medicaid",
      "taxAmount": "9.94",
      "ytdTaxAmount": "168.98"
    },
    {
      "externalTaxId": "STATE-UT",
      "taxDescription": "Utah State Income Tax",
      "taxAmount": "200.00",
      "ytdTaxAmount": "3400.00"
    }
  ],
  "deductions": [
    {
      "externalDeductionId": "MED-UHC-BASE-PPO",
      "deductionDescription": "Medical - UHC Traditional",
      "deductionAmount": "217.24",
      "ytdDeductionAmount": "3693.08"
    },
    {
      "externalDeductionId": "DENTAL-VALUE",
      "deductionDescription": "Dental - Delta Value",
      "deductionAmount": "47.25",
      "ytdDeductionAmount": "803.25"
    },
    {
      "externalDeductionId": "401K",
      "deductionDescription": "401(k)",
      "deductionAmount": "667.89",
      "ytdDeductionAmount": "11354.13"
    }
  ],
  "deposits": [
    {
      "depositOrder": "1",
      "depositAmount": "2272.50",
      "maskedAccountNumber": "X-8601",
      "accountType": "checking"
    },
    {
      "depositOrder": "2",
      "depositAmount": "1000.00",
      "maskedAccountNumber": "X-7124",
      "accountType": "savings"
    }
  ]
}
Delete an employee's paystub
HTTP Method:
DELETE
Path:
/api/gateway.php/{company}/v1/employee_pay_stub/{recordId}
Success Response:
200 - The response content will be an JSON success document.
Failure Response:

403 - if the API user doesn't have access to delete the employee paystub.

400 - Invalid record ID was provided

Sample Request:
DELETE /api/gateway.php/test/v1/employee_pay_stub/1

Sample Response:

{
  "success": true,
  "message": "Employee pay stub deleted"
}
Get payroll deductions for employee
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/payroll/deductions/{employeeId}
Notes:

The owner of the API key used must have access to benefit settings.

Employee ID is required.

You can send an Accept Header of application/json to retrieve a JSON Response

Sample Request:
GET /api/gateway.php/test/v1/payroll/deductions/1

Sample Response:

<?xml version="1.0"?>
<payrollDeductions employeeId="1" payFrequency="Monthly">
    <deduction employeePays="250.00" companyPays="1000.00" currencyCode="USD" employeePaysType="$" companyPaysType="$" coverageType="Employee + Family" effectiveDate="01/01/2017" benefitPlanName="South Park Health" benefitPlanId="1"/>
    <deduction employeePays="100.00" companyPays="100.00" currencyCode="USD" employeePaysType="$" companyPaysType="$" coverageType="" effectiveDate="01/01/2017" benefitPlanName="SP 401(k)" benefitPlanId="2"/>
</payrollDeductions>

Have more questions? We're here to help, so please contact us.