Deliver Payslips Directly to Employee HRIS Profiles

Implementation: Upload Payslips to HRIS Profiles

Step 1: Generate Payslip PDF After Payroll Processing

Once payroll calculations are finalized and approved, generate PDF payslips for each employee containing compensation details, deductions, tax withholdings, and net pay. These PDFs become the source documents that will be uploaded to employees' HRIS profiles.

// Example: Generate payslip PDF after payroll run
const payrollRun = await payrollSystem.completePayrollRun({
  payPeriod: '2025-01-31',
  status: 'finalized'
});

// Generate payslip PDFs for all employees
const payslips = await Promise.all(
  payrollRun.employees.map(async (employee) => {
    const payslipPDF = await payrollSystem.generatePayslip({
      employeeId: employee.id,
      payPeriod: '2025-01-31',
      format: 'pdf',
      includeYTD: true // Year-to-date totals
    });

    return {
      employeeId: employee.id,
      fileName: `Payslip_${employee.lastName}_${employee.firstName}_Jan2025.pdf`,
      pdfContent: payslipPDF.buffer,
      issueDate: '2025-01-31'
    };
  })
);

Step 2: Prepare Document with Proper Naming and Metadata

Different HRIS platforms require specific document categorization, naming conventions, and metadata. Prepare your payslip documents with appropriate categories and ensure file names are descriptive and follow consistent patterns that help employees locate documents later.

// Example: Prepare document metadata for HRIS upload
const prepareDocumentMetadata = (payslip, hrisConfig) => {
  // Base64 encode the PDF content for API transmission
  const base64Content = payslip.pdfContent.toString('base64');

  return {
    employeeId: payslip.employeeId,
    fileName: payslip.fileName,
    fileContent: base64Content,
    issueDate: payslip.issueDate,
    description: 'Monthly Payslip - January 2025',

    // Category mapping based on HRIS platform
    category: getCategoryForPlatform(hrisConfig.platform, 'payslip'),

    // Platform-specific metadata
    documentType: hrisConfig.platform === 'darwinbox'
      ? { type: 'Payslip', section_attribute: 'compensation_docs' }
      : undefined
  };
};

// Platform-specific category handling
const getCategoryForPlatform = (platform, docType) => {
  const categoryMap = {
    'hibob': 'Compensation', // Hibob's Shared folder structure
    'zoho_people': 'Payroll Documents', // Required for Zoho
    'oracle_hcm': 'Compensation', // Required for Oracle
    'bamboohr': 'Payroll', // Fetch via Get Document Categories API
    'darwinbox': 'Payslips' // Required with documentType
  };

  return categoryMap[platform] || 'Compensation';
};

Step 3: Upload to Employee's HRIS Profile via Document Upload API

Use Knit's document upload API to deliver payslips to the correct employee profile in their connected HRIS. Knit handles platform-specific authentication, document categorization requirements, and format transformations automatically.

API Endpoint: POST https://api.getknit.dev/v1.0/hr.employees.document.upload

// Example: Upload payslip to HRIS using Knit API
const uploadPayslipToHRIS = async (payslipMetadata, knitConfig) => {
  const formData = new FormData();

  // Add required fields
  formData.append('employee_id', payslipMetadata.employeeId);
  formData.append('file', Buffer.from(payslipMetadata.fileContent, 'base64'), {
    filename: payslipMetadata.fileName,
    contentType: 'application/pdf'
  });

  // Add optional fields based on platform requirements
  if (payslipMetadata.category) {
    formData.append('category', payslipMetadata.category);
  }

  if (payslipMetadata.documentType) {
    formData.append('documentType', JSON.stringify(payslipMetadata.documentType));
  }

  const response = await fetch('https://api.getknit.dev/v1.0/hr.employees.document.upload', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${knitConfig.apiKey}`,
      'X-Knit-Integration-Id': knitConfig.integrationId
    },
    body: formData
  });

  const result = await response.json();

  if (response.ok) {
    console.log(`Payslip uploaded successfully for employee ${payslipMetadata.employeeId}`);
    return result;
  } else {
    throw new Error(`Upload failed: ${result.error}`);
  }
};

// Batch upload payslips for all employees
const uploadResults = await Promise.all(
  payslips.map(payslip => {
    const metadata = prepareDocumentMetadata(payslip, hrisConfig);
    return uploadPayslipToHRIS(metadata, knitConfig);
  })
);

console.log(`Successfully uploaded ${uploadResults.length} payslips to HRIS`);

Platform-Specific Considerations:

• Hibob: The category parameter determines upload location (defaults to Shared folder if omitted)
• Darwinbox: Both category and documentType are mandatory—documentType includes the document type name and section_attribute value provided by Darwinbox integrations team
• Zoho People & Oracle Cloud HCM: The category field is required for document organization
• BambooHR: Retrieve available categories using the Get Document Categories endpoint before uploading
• File Format: All platforms support PDF format; some also support images (PNG, JPG) and documents (DOCX)
• File Size: Most platforms support files up to 10MB; check platform-specific limits for large documents

Key APIs and Data Models

API/Endpoint	Description	Key Fields
POST /hr.employees.document.upload	Uploads document to employee's HRIS profile	employee_id, file, category, documentType, description, issueDate
GET /hr.employees.documents.categories	Retrieves available document categories for HRIS	categoryId, categoryName, categoryType
GET /hr.employees.documents	Lists documents for an employee	employeeId, documentId, fileName, uploadDate, category
DELETE /hr.employees.document	Removes document from employee profile	employeeId, documentId
GET /hr.employees	Retrieves employee data for ID mapping	employeeId, email, firstName, lastName, employeeNumber

Supported HRIS Platforms:
Workday, Hibob, Sage, BambooHR, Personio, Darwinbox, Zoho People, SAP SuccessFactors, Oracle Cloud HCM, Keka HR, People HR, Avionte, ADP Workforce Now, UKG Pro, Ceridian Dayforce, Paycor, Gusto, Rippling, Namely, 15Five, and more.

Data Model Notes:

• Employee IDs must match between payroll and HRIS systems—use Knit's employee sync to maintain consistent identifiers
• File content requires base64 encoding for API transmission
• Document categories vary by HRIS platform—always check available categories for proper organization
• Issue date helps maintain chronological document ordering in employee profiles
• Supported file types: PDF (recommended for payslips), PNG, JPG, DOCX, XLSX
• Maximum file size varies by platform (typically 5-10MB)

Wrapping Up: Seamless Payslip Delivery and Centralized Document Management

Payslip distribution shouldn't require employees to juggle multiple logins or IT teams to manage separate payroll portals. With Knit's document upload automation, payslips flow seamlessly from your payroll platform into employees' HRIS profiles—appearing exactly where employees expect to find employment documents. This creates a unified employee experience, reduces support overhead, and ensures HR teams maintain complete document archives without manual file management.

Key capabilities unlocked:

• One integration, 30+ HRIS platforms: Build payslip delivery once, support every major HRIS your customers use
• Automatic platform adaptation: Knit handles Darwinbox's mandatory metadata, BambooHR's category structure, and other platform-specific requirements
• Centralized document management: Payslips archive in employee HRIS profiles alongside other employment documents
• Reduced employee friction: Single-portal access eliminates password fatigue and login confusion
• Compliance-ready audit trails: HRIS maintains complete records of document delivery and access history