Get Timesheet and Attendance Data from HRIS

Implementation: Sync Time, Attendance, and Compensation Data

Step 1: Sync Timesheet and Attendance Data for Pay Period

When initiating a payroll run, first sync time and attendance data for the specific pay period from connected HRIS and time-tracking systems. This provides the foundation for calculating hours worked, overtime, and leave deductions.

Timesheet API Endpoint: GET https://api.getknit.dev/v1.0/hr.employees.timesheets

Attendance API Endpoint: GET https://api.getknit.dev/v1.0/hr.employees.attendance

// Example: Fetch timesheet data for pay period
const fetchTimesheetData = async (payPeriod, knitConfig) => {
  const response = await fetch(
    `https://api.getknit.dev/v1.0/hr.employees.timesheets?` +
    `startDate=${payPeriod.startDate}&` +
    `endDate=${payPeriod.endDate}`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${knitConfig.apiKey}`,
        'X-Knit-Integration-Id': knitConfig.integrationId
      }
    }
  );

  const timesheetData = await response.json();

  // Returns structured timesheet entries with:
  // - employeeId: Employee identifier
  // - timeLogId: Unique timesheet entry ID
  // - date: Work date
  // - startTime: Shift start time
  // - endTime: Shift end time
  // - totalHours: Hours worked for this entry
  // - projectId: Project allocation (if applicable)
  // - entryType: REGULAR, OVERTIME, DOUBLE_TIME
  // - status: APPROVED, PENDING, REJECTED

  return timesheetData.timesheets;
};

// Example: Fetch attendance data for pay period
const fetchAttendanceData = async (payPeriod, knitConfig) => {
  const response = await fetch(
    `https://api.getknit.dev/v1.0/hr.employees.attendance?` +
    `startDate=${payPeriod.startDate}&` +
    `endDate=${payPeriod.endDate}`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${knitConfig.apiKey}`,
        'X-Knit-Integration-Id': knitConfig.integrationId
      }
    }
  );

  const attendanceData = await response.json();

  // Returns attendance records with:
  // - employeeId: Employee identifier
  // - date: Attendance date
  // - status: PRESENT, ABSENT, HALF_DAY, LEAVE
  // - clockIn: Clock-in timestamp
  // - clockOut: Clock-out timestamp
  // - leaveType: SICK, VACATION, UNPAID, etc.
  // - hoursWorked: Calculated hours from clock times

  return attendanceData.attendance;
};

// Sync both data sources for payroll period
const payPeriod = {
  startDate: '2025-01-01',
  endDate: '2025-01-15'
};

const [timesheets, attendance] = await Promise.all([
  fetchTimesheetData(payPeriod, knitConfig),
  fetchAttendanceData(payPeriod, knitConfig)
]);

console.log(`Synced ${timesheets.length} timesheet entries and ${attendance.length} attendance records`);

Step 2: Retrieve Employee Compensation Structures

Compensation calculation requires understanding each employee's pay structure—base salary, hourly rates, overtime multipliers, deductions, allowances, and benefits. Sync employee compensation data from the HRIS to ensure payroll calculations use current, accurate compensation details.

// Example: Fetch employee compensation data
const fetchEmployeeCompensation = async (employeeIds, knitConfig) => {
  const employees = await Promise.all(
    employeeIds.map(async (employeeId) => {
      const response = await fetch(
        `https://api.getknit.dev/v1.0/hr.employees/${employeeId}`,
        {
          method: 'GET',
          headers: {
            'Authorization': `Bearer ${knitConfig.apiKey}`,
            'X-Knit-Integration-Id': knitConfig.integrationId
          }
        }
      );

      const employeeData = await response.json();

      return {
        employeeId: employeeData.employeeId,
        compensation: employeeData.compensation,
        // Compensation structure includes:
        // - fixed: Array of salary/allowance items
        // - variable: Array of bonuses/commissions
        // - stock: Array of equity compensation
        deductions: employeeData.deductions,
        taxInfo: employeeData.taxInfo
      };
    })
  );

  return employees;
};

// Example: Parse compensation structure for payroll calculation
const parseCompensationStructure = (employee) => {
  const compensation = employee.compensation;

  // Extract base salary or hourly rate
  const basePay = compensation.fixed.find(item =>
    item.type === 'SALARY' || item.type === 'HOURLY'
  );

  // Calculate pay rate based on pay period
  const payRate = basePay.payPeriod === 'HOURLY'
    ? basePay.amount // Hourly rate
    : basePay.payPeriod === 'ANNUAL'
    ? basePay.amount / 26 // Bi-weekly from annual
    : basePay.amount; // Direct period amount

  // Extract allowances (housing, transportation, etc.)
  const allowances = compensation.fixed.filter(item =>
    item.type === 'ALLOWANCE'
  );

  // Extract deductions (health insurance, retirement, etc.)
  const deductions = employee.deductions || [];

  return {
    employeeId: employee.employeeId,
    basePayRate: payRate,
    payPeriod: basePay.payPeriod,
    currency: basePay.currency,
    allowances: allowances,
    deductions: deductions,
    overtimeMultiplier: 1.5 // Default, may vary by jurisdiction
  };
};

