Skip to main content
POST
/
api
/
hris
/
v1
/
employee-payroll-runs
Create Employee Payroll Run
curl --request POST \
  --url https://api.bindbee.dev/api/hris/v1/employee-payroll-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-connector-token: <x-connector-token>' \
  --data '
{
  "employee": "018b168d-70f9-7043-a796-56d66a4f8f07",
  "payroll_run": "018b709e-b6ef-7db4-902a-a064157bdba2",
  "payroll_process_name": "Hours, Earning Codes",
  "paystatement_type_id": 53123324,
  "payroll_file": "000099",
  "payroll_provider_id": "ECP",
  "payroll_person_id": "1234567890",
  "payroll_employment_id": "1234567890",
  "payroll_group_code": "9YT",
  "gross_pay": 772277.77,
  "net_pay": 577221.27,
  "start_date": "2023-07-01T00:00:00Z",
  "end_date": "2023-07-31T00:00:00Z",
  "check_date": "2023-08-31T00:00:00Z",
  "earnings": [
    {
      "amount": "27151",
      "name": "SALARY"
    }
  ],
  "deductions": [
    {
      "company_deduction": "77.57",
      "employee_deduction": "27.22",
      "name": "Social Security"
    }
  ],
  "taxes": [
    {
      "amount": "175.22",
      "name": "California State Income Tax"
    }
  ]
}
'
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
This endpoint creates an Employee Payroll Run in the connected HRIS via Bindbee’s unified Employee Payroll Runs model.

​
Provider-specific behavior

Different HRIS systems can have slightly different requirements and behaviors when creating payroll runs. Use the accordions below to see details for each provider.

When the underlying HRIS is Workday, an earning can be created using a payload like:

{
  "employee": "019b2647-8e14-7fcf-aa9e-aeff6ab205b2",
  "start_date": "2025-12-01",
  "end_date": "2025-12-31",
  "earnings":
  [
    {
      "type": "Workday_Earning_Code",
      "amount": 200,
      "id": "W_1042S_2015"
    }
  ]
}

Similarly, a deduction can be created using a payload like:

{
  "employee": "019b2647-8e14-7fcf-aa9e-aeff6ab205b2",
  "start_date": "2025-12-01",
  "end_date": "2025-12-31",
  "deductions":
  [
    {
      "type": "Workday_Deduction_Code",
      "amount": 200,
      "id": "W_1042S_2015"
    }
  ]
}

​
Important note

  • For Workday, you can add either earnings or deductions at a time - you cannot add both simultaneously.
  • You can only add 1 earning or deduction at a time, no more than that.
  • payroll_run field must be set to null for Workday integration.
The possible types for earnings are:
  • Workday_Earning_Code
  • WID
The possible types for deductions are:
  • Workday_Deduction_Code
  • WID

When the underlying HRIS is ADP , an employee_payroll_run can be created using a payload like:

{
  "employee": "01929ee7-28b6-7abc-b4d3-e78610669c82",
  "earnings":
    [
      {
        "code": "BN",
        "amount": 0.01
      },
      {
        "code": "R",
        "amount": 0.04
      }
    ],
  "deductions":
    [
      {
        "code": "REI",
        "amount": 0.01
      },
      {
          "code": "KL1",
          "amount": 0.04
      }
    ],
  "taxes":
    [
      {
          "code": "9"
      }
    ],
  "payroll_file": "023321",
  "payroll_process_name": "Ded Ear writeback"
}

When the underlying HRIS is UKG Ready , an employee_payroll_run can be created using a payload like:

{
  "employee": "0194cbef-a29f-7afe-8fb6-bcb706383346",
  "payroll_run": "0194cbef-a8e7-7784-ae98-bb6adaac63c6",
  "paystatement_type_id": 51743758,
  "deductions":
    [
      {
        "company_deduction": 5.5,
        "employee_deduction": 10.2,
        "name": "Student Loan"
      },
      {
        "company_deduction": 1.5,
        "name": "Dental PreTax"
      }
    ],
  "earnings":
    [
      {
        "name": "Overtime",
        "amount": 12.9
      }
    ]
}

When the underlying HRIS is SAP SuccessFactors, an employee_payroll_run can be created using a payload like:

{
  "employee": "019bdafb-0afb-782b-b03b-01c23271653d",
  "payroll_provider_id": "BindBee",
  "payroll_person_id": "310",
  "payroll_employment_id": "270",
  "start_date": "2026-01-26T08:00:00Z",
  "end_date": "2026-01-31T08:00:00Z",
  "deductions": [
    {
      "employee_deduction": 200,
      "name": "401K"
    }
  ],
  "earnings": [
    {
      "name": "GROSS",
      "amount": 2000
    }
  ],
  "taxes": [
    {
      "name": "Testing_Tax",
      "amount": 101
    }
  ]
}

​
Where to find these fields:

  • payroll_provider_id: Use the ID provided by the customer if it’s available. If not, any valid string can be used.
  • payroll_person_id: This value can be found in the employee’s raw_data.
  • payroll_employment_id: Source this either from the employee’s raw_data or from Binbee’s employment model (remote_id).
  • Deductions: When adding deductions, ensure the deduction codes are included in the name field.

​
Important notes

  • All top-level fields are mandatory.
  • earnings, deductions, and taxes can be sent together.
  • All fields inside each array are compulsory.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-connector-token
string
required

Body

application/json
​
employee
string<uuid> | null
required

The employee whose payroll is being run.

Example:

"018b168d-70f9-7043-a796-56d66a4f8f07"

​
payroll_run
string<uuid> | null
default:""

The payroll being run.

Example:

"018b709e-b6ef-7db4-902a-a064157bdba2"

​
payroll_process_name
string | null
default:""

The payroll process name to be displayed.

Example:

"Hours, Earning Codes"

​
paystatement_type_id
integer | null

Id of Employee's Paystatement Type

Example:

53123324

​
payroll_file
string | null
default:""

Employee's Payroll File Number for which earnings are made

Example:

"000099"

​
payroll_provider_id
string | null

Payroll provider identifier.

Example:

"ECP"

​
payroll_person_id
string | null

Payroll person identifier.

Example:

"1234567890"

​
payroll_employment_id
string | null

Payroll employment identifier.

Example:

"1234567890"

​
payroll_group_code
string | null
default:""

The payroll group code the employee belongs to.

Example:

"9YT"

​
gross_pay
default:0

The total earnings throughout a given period for an employee before any deductions are made.

Example:

772277.77

​
net_pay
default:0

The take-home pay throughout a given period for an employee after deductions are made.

Example:

577221.27

​
start_date
string | null
default:""

The day and time the benefit started.

Example:

"2023-07-01T00:00:00Z"

​
end_date
string | null
default:""

The day and time the benefit ended.

Example:

"2023-07-31T00:00:00Z"

​
check_date
string | null
default:""

The day and time the payroll run was checked.

Example:

"2023-08-31T00:00:00Z"

​
earnings
Earnings · object[] | null

The earnings of the Employee

Example:
[{ "amount": "27151", "name": "SALARY" }]
​
deductions
Deductions · object[] | null

The deductions of the Employee

Example:
[
  {
    "company_deduction": "77.57",
    "employee_deduction": "27.22",
    "name": "Social Security"
  }
]
​
taxes
Taxes · object[] | null

The taxes of the Employee

Example:
[
  {
    "amount": "175.22",
    "name": "California State Income Tax"
  }
]

Response

Successful Response