Senior n8n Developer for Paychex Payroll API Automation

Project Overview We are an automation consultancy looking for an experienced n8n/API developer to help implement a controlled payroll-entry workflow for a multi-location healthcare organization with approximately 150 employees. The system will compile payroll inputs into a Google Sheets review table and write human-approved earnings into unprocessed Paychex checks through the official Paychex API. This is not a tax-calculation or payroll-processing system. A payroll administrator will review all information and remain responsible for final payroll submission. We have completed process discovery and will provide the workflow design, business rules, sample data, and existing infrastructure. Existing Environment - Self-hosted n8n - Existing Open Dental API connection - Google Sheets and Gmail - Existing monthly doctor-payroll automation - Client-owned Paychex Flex account - Existing hosting and deployment environment The client will create a private Paychex API application. The freelancer will not need to apply to become a Paychex partner. What You Will Build The workflow will support: - Regular employee hours - Overtime hours - PTO/vacation hours - Bonus and approved dollar adjustments - Approved doctor-payroll amounts from an existing workflow - Manual payroll-administrator corrections The workflow must: 1. Normalize the payroll inputs into one row per employee. 2. Match employees to Paychex workers using stable identifiers. 3. Flag missing mappings, invalid values, and incomplete records. 4. Create a Google Sheets review table. 5. Pause for human review and approval. 6. Read approved corrections from the review table. 7. Retrieve the appropriate open Paychex pay period and earning components. 8. Write approved hours and dollar earnings into unprocessed Paychex checks. 9. Read the resulting checks to verify the entries. 10. Log successes, failures, API responses, and verification results. The automation must never submit or finalize payroll. Required Run Modes Employee-Only Run Processes the approved payroll inputs for hourly employees, salaried employees with adjustments, W2 employees, and applicable contractors. Employees Plus Doctors Run Processes the employee payroll inputs plus approved monthly doctor-payroll amounts from an existing Google Sheets workflow. The payroll administrator must select the appropriate run mode manually because the doctor-payroll date can change. Paychex API Requirements The workflow must use the official Paychex API to: - Authenticate using client credentials - Retrieve companies and workers - Retrieve open pay periods - Retrieve earning and pay components - Retrieve existing checks - Add hour-based and dollar-based earnings - Verify the resulting entries - Capture and clearly display API errors Critical Safeguards Because this workflow writes payroll data, it must include: - Idempotency and duplicate prevention - Unique correlation IDs - Persistent payroll-run status - Pre-write validation - Checks for existing entries - Controlled retry behavior - Post-write verification - Clear exception reporting - Audit logging - Protection against overwriting manual corrections - No silent failures - No automatic payroll submission A workflow retry must never add the same earnings twice. Deliverables - Working n8n payroll workflow - Paychex authentication and data-retrieval workflows - Employee-mapping process - Google Sheets review and approval process - Both required payroll run modes - Approved Paychex check-entry process - Duplicate prevention and error handling - Post-write verification and run logging - Exported n8n workflow files - Supporting JavaScript or Node.js source code - Setup and configuration documentation - Short handoff walkthrough All workflows and source code must be stored in our environment or repository. Final delivery cannot exist only in the freelancer’s local environment. Out of Scope - Payroll-tax calculations - Direct deposits - Final payroll submission - Employee onboarding or offboarding - Benefits or 401(k) administration - QuickBooks integration - Automatically correcting time-clock errors - Browser or screen automation - Patient or clinical-data processing - Rebuilding the existing doctor-payroll calculation workflow - Unlimited compensation rules or input formats Security Requirements The selected freelancer must: - Sign an NDA and confidentiality agreement - Begin with synthetic or sanitized data - Follow least-privilege access practices - Store credentials using n8n credentials or approved environment variables - Never place credentials in code, messages, screenshots, logs, or documentation - Avoid accessing patient or clinical information - Disclose any subcontractors - Transfer all work product and source code upon payment Production access will only be provided after the initial API proof is approved. Required Experience - Production n8n workflows - REST API integrations - JavaScript or Node.js - OAuth 2.0/client-credentials authentication - API pagination and data transformation - Idempotency and duplicate prevention - Retry and error-handling design - Google Sheets integration - Secure credential management - Financial, payroll, accounting, payment, or similarly sensitive systems Direct Paychex API experience is helpful but not required. Strong experience with another payroll, payment, banking, or financial API is acceptable. Budget and Timeline - Fixed-price budget: $1,250 - Target timeline: 2–4 weeks - Potential additional work after successful completion Begin your proposal with PAYROLL SAFE and explain specifically how you would prevent a workflow retry from creating duplicate payroll entries.