// Get unique employee IDs from timesheet and attendance data
const uniqueEmployeeIds = [
  ...new Set([
    ...timesheets.map(t => t.employeeId),
    ...attendance.map(a => a.employeeId)
  ])
];

const compensationData = await fetchEmployeeCompensation(uniqueEmployeeIds, knitConfig);
const compensationStructures = compensationData.map(parseCompensationStructure);

Step 3: Calculate Gross Pay, Deductions, and Net Pay Using Collected Data

With timesheet hours, attendance records, and compensation structures synced, calculate each employee's gross pay by applying pay rates to hours worked, adding allowances, calculating overtime premiums, and subtracting deductions for leave taken.

// Example: Calculate payroll using synced data
const calculatePayroll = (timesheets, attendance, compensationStructures) => {
  return compensationStructures.map(empComp => {
    // Get employee's timesheets for pay period
    const empTimesheets = timesheets.filter(t =>
      t.employeeId === empComp.employeeId && t.status === 'APPROVED'
    );

    // Get employee's attendance records
    const empAttendance = attendance.filter(a =>
      a.employeeId === empComp.employeeId
    );

    // Calculate regular and overtime hours
    const regularHours = empTimesheets
      .filter(t => t.entryType === 'REGULAR')
      .reduce((sum, t) => sum + t.totalHours, 0);

    const overtimeHours = empTimesheets
      .filter(t => t.entryType === 'OVERTIME')
      .reduce((sum, t) => sum + t.totalHours, 0);

    // Calculate leave deductions
    const unpaidLeaveDays = empAttendance.filter(a =>
      a.status === 'ABSENT' || (a.leaveType && a.leaveType === 'UNPAID')
    ).length;

    // For hourly employees: Calculate gross pay from hours
    let grossPay = 0;
    if (empComp.payPeriod === 'HOURLY') {
      grossPay = (regularHours * empComp.basePayRate) +
                 (overtimeHours * empComp.basePayRate * empComp.overtimeMultiplier);
    } else {
      // For salaried employees: Use period salary minus leave deductions
      grossPay = empComp.basePayRate;

      // Deduct unpaid leave (assuming 10 working days per pay period)
      const dailyRate = empComp.basePayRate / 10;
      grossPay -= (unpaidLeaveDays * dailyRate);
    }

    // Add allowances
    const totalAllowances = empComp.allowances.reduce((sum, allowance) =>
      sum + (allowance.amount || 0), 0
    );
    grossPay += totalAllowances;

    // Calculate total deductions
    const totalDeductions = empComp.deductions.reduce((sum, deduction) => {
      // Deductions can be fixed amounts or percentages
      const deductionAmount = deduction.amount ||
        (grossPay * (deduction.percentage / 100));
      return sum + deductionAmount;
    }, 0);

    // Calculate net pay
    const netPay = grossPay - totalDeductions;

    return {
      employeeId: empComp.employeeId,
      payPeriod: {
        start: '2025-01-01',
        end: '2025-01-15'
      },
      hours: {
        regular: regularHours,
        overtime: overtimeHours
      },
      compensation: {
        basePay: empComp.payPeriod === 'HOURLY'
          ? regularHours * empComp.basePayRate
          : empComp.basePayRate,
        overtimePay: overtimeHours * empComp.basePayRate * empComp.overtimeMultiplier,
        allowances: totalAllowances,
        grossPay: grossPay
      },
      deductions: {
        items: empComp.deductions,
        total: totalDeductions,
        unpaidLeave: unpaidLeaveDays
      },
      netPay: netPay,
      currency: empComp.currency
    };
  });
};

// Execute payroll calculation
const payrollResults = calculatePayroll(
  timesheets,
  attendance,
  compensationStructures
);

console.log('Payroll calculation complete:', payrollResults);

Data Integration Best Practices:

