--- updatedAt: 2026-06-08T15:30:39.000Z agentTools: siteIndex: https://developer.paylocity.com/llms.txt projectIndex: https://developer.paylocity.com/integrations/llms.txt --- # Create Employee Deduction **Summary Description** This function will allow the API user to create a new deduction on the employee record. Garnishments cannot be created using the Deduction endpoints. # OpenAPI definition ```json { "openapi": "3.0.4", "info": { "title": "Pay Setup API", "version": "v1" }, "servers": [ { "url": "dc1demogwext.paylocity.com" } ], "paths": { "/apiHub/payroll/v1/companies/{companyId}/employees/{employeeId}/deductions": { "post": { "tags": [ "Recurring Deductions" ], "summary": "Create Employee Deduction", "description": "**Summary Description**\n\n This function will allow the API user to create a new deduction on the employee record. Garnishments cannot be created using the Deduction endpoints.", "x-explorer-enabled": false, "parameters": [ { "name": "companyId", "in": "path", "description": "The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity.\r\n **Allowable Values:**\r\n 9 char max", "required": true, "schema": { "type": "string" }, "example": "A12345" }, { "name": "employeeId", "in": "path", "description": "A filter to use to limit results to a specific employee.\r\n **Allowable Values:**\r\n 255 char max", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "A Payroll Deduction code is a unique identifier used by payroll systems to categorize and track specific deductions from an employee's paycheck. These deductions can include taxes, health insurance premiums, retirement contributions, loan repayments, and more. Each type of deduction has its own unique code that allows it to be easily identified and processed by the payroll system. This not only ensures accurate calculations and disbursements, but also helps with record-keeping and reporting requirements.", "content": { "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/CreateDeductionDto" }, "examples": { "Health Insurance Deduction": { "value": { "code": "HEALTH", "effectiveFrom": "2024-01-01T00:00:00", "effectiveTo": "2024-12-31T00:00:00", "rate": 250, "frequency": "PerPayPeriod", "note": "Employee health insurance premium", "selfInsured": true, "priority": 5 } }, "401k Contribution": { "value": { "code": "401K", "effectiveFrom": "2024-01-01T00:00:00", "calculationCode": "PERCENT", "rate": 500, "frequency": "PerPayPeriod", "note": "401(k) retirement contribution", "priority": 6 } }, "Child Support Deduction": { "value": { "code": "CHLDSUPP", "effectiveFrom": "2024-01-01T00:00:00", "rate": 350, "frequency": "PerPayPeriod", "agency": "AGENCY123", "miscellaneousInfo": "Court order #12345", "note": "Child support garnishment", "priority": 2 } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeductionDto" }, "examples": { "Health Insurance Deduction": { "value": { "code": "HEALTH", "effectiveFrom": "2024-01-01T00:00:00", "effectiveTo": "2024-12-31T00:00:00", "rate": 250, "frequency": "PerPayPeriod", "note": "Employee health insurance premium", "selfInsured": true, "priority": 5 } }, "401k Contribution": { "value": { "code": "401K", "effectiveFrom": "2024-01-01T00:00:00", "calculationCode": "PERCENT", "rate": 500, "frequency": "PerPayPeriod", "note": "401(k) retirement contribution", "priority": 6 } }, "Child Support Deduction": { "value": { "code": "CHLDSUPP", "effectiveFrom": "2024-01-01T00:00:00", "rate": 350, "frequency": "PerPayPeriod", "agency": "AGENCY123", "miscellaneousInfo": "Court order #12345", "note": "Child support garnishment", "priority": 2 } } } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateDeductionDto" }, "examples": { "Health Insurance Deduction": { "value": { "code": "HEALTH", "effectiveFrom": "2024-01-01T00:00:00", "effectiveTo": "2024-12-31T00:00:00", "rate": 250, "frequency": "PerPayPeriod", "note": "Employee health insurance premium", "selfInsured": true, "priority": 5 } }, "401k Contribution": { "value": { "code": "401K", "effectiveFrom": "2024-01-01T00:00:00", "calculationCode": "PERCENT", "rate": 500, "frequency": "PerPayPeriod", "note": "401(k) retirement contribution", "priority": 6 } }, "Child Support Deduction": { "value": { "code": "CHLDSUPP", "effectiveFrom": "2024-01-01T00:00:00", "rate": 350, "frequency": "PerPayPeriod", "agency": "AGENCY123", "miscellaneousInfo": "Court order #12345", "note": "Child support garnishment", "priority": 2 } } } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateDeductionDto" }, "examples": { "Health Insurance Deduction": { "value": { "code": "HEALTH", "effectiveFrom": "2024-01-01T00:00:00", "effectiveTo": "2024-12-31T00:00:00", "rate": 250, "frequency": "PerPayPeriod", "note": "Employee health insurance premium", "selfInsured": true, "priority": 5 } }, "401k Contribution": { "value": { "code": "401K", "effectiveFrom": "2024-01-01T00:00:00", "calculationCode": "PERCENT", "rate": 500, "frequency": "PerPayPeriod", "note": "401(k) retirement contribution", "priority": 6 } }, "Child Support Deduction": { "value": { "code": "CHLDSUPP", "effectiveFrom": "2024-01-01T00:00:00", "rate": 350, "frequency": "PerPayPeriod", "agency": "AGENCY123", "miscellaneousInfo": "Court order #12345", "note": "Child support garnishment", "priority": 2 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeductionDtoResponse" }, "examples": { "Health Insurance Deduction": { "value": { "id": "1f95299d-d10e-4a18-9162-d28c966b1a27", "code": "HEALTH", "effectiveFrom": "2024-01-01T00:00:00", "effectiveTo": "2024-12-31T00:00:00", "rate": 250, "frequency": "PerPayPeriod", "note": "Employee health insurance premium", "selfInsured": true, "priority": 5 } }, "401k Contribution": { "value": { "id": "50eb8d5d-10c6-4c9a-b1a0-10e9076d89be", "code": "401K", "effectiveFrom": "2024-01-01T00:00:00", "calculationCode": "PERCENT", "rate": 500, "frequency": "PerPayPeriod", "note": "401(k) retirement contribution", "priority": 6 } }, "Child Support Deduction": { "value": { "id": "f38fda23-6ae3-4522-8789-e4d699a56d89", "code": "CHLDSUPP", "effectiveFrom": "2024-01-01T00:00:00", "rate": 350, "frequency": "PerPayPeriod", "agency": "AGENCY123", "miscellaneousInfo": "Court order #12345", "note": "Child support garnishment", "priority": 2 } } } } } } } } } }, "components": { "schemas": { "CostCenterDto": { "type": "object", "properties": { "level": { "type": "integer", "description": "Cost center level (Levels are 1-3)", "format": "int32", "nullable": true }, "code": { "type": "string", "description": "Cost Center Code associated with the Level. This must match a Paylocity Cost Center Code", "nullable": true } }, "additionalProperties": { "type": "object", "nullable": true }, "description": "Cost Centers are organizational units within a company. Typically clients will break out their employees using cost centers like divisions, location and department." }, "CreateDeductionDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Deduction Code", "nullable": true }, "effectiveFrom": { "type": "string", "description": "Effective Date of the Deduction", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "description": "End Date of the Deduction", "format": "date-time", "nullable": true }, "calculationCode": { "type": "string", "description": "Calculation Code that Applies to Deduction", "nullable": true }, "rate": { "type": "number", "description": "Rate for the Deduction", "format": "double", "nullable": true }, "frequency": { "type": "string", "description": "Frequency determines how often the deduction Rate is applied in payroll", "nullable": true }, "agency": { "type": "string", "description": "Agency Code. These are custom per client", "nullable": true }, "arrear": { "type": "number", "description": "Money that is owed", "format": "double", "nullable": true }, "miscellaneousInfo": { "type": "string", "description": "Miscellaneous Information", "nullable": true }, "note": { "type": "string", "description": "Deduction Notes", "nullable": true }, "selfInsured": { "type": "boolean", "description": "Self-Insured Plan Flag. This will generate Part III of the employee's 1095-C Form", "nullable": true }, "priority": { "type": "integer", "description": "Priority determines the order in which a deduction is subtracted from gross pay. Priorities 1-4 are reserved for Statutory deductions(necessary by law), while 5-7 are reserved for Voluntary deductions(employee-elected).", "format": "int32", "nullable": true }, "loan401K": { "$ref": "#/components/schemas/Loan401KDto" }, "costCenters": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenterDto" }, "description": "An array of objects representing the Cost Centers", "nullable": true }, "limits": { "$ref": "#/components/schemas/CreateLimitsDto" } }, "additionalProperties": { "type": "object", "nullable": true }, "description": "A Payroll Deduction code is a unique identifier used by payroll systems to categorize and track specific deductions from an employee's paycheck.\r\nThese deductions can include taxes, health insurance premiums, retirement contributions, loan repayments, and more.\r\nEach type of deduction has its own unique code that allows it to be easily identified and processed by the payroll system.\r\nThis not only ensures accurate calculations and disbursements, but also helps with record-keeping and reporting requirements." }, "CreateDeductionDtoResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Resource ID of the record.", "format": "uuid" }, "code": { "type": "string", "description": "Deduction Code", "nullable": true }, "effectiveFrom": { "type": "string", "description": "Effective Date of the Deduction", "format": "date-time", "nullable": true }, "effectiveTo": { "type": "string", "description": "End Date of the Deduction", "format": "date-time", "nullable": true }, "calculationCode": { "type": "string", "description": "Calculation Code that Applies to Deduction", "nullable": true }, "rate": { "type": "number", "description": "Rate for the Deduction", "format": "double", "nullable": true }, "frequency": { "type": "string", "description": "Frequency determines how often the deduction Rate is applied in payroll", "nullable": true }, "agency": { "type": "string", "description": "Agency Code. These are custom per client", "nullable": true }, "arrear": { "type": "number", "description": "Money that is owed", "format": "double", "nullable": true }, "miscellaneousInfo": { "type": "string", "description": "Miscellaneous Information", "nullable": true }, "note": { "type": "string", "description": "Deduction Notes", "nullable": true }, "selfInsured": { "type": "boolean", "description": "Self-Insured Plan Flag. This will generate Part III of the employee's 1095-C Form", "nullable": true }, "priority": { "type": "integer", "description": "Priority determines the order in which a deduction is subtracted from gross pay. Priorities 1-4 are reserved for Statutory deductions(necessary by law), while 5-7 are reserved for Voluntary deductions(employee-elected).", "format": "int32", "nullable": true }, "loan401K": { "$ref": "#/components/schemas/Loan401KDto" }, "costCenters": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenterDto" }, "description": "An array of objects representing the Cost Centers", "nullable": true }, "limits": { "$ref": "#/components/schemas/CreateLimitsDto" } }, "additionalProperties": { "type": "object", "nullable": true }, "description": "A Payroll Deduction code is a unique identifier used by payroll systems to categorize and track specific deductions from an employee's paycheck.\r\nThese deductions can include taxes, health insurance premiums, retirement contributions, loan repayments, and more.\r\nEach type of deduction has its own unique code that allows it to be easily identified and processed by the payroll system.\r\nThis not only ensures accurate calculations and disbursements, but also helps with record-keeping and reporting requirements." }, "CreateLimitsDto": { "type": "object", "properties": { "goal": { "type": "number", "description": "The Goal is the deduction/earning limit. When deductions/earnings have met the limit, the employee pay deductions/earnings will stop.\r\nFor payroll, this amount is the lifetime deduction/earning limit.\r\nFor benefits, this limit amount could be annual.", "format": "double", "nullable": true }, "paidToDate": { "type": "number", "description": "Paid to Date tracks the amount paid toward the Goal. The Paid to Date amount will never be more than the Goal amount", "format": "double", "nullable": true }, "payPeriodMinimum": { "type": "number", "description": "Minimum for the pay period", "format": "double", "nullable": true }, "payPeriodMaximum": { "type": "number", "description": "Maximum for the pay period", "format": "double", "nullable": true }, "annualMaximum": { "type": "number", "description": "Entering an amount in the Annual Maximum field will override the system setting, and you'll need to manually manage the maximum each year.\r\nLeave this field blank to keep the system setting.", "format": "double", "nullable": true } }, "additionalProperties": { "type": "object", "nullable": true }, "description": "Limits are used to control the amount of an earning or deduction" }, "Loan401KDto": { "type": "object", "properties": { "loanNumber": { "type": "string", "description": "401K Loan Number. Provided by Record Keeper", "nullable": true }, "issueDate": { "type": "string", "description": "Date of 401K Loan Issued", "format": "date-time", "nullable": true }, "firstPaymentDate": { "type": "string", "description": "First Payment Date of 401K Loan", "format": "date-time", "nullable": true } }, "additionalProperties": { "type": "object", "nullable": true }, "description": "A 401K loan is a type of loan that allows you to borrow money against the balance of your 401K retirement plan, up to a certain limit. It's a way for individuals to access their retirement savings without incurring early withdrawal penalties or taxes. The borrower is expected to repay the loan, typically over five years, through payroll deductions. The values to insert a loan, like Loan Number, and First Payment Date are provided by the record keeper." } } } } ```