Payroll Reference Data
Retrieve earnings codes, deduction types, and tax codes configured in Netchex.
This guide covers fetching earnings codes, deduction types, and tax codes, the reference data needed to decode paycheck line items or submit payroll data through other endpoints. See the Glossary for what a company earning/deduction is.
Overview
Three v3 endpoints expose payroll reference data:
GET /company-earnings: earnings types configured per companyGET /company-deductions: deduction types, with a real category per type (retirement, insurance, garnishment, and more, see below)GET /company-tax-codes: tax codes configured per company
Step 1: Fetch earnings codes
GET https://external-api.netchexonline.net/company-earnings?company-ids=101&api-version=3.0
Authorization: ApiKey YOUR_API_KEYKey parameters:
| Parameter | Type | Description |
|---|---|---|
company-ids | integer[] | Filter to one or more companies |
organization-id | GUID | Filter by organization |
page-number / page-size | integer | Pagination |
{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 3,
"items": [
{ "id": 1, "code": "REG", "name": "Regular Pay", "calculationMethod": "UnitRate", "companyId": 101 },
{ "id": 2, "code": "OT", "name": "Overtime Pay", "calculationMethod": "UnitRate2", "companyId": 101 },
{ "id": 3, "code": "BON", "name": "Annual Bonus", "calculationMethod": "FlatAmount", "companyId": 101 }
]
}The label field is name.
calculationMethod describes how Netchex computes this earning internally (FlatAmount, PieceRate, a numbered series of UnitRate variants). It's informational, read-only. When submitting an earning, you just reference the earning's id.
Step 2: Fetch deduction types
GET https://external-api.netchexonline.net/company-deductions?company-ids=101&category=Retirement401k&api-version=3.0
Authorization: ApiKey YOUR_API_KEYKey parameters:
| Parameter | Type | Description |
|---|---|---|
company-ids | integer[] | Filter to one or more companies |
organization-id | GUID | Filter by organization |
category | string | Deduction category filter, see values below |
page-number / page-size | integer | Pagination |
Deduction categories are specific values. A representative sample:
- Retirement:
Retirement401k,Retirement401kCatchUp,Retirement401kRoth,Retirement401kRothCatchUp,Retirement401kLoanthroughRetirement401kLoan4,Retirement403b,Retirement457b, and more - Section 125 benefits:
Section125Health,Section125Dental,Section125EyeCare,Section125Dependent,Section125HSACard, and more - Other insurance:
HealthInsurance,HealthInsuranceFSA,HealthInsuranceHRA,DentalInsurance,LifeInsurance, and more - Withholding style:
GarnishmentthroughGarnishment5,ChildSupport,Levy,UnionDues,Charity
Omit category to return all deduction types for the given companies, and read the category back on each item rather than hardcoding the full list, it's long and specific enough that pulling it live is more reliable than a hardcoded reference.
{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 2,
"items": [
{ "id": 10, "code": "401K", "name": "401k Contribution", "calculationMethod": "Percent401k", "category": "Retirement401k", "companyId": 101 },
{ "id": 11, "code": "401KM", "name": "401k Roth Contribution", "calculationMethod": "Percent401k", "category": "Retirement401kRoth", "companyId": 101 }
]
}The label field is name.
Step 3: Fetch tax codes
GET https://external-api.netchexonline.net/company-tax-codes?company-ids=101&include-federal=true&api-version=3.0
Authorization: ApiKey YOUR_API_KEYKey parameters:
| Parameter | Type | Description |
|---|---|---|
company-ids | integer[] | Filter to one or more companies |
organization-id | GUID | Filter by organization |
include-federal | boolean | Include federal tax codes in results |
page-number / page-size | integer | Pagination |
{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 2,
"items": [
{
"companyId": 101,
"companyCode": "ACME",
"taxCodeId": 20,
"taxCode": "FIT",
"taxTableCode": "FED2024",
"taxDescription": "Federal Income Tax",
"taxType": "Federal",
"payeeCode": "IRS",
"symmetry": null,
"w2Id": "1",
"sutaTaxRateAmount": 0
}
]
}This response is a fuller shape than earnings or deductions. Whether a code is federal is reflected in fields like taxType. include-federal controls whether federal codes are included in results at all.
Seed your reference tables
const BASE_URL = 'https://external-api.netchexonline.net';
const API_KEY = process.env.API_KEY;
async function fetchJson(path) {
const res = await fetch(`${BASE_URL}${path}`, {
headers: { Authorization: `ApiKey ${API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${path}`);
return res.json();
}
async function loadReferenceData(companyId) {
const params = `company-ids=${companyId}&api-version=3.0`;
const [earnings, deductions, taxes] = await Promise.all([
fetchJson(`/company-earnings?${params}`),
fetchJson(`/company-deductions?${params}`),
fetchJson(`/company-tax-codes?${params}&include-federal=true`),
]);
return {
earnings: earnings.items,
deductions: deductions.items,
taxes: taxes.items,
};
}
loadReferenceData(101)
.then((data) => console.log(JSON.stringify(data, null, 2)))
.catch(console.error);import os, requests
BASE_URL = "https://external-api.netchexonline.net"
HEADERS = {"Authorization": f"ApiKey {os.environ['API_KEY']}"}
def fetch(path, params=None):
resp = requests.get(f"{BASE_URL}{path}", params=params, headers=HEADERS)
resp.raise_for_status()
return resp.json()
def load_reference_data(company_id):
base_params = {"company-ids": company_id, "api-version": "3.0"}
return {
"earnings": fetch("/company-earnings", base_params)["items"],
"deductions": fetch("/company-deductions", base_params)["items"],
"taxes": fetch("/company-tax-codes", {**base_params, "include-federal": "true"})["items"],
}
if __name__ == "__main__":
import json
print(json.dumps(load_reference_data(101), indent=2))Reference data changes infrequently. Cache these results locally and refresh once per sync cycle rather than fetching on every payroll export run.
Try it in the playground
Test these endpoints interactively in the API reference: