> ## Documentation Index > Fetch the complete documentation index at: https://developer.payrollintegrations.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Update Group > Submits a list of employee updates ## OpenAPI ````yaml api-reference/openapi.json POST /v1/employer-identifiers/{employer_identifier}/update-groups openapi: 3.0.3 info: title: Payroll Integrations Public API version: 1.0.0 description: Public API for Payroll Integrations platform license: name: MIT servers: - url: https://api.payrollintegrationsapp.com description: Production security: [] tags: - name: auth - name: employer-identifiers - name: meta - name: payroll-connections - name: payroll-platforms - name: roles - name: users - name: webhooks paths: /v1/employer-identifiers/{employer_identifier}/update-groups: post: tags: - employer-identifiers summary: Post an employee update group description: Submits a list of employee updates operationId: post_v1_employer_identifiers_employer_identifier_update_groups parameters: - name: employer_identifier in: path required: true schema: description: UUID of the employer identifier type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: UUID of the employer identifier requestBody: description: List of employee deduction updates to perform required: true content: application/json: schema: $ref: '#/components/schemas/CreateUpdateGroupRequest' example: updates: - employeeProfileId: 22222222-2222-2222-2222-222222222222 subcategory: ROTH calculationValue: '10' calculationType: PERCENT startDate: '2026-01-31' - employeeProfileId: 33333333-3333-3333-3333-333333333333 subcategory: 401K_PRETAX calculationValue: '150.00' calculationType: FLAT_DOLLAR startDate: '2026-01-31' - employeeProfileId: 44444444-4444-4444-4444-444444444444 subcategory: 401K_LOAN calculationValue: '100.00' calculationType: FLAT_DOLLAR startDate: '2026-01-31' loanIdentifier: MyLoanDeduction responses: '201': description: Update group created successfully content: application/json: schema: $ref: '#/components/schemas/CreateUpdateGroupResponse' example: updateGroupId: 55555555-5555-5555-5555-555555555555 '400': description: >- Invalid request parameters, or a transaction ID is required because the recordkeeper tracks update transaction status - use the recordkeeper-specific webhook endpoint instead. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid or missing token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: WWW-Authenticate: schema: description: Authentication challenge (Bearer) type: string description: Authentication challenge (Bearer) '403': description: >- Insufficient permissions or access denied, or the employer identifier belongs to a different recordkeeper. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Retry-After: schema: description: Number of seconds to wait before retrying type: string description: Number of seconds to wait before retrying '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '501': description: Deduction updates are not supported for TPA entities content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Not implemented errors: - Not implemented security: - bearerAuth: [] components: schemas: CreateUpdateGroupRequest: type: object properties: updates: type: array items: allOf: - type: object properties: employeeProfileId: description: The Payroll Integrations UUID for an employee profile type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ subcategory: description: >- The subcategory to apply the deduction to (e.g. 401K_PRETAX, ROTH, etc.) type: string enum: - 401K_PRETAX - 401K_CATCHUP - ROTH - ROTH_CATCHUP - 401K_LOAN - AFTER_TAX - MATCH - SAFE_HARBOR_MATCH - SAFE_HARBOR_NON_ELECTIVE - PROFIT_SHARING - OTHER - AFTER_TAX_CATCHUP - 401K_BONUS - AFTER_TAX_BONUS - ROTH_BONUS - QACA_MATCH - QACA_NON_ELECTIVE - QUALIFIED_NON_ELECTIVE_CONTRIBUTION - QUALIFIED_MATCHING_CONTRIBUTION - HSA_EMPLOYEE - HSA_EMPLOYER - LOAN_REPAYMENT_EMPLOYEE - LOAN_REPAYMENT_EMPLOYER - FSA_EMPLOYEE - FSA_EMPLOYER - 529_EMPLOYEE - 529_EMPLOYER - SEP_EMPLOYEE - SEP_EMPLOYER - SIMPLE_IRA_EMPLOYEE - SIMPLE_IRA_EMPLOYER - 403B_PRETAX - 403B_CATCHUP - 403B_ROTH - 403B_ROTH_CATCHUP - 403B_LOAN - 403B_AFTERTAX - 403B_AFTERTAX_CATCHUP - 403B_MATCH - TRADITIONAL_IRA - ROTH_IRA - PLAN_EXCLUDED_COMPENSATION - PLAN_INCLUDED_GROSS_COMPENSATION - NON_GROSS_COMPENSATION - EMPLOYER_MATCHING_CONTRIBUTIONS - EMPLOYER_CONTRIBUTION - EMPLOYEE_DEFINED_MONEYTYPE_1 - EMPLOYEE_DEFINED_MONEYTYPE_2 - EMPLOYER_DEFINED_MONEYTYPE_1 - EMPLOYER_DEFINED_MONEYTYPE_2 - EMPLOYER_DEFINED_MONEYTYPE_3 - EMPLOYER_DEFINED_MONEYTYPE_4 - EMPLOYER_DEFINED_MONEYTYPE_5 - EMPLOYER_DEFINED_MONEYTYPE_6 - SAFE_HARBOR_GRADED_CONTRIBUTIONS - MONEY_PURCHASE - CLIENT_SPECIFIC_1 - CLIENT_SPECIFIC_2 - CLIENT_SPECIFIC_3 - EMPLOYER_DISCRETIONARY - SAFE_HARBOR_PROFIT_SHARING - PENSION - PREVAILING_WAGE - 401K_BONUS_CATCHUP - ROTH_BONUS_CATCHUP - PLAN_EXCLUDED_BONUS - PLAN_EXCLUDED_AUTO_ALLOWANCE - PLAN_EXCLUDED_COMMISSIONS - PLAN_EXCLUDED_OVERTIME_COMPENSATION - PLAN_EXCLUDED_SEVERANCE_COMPENSATION - PLAN_EXCLUDED_MONEY_PURCHASE_CONTRIBUTIONS - PLAN_EXCLUDED_OTHER_COMPENSATION_CATEGORY_1 - PLAN_EXCLUDED_OTHER_COMPENSATION_CATEGORY_2 - PLAN_INCLUDED_BONUS - PLAN_INCLUDED_AUTO_ALLOWANCE - PLAN_INCLUDED_COMMISSIONS - PLAN_INCLUDED_OVERTIME_COMPENSATION - PLAN_INCLUDED_SEVERANCE_COMPENSATION - PLAN_INCLUDED_MONEY_PURCHASE_CONTRIBUTIONS - PLAN_INCLUDED_OTHER_COMPENSATION_CATEGORY_1 - PLAN_INCLUDED_OTHER_COMPENSATION_CATEGORY_2 - PRE_TAX_HEALTH_125 - 457_SALARY_DEFERRALS - OTHER_DEDUCTION_CATEGORY_1 - OTHER_DEDUCTION_CATEGORY_2 - EMPLOYER_NON_ELECTIVE - ROTH_EMPLOYER_MATCH - CLIENT_SPECIFIC_ADDITIONAL_PLAN_EXCLUDED_COMPENSATION - EMPLOYEE_MEDICARE - EMPLOYEE_SOCIAL_SECURITY - EMPLOYEE_FEDERAL_INCOME_TAX - EMPLOYEE_STATE_INCOME_TAX - EMPLOYEE_LOCAL_INCOME_TAX - EMPLOYEE_STATE_UNEMPLOYMENT - EMPLOYEE_WORKERS_COMPENSATION_INSURANCE - EMPLOYEE_STATE_INSURANCE - EMPLOYEE_OTHER_TAX - EMPLOYER_MEDICARE - EMPLOYER_SOCIAL_SECURITY - EMPLOYER_FEDERAL_UNEMPLOYMENT - EMPLOYER_STATE_UNEMPLOYMENT - EMPLOYER_WORKERS_COMPENSATION_INSURANCE - EMPLOYER_STATE_INSURANCE - EMPLOYER_OTHER_TAX - ROTH_SUPER_CATCHUP - UNKNOWN_TAX - EMPLOYEE_LIMITED_FSA - EMPLOYER_LIMITED_FSA - EMPLOYEE_DEPENDENT_CARE - EMPLOYER_DEPENDENT_CARE - EMPLOYEE_COMMUTER_MASS_TRANSIT_PRETAX - EMPLOYER_COMMUTER_MASS_TRANSIT_PRETAX - EMPLOYEE_COMMUTER_MASS_TRANSIT_POSTTAX - EMPLOYEE_COMMUTER_PARKING_PRETAX - EMPLOYER_COMMUTER_PARKING_PRETAX - EMPLOYEE_COMMUTER_PARKING_POSTTAX - PRETAX_SUPER_CATCHUP - SS_401K_MATCH startDate: description: Start date for the deduction in ISO format YYYY-MM-DD type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ loanIdentifier: description: >- The label to apply to the employee's loan deduction, only applicable when subcategory is 401K_LOAN type: string required: - employeeProfileId - subcategory - startDate - anyOf: - type: object properties: calculationValue: description: >- Flat dollar deduction amount in number-string format, must include 2 decimal places (e.g. "12.34") type: string pattern: ^\d{1,16}\.\d{2}$ calculationType: description: >- Denotes whether calculationValue is treated as a flat dollar amount or a percentage type: string enum: - FLAT_DOLLAR required: - calculationValue - calculationType - type: object properties: calculationValue: description: >- Percentage deduction in number-string format with up to 2 decimal places type: string pattern: ^(100(\.00?)?|[1-9]\d?(\.\d{1,2})?|0(\.\d{1,2})?)$ calculationType: description: >- Denotes whether calculationValue is treated as a flat dollar amount or a percentage type: string enum: - PERCENT required: - calculationValue - calculationType required: - updates CreateUpdateGroupResponse: type: object properties: updateGroupId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - updateGroupId additionalProperties: false ErrorResponse: type: object properties: message: description: Human-readable error message type: string errors: description: Array of specific error details type: array items: type: string required: - message - errors additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token obtained from the /v1/auth/token endpoint. Send as: Authorization: Bearer . ````