Payroll Reference Data

This guide covers fetching earnings codes, deduction types, and tax codes — the reference data needed to decode paycheck line items or configure time-and-attendance rules in your integration.

Overview

Three v3 endpoints expose payroll reference data:

GET /company-earnings — earnings types configured per company
GET /company-deductions — deduction types (categorized: benefit, tax, garnishment, etc.)
GET /company-tax-codes — tax codes, optionally including federal codes

Step 1 — Fetch earnings codes

Request

GET https://external-api.netchexonline.net/company-earnings?company-ids=101&api-version=3.0
Authorization: ApiKey YOUR_API_KEY

Key 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

Response (200)

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalItemsCount": 8,
  "items": [
    { "id": 1, "code": "REG", "description": "Regular Pay",   "companyId": 101 },
    { "id": 2, "code": "OT",  "description": "Overtime Pay",  "companyId": 101 },
    { "id": 3, "code": "BON", "description": "Annual Bonus",  "companyId": 101 }
  ]
}

Step 2 — Fetch deduction types

The category parameter filters to a specific type of deduction:

Request

GET https://external-api.netchexonline.net/company-deductions?company-ids=101&category=benefit&api-version=3.0
Authorization: ApiKey YOUR_API_KEY

Key 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

Valid category values include: benefit, garnishment, tax, loan, retirement, other. Omit the parameter to return all deduction types for the given companies.

Response (200)

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalItemsCount": 4,
  "items": [
    { "id": 10, "code": "MED", "description": "Medical Insurance", "category": "benefit", "companyId": 101 },
    { "id": 11, "code": "DEN", "description": "Dental Insurance",  "category": "benefit", "companyId": 101 }
  ]
}

Step 3 — Fetch tax codes

Request

GET https://external-api.netchexonline.net/company-tax-codes?company-ids=101&include-federal=true&api-version=3.0
Authorization: ApiKey YOUR_API_KEY

Key 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

Response (200)

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalItemsCount": 6,
  "items": [
    { "id": 20, "code": "FIT",  "description": "Federal Income Tax",  "isFederal": true },
    { "id": 21, "code": "FICA", "description": "Social Security",     "isFederal": true },
    { "id": 22, "code": "LA",   "description": "Louisiana State Tax", "isFederal": false, "companyId": 101 }
  ]
}

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:

Payroll Reference Data

Overview

Step 1 — Fetch earnings codes

Step 2 — Fetch deduction types

Step 3 — Fetch tax codes

Seed your reference tables

Try it in the playground

On this page