• Timesheet Approval Status: Only include approved timesheets in payroll calculations—pending or rejected entries should not affect compensation
• Attendance vs. Timesheet Reconciliation: Some systems provide both attendance and timesheet data—use timesheet hours as authoritative for hourly calculations, attendance for leave tracking
• Multi-Platform Time Tracking: Employees may track time in specialized tools (Toggl, Clockify) while attendance is recorded in HRIS—sync both sources and reconcile based on your payroll policies
• Project Allocation: Capture projectId and taskId from timesheets for cost accounting and client billing alongside payroll calculation
• Pay Period Boundaries: Ensure date range queries align with your pay period calendar—some systems use inclusive end dates, others exclusive
• Currency Consistency: Verify all compensation amounts use the same currency or implement exchange rate conversion for international employees

Key APIs and Data Models

Timesheet API

API/Endpoint	Description	Key Fields
GET /hr.employees.timesheets	Retrieves timesheet entries for pay period	employeeId, timeLogId, date, startTime, endTime, totalHours, projectId, taskId, entryType, status

Query Parameters:

• startDate & endDate: Date range for timesheet entries (required)
• month: Alternative to date range (format: YYYY-MM)
• employeeId: Filter to specific employee
• originData: Include raw platform data

Supported Platforms: Webwork, Timedoctor, Clockify, BambooHR, Toggl Track, Zoho People, TimeTac, Hubstaff, and more.

Entry Types:

• REGULAR: Standard working hours
• OVERTIME: Hours beyond standard workweek
• DOUBLE_TIME: Premium overtime hours
• PTO: Paid time off tracked as timesheet entry

Attendance API

API/Endpoint	Description	Key Fields
GET /hr.employees.attendance	Retrieves attendance records for pay period	employeeId, date, status, clockIn, clockOut, leaveType, hoursWorked

Query Parameters:

• startDate & endDate: Date range for attendance records (required)
• month: Alternative to date range (format: YYYY-MM)
• type: Filter by attendance type (e.g., TIMESHEETS)
• payPeriodId: Fetch Loss of Pay (LoP) data for specific pay period

Supported Platforms: Darwinbox, Keka HR, GreytHR, Zoho People, Paycor, Ceridian Dayforce, Employment Hero, Workline, Factorial, Personio, 7shifts, UKG Ready, Lucca HR, ZingHR, Hubstaff, Webwork, Toggl Track, and more.

Attendance Status Types:

• PRESENT: Employee attended work
• ABSENT: Employee did not attend
• HALF_DAY: Partial day attendance
• LEAVE: On approved leave (check leaveType for classification)

Leave Types: SICK, VACATION, UNPAID, PERSONAL, BEREAVEMENT

Employee Compensation Model

API/Endpoint	Description	Key Fields
GET /hr.employees/{id}	Retrieves employee data including compensation	employeeId, compensation.fixed, compensation.variable, compensation.stock, deductions, taxInfo

Compensation Structure:

Fixed Compensation (Array of compensation items):

• type: SALARY, ALLOWANCE, HOURLY, MERIT
• amount: Monetary value
• percentage: Percentage-based value
• currency: ISO currency code (USD, EUR, GBP, etc.)
• payPeriod: ANNUAL, MONTHLY, BI_WEEKLY, SEMI_MONTHLY, HOURLY, DAILY
• frequency: Payment frequency matching payPeriod
• startDate: Effective date
• endDate: Termination date (if applicable)

Variable Compensation (Array of compensation items): Same structure as fixed, typically used for BONUS, COMMISSION

Stock Compensation (Array of stock grants): planId, type, targetShares, optionsPercentage, vestingScheduleId

Deductions: Retrieved via employee data model or dedicated deductions endpoint—health insurance premiums, retirement contributions (401k, pension), tax withholdings, garnishments, other mandatory or voluntary deductions

Wrapping Up: Eliminate Manual Data Collection and Ensure Payroll Accuracy

Payroll calculation shouldn't require manual data collection across disconnected time-tracking, attendance, and HR systems. With Knit's unified time, attendance, and compensation APIs, all the data your payroll engine needs flows automatically from source systems—hours worked, leave taken, salary structures, deductions, and allowances arrive ready for calculation. This eliminates manual exports, reduces payroll processing time, and ensures employees are paid accurately based on real-time, authoritative data.

Key capabilities unlocked:

• One integration, 50+ data sources: Build payroll data sync once, support time-tracking tools, HRIS platforms, and attendance systems your customers already use
• Automatic data reconciliation: Knit standardizes timesheet and attendance data across platforms, eliminating format inconsistencies and field mapping complexity
• Real-time calculation accuracy: Payroll runs use current, approved data rather than stale exports or manually entered hours
• Project-level cost accounting: Capture time allocation for accurate labor cost distribution to projects, clients, and cost centers
• Compliance-ready audit trails: Permanent links between payroll calculations and source time/attendance data demonstrate wage-hour compliance