Submit Payroll Data
Submit pending earnings and deductions ahead of a run, and manage recurring deductions like 401k.
This guide covers bringing payroll data into Netchex: one-time pending amounts ahead of a run, and recurring scheduled deductions like a 401k contribution that repeats every paycheck. See the Glossary for the difference between a pending amount and a scheduled deduction.
Look up valid companyEarningId/companyDeductionId values with Payroll Reference Data before submitting. These are your company's configured earning and deduction types, not something you invent.
Pending earnings and deductions
A pending amount applies to an employee's current or upcoming paycheck a single time.
Pending earnings
POST https://external-app-prod.netchexonline.net/pending-paycheck-earnings?api-version=3.0
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json[
{
"companyId": 101,
"employeeId": 5001,
"companyEarningId": 3,
"date": "2024-01-22",
"flatAmount": { "amount": 500.00 },
"laborDistributedDepartmentId": 10,
"laborDistributedClientProject": null,
"laborDistributedJobCode": null,
"workersCompensationCode": null
}
][
{ "ids": ["PE-1001"], "externalUniqueId": null, "dataSource": "ExternalApi" }
]Each item specifies exactly one amount type: flatAmount.amount (non-zero), unitsAmount.units (non-zero, at the earning's standard rate), or unitsAndRateAmount with both units and rate (rate greater than zero). Don't send more than one. laborDistributedDepartmentId and the other laborDistributed*/workersCompensationCode fields are optional cost-allocation metadata, they label which department, client/project, or job code the cost is attributed to, they don't affect the amount paid.
Batches of up to 500 items, but validation is whole-batch, not per item: if any item is inaccessible, specifies more than one amount type, or fails the non-zero amount check, the entire request returns 400 and nothing is submitted. There's no partial success here, fix every item before resubmitting.
You can read back what's already been submitted with GET /pending-paycheck-earnings, filterable by company-earning-id, pending-paycheck-earning-ids, external-unique-id, data-source, and an effective-date-from/effective-date-to range.
Pending deductions
POST https://external-app-prod.netchexonline.net/pending-paycheck-deductions?api-version=3.0
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json[
{
"companyId": 101,
"employeeId": 5001,
"companyDeductionId": 11,
"date": "2024-01-22",
"flatAmount": { "employeeAmount": 50.00, "employerAmount": 0 }
}
]The only supported amount type for deductions is flatAmount. At least one of employeeAmount or employerAmount must be non-zero. Same batching rules as pending earnings: up to 500 items, whole-batch validation, one invalid item fails the entire request.
GET /pending-paycheck-deductions reads these back, with the same filter shape as pending earnings above (company-deduction-id, pending-paycheck-deduction-ids, external-unique-id, data-source, effective-date-from/effective-date-to).
Recurring deductions, including 401k
Some deductions aren't one-time. They repeat every paycheck, or on a defined schedule, until changed or stopped, this is how retirement contributions and ongoing insurance premiums are represented.
GET https://external-app-prod.netchexonline.net/employee-scheduled-deductions?employee-ids=5001&api-version=3.0
Authorization: ApiKey YOUR_API_KEY{
"pageNumber": 1,
"pageSize": 100,
"totalItemsCount": 1,
"items": [
{
"employeeDeductionId": 90001,
"employeeId": 5001,
"companyDeductionId": 10,
"companyId": 101,
"categoryGroup": "Voluntary",
"isLocked": false,
"isActive": true,
"voluntaryDeduction": {
"employeeContributionAmount": { "flatAmount": null, "percentage": 6.0 },
"frequency": "Recurring",
"effectiveFrom": "2024-01-01T00:00:00",
"effectiveTo": null,
"isEmployerContributionOverride": true,
"employerContributionAmount": { "flatAmount": null, "percentage": 3.0 }
}
}
]
}Filter by employee-ids, company-deduction-ids, status (Active or InActive), and an effective-from/effective-to range (max 365 days, required if you're filtering by organization-id or company-ids alone rather than by employee).
effectiveFrom/effectiveTo come back as full ISO date-times ("2024-01-01T00:00:00"), not date-only strings, even though a date-only value is accepted on write.
401k specifically: retirement deductions have their own family of categories on GET /company-deductions, standard 401k, catch-up, Roth 401k, Roth catch-up, and multiple concurrent 401k loans, plus equivalent categories for 403b and 457b. A 401k contribution is typically a recurring percentage deduction, with an employer match set separately via employerContributionAmount when one applies. See Payroll Reference Data for the full category list.
Create or update a scheduled deduction
PUT https://external-app-prod.netchexonline.net/employee-scheduled-deductions?api-version=3.0
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json{
"deductions": [
{
"employeeId": 5001,
"companyDeductionId": 10,
"voluntaryDeduction": {
"employeeContributionAmount": { "percentage": 6.0 },
"frequency": "Recurring",
"effectiveFrom": "2024-01-01",
"isEmployerContributionOverride": true,
"employerContributionAmount": { "percentage": 3.0 }
}
}
]
}If the employee already has a deduction of that type, it's updated. Otherwise a new one is created. Currently supports Voluntary deductions only. Up to 500 deductions per request, and like pending earnings/deductions above, this is whole-batch: all changes in the request succeed or fail together.
Remove a scheduled deduction
DELETE https://external-app-prod.netchexonline.net/employee-scheduled-deductions?api-version=3.0
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json{ "employeeDeductionIds": [90001] }This takes employeeDeductionId values, the IDs returned by the list endpoint above, not employee IDs or deduction type IDs.
Try it in the playground
Test these endpoints interactively in the API reference: