update_employee
Modify employee records in Paylocity by updating personal information, job details, compensation, employment status, and benefit setup with required effective dates.
Instructions
Update an employee's information. Supports changing: personal info (name, address), job details (title, department, cost center, supervisor), compensation (pay rate, salary), employment status (active, terminated, leave), and benefit setup. All changes require an effective date where applicable.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | No | Paylocity company ID (defaults to PAYLOCITY_COMPANY_ID env var) | |
| employeeId | Yes | Paylocity employee ID | |
| updates | Yes | Fields to update |
Implementation Reference
- src/server.ts:403-533 (handler)Implementation of the 'update_employee' MCP tool, handling input validation, payload construction, and API request.
server.tool( "update_employee", `Update an employee's information. Supports changing: personal info (name, address), job details (title, department, cost center, supervisor), compensation (pay rate, salary), employment status (active, terminated, leave), and benefit setup. All changes require an effective date where applicable.`, { companyId: companyIdParam, employeeId: z.string().describe("Paylocity employee ID"), updates: z .object({ // Personal firstName: z.string().optional(), lastName: z.string().optional(), address1: z.string().optional(), address2: z.string().optional(), city: z.string().optional(), state: z.string().optional(), zip: z.string().optional(), personalEmailAddress: z.string().optional(), homePhone: z.string().optional(), personalMobilePhone: z.string().optional(), // Status employeeStatus: z .enum(["A", "T", "L"]) .optional() .describe("A=Active, T=Terminated, L=Leave"), empStatusChangeReason: z.string().optional(), empStatusEffectiveDate: z .string() .optional() .describe("YYYY-MM-DD"), eligibleForRehire: z.boolean().optional(), // Department / Position departmentPosition: z .object({ jobTitle: z.string().optional(), costCenter1: z.string().optional(), costCenter2: z.string().optional(), costCenter3: z.string().optional(), employeeType: z.string().optional().describe("RFT, RPT, SNL, TFT, TPT"), supervisorCompanyNumber: z.string().optional(), supervisorEmployeeId: z.string().optional(), effectiveDate: z.string().optional().describe("YYYY-MM-DD"), changeReason: z.string().optional(), }) .optional(), // Pay rate primaryPayRate: z .object({ payType: z.string().optional().describe("Salary or Hourly"), salary: z.number().optional(), annualSalary: z.number().optional(), baseRate: z.number().optional(), defaultHours: z.number().optional(), payFrequency: z.string().optional().describe("S=Semi-monthly, B=Biweekly, W=Weekly, M=Monthly"), effectiveDate: z.string().optional().describe("YYYY-MM-DD"), reason: z.string().optional(), }) .optional(), // Benefit setup benefitSetup: z .object({ benefitClass: z.string().optional(), benefitClassEffectiveDate: z.string().optional(), benefitSalary: z.number().optional(), benefitSalaryEffectiveDate: z.string().optional(), }) .optional(), }) .describe("Fields to update"), }, async ({ companyId, employeeId, updates }) => { try { const cid = resolveCompanyId(companyId); // Build the updateEmployee payload — nest arrays where Paylocity expects them const payload: Record<string, any> = { companyNumber: cid, employeeId, }; // Flat personal/status fields const flatFields = [ "firstName", "lastName", "address1", "address2", "city", "state", "zip", "personalEmailAddress", "homePhone", "personalMobilePhone", "employeeStatus", "empStatusChangeReason", "empStatusEffectiveDate", "eligibleForRehire", ] as const; for (const f of flatFields) { if ((updates as any)[f] !== undefined) { payload[f] = (updates as any)[f]; } } // Nested array fields (Paylocity expects these as single-element arrays) if (updates.departmentPosition) { payload.departmentPosition = [updates.departmentPosition]; } if (updates.primaryPayRate) { payload.primaryPayRate = [updates.primaryPayRate]; } if (updates.benefitSetup) { payload.benefitSetup = [updates.benefitSetup]; } const result = await client.patch( `/v2/companies/${cid}/employees/${employeeId}`, { updateEmployee: payload } ); // Invalidate directory cache since employee data changed directoryCacheTime = 0; return ok({ success: true, result: redact(result) }); } catch (e) { return err(e); } } );