Glossary

The API uses a specific vocabulary for HR, time, and payroll concepts. This page defines the terms as they're used across these docs, independent of any single endpoint.

Organization hierarchy

• Organization: the top level of the hierarchy, identified by a GUID. An organization contains one or more companies.
• Company: a legal or operational entity within an organization, identified by an integer ID. Most filtering across the API happens at the company level, your API key is scoped to specific companies.
• Division and Business Unit: optional groupings between company and department, used by larger or multi-brand companies to organize departments further.
• Department: where an employee's time and earnings are recorded against. An employee can be restricted to specific departments or allowed to work across all of them.
• Location: a physical work location, separate from the department hierarchy. An employee can be assigned to a location or marked as working from home.

Employee identity

• Employee ID: Netchex's internal numeric identifier for an employee.
• Employee code: a code your system or Netchex's configuration assigns to the employee, used as an alternative to the internal ID on some submission endpoints (particularly time punches and timecard earnings). Not every endpoint accepts both, check which one a given endpoint expects.
• Connected employee / Universal ID: employees who are the same physical person across multiple companies are linked by a shared identifier, so you can resolve "this person in Company A" and "this person in Company B" as one individual.

Time & Attendance

• Time punch: a single clock event, one timestamp and one type (In, Out, InLunch, OutLunch, InBreak, OutBreak, and paid/unpaid variants of break). A shift is represented as multiple punches, not one record with both an in and out time on it.
• Direct-entry earning: an earning tied to a specific date and department but not to a punch, hours, tips, mileage, or a bonus entered directly rather than calculated from clock events.
• Department transfer: when set up for a company, lets an employee working across multiple departments be paid at each department's own rate instead of one fixed rate. See Time & Attendance for how this shows up on an earning.
• Data source: where a punch or earning originated (e.g. a specific time clock integration, a manual entry). Useful for filtering and for tracing a record back to its source.

Payroll

• Company earning / Company deduction: the earning and deduction types configured for a company, for example "Regular Pay" or "401k Contribution". These have their own IDs (companyEarningId, companyDeductionId) that you look up once and reference on every submission, you don't invent your own codes.
• Pending paycheck earning/deduction: a one-time amount queued for an employee's current or upcoming paycheck. Submitted with an explicit amount, either a flat dollar figure, units at the earning's rate, or units at a custom rate.
• Scheduled deduction: a recurring (or defined-schedule) deduction that persists across paychecks until changed or stopped, this is how retirement contributions like 401k and ongoing insurance premiums are represented, as opposed to a one-time pending deduction.
• Payroll run: one execution of payroll for a company, identified by a payrollNumber, covering potentially many employees and paychecks.
• Paycheck: a single employee's pay for one payroll run. One payroll run produces many paychecks.
• GL journal entry: a single debit or credit line produced by a payroll run, categorized (earnings, taxes, deductions, workers' compensation) and mapped to an account, for posting into an accounting system.

Requests & responses

• Problem Details: the RFC 9457 error response format used across the API (type, title, status, detail, sometimes instance or a field-level errors map).
• Scoped access: your API key is authorized for specific companies. How an inaccessible ID is handled depends on the shape of the request: a collection filter (e.g. company-ids=101,102 where you only have access to 101) typically drops the inaccessible ones silently rather than erroring; a single-resource lookup by ID (e.g. GET /api/Employees/{id}, or a connected-employee lookup by ID) instead returns 404, same as if the ID didn't exist at all. Check the specific endpoint's own docs for which applies — see Error Handling for when this can also come back as 403.
• External unique ID: an ID you supply on write requests so you can correlate a submitted record with your own system's records, and so retries don't create duplicates.

Webhooks

• Event Grid: the Azure service Netchex uses to deliver webhook events. Its subscription validation handshake and retry behavior are Azure infrastructure, not custom Netchex code.
• Topic / Subject: identifiers on a webhook event, topic identifies your integration's event stream, subject identifies the specific resource the event is about.