--- updatedAt: 2026-05-26T23:06:49.000Z agentTools: siteIndex: https://docs.gusto.com/llms.txt projectIndex: https://docs.gusto.com/embedded-payroll/llms.txt --- # Create an off-cycle payroll Creates a new, unprocessed, off-cycle payroll. ## `off_cycle_reason` By default: - External benefits and deductions will be included when the `off_cycle_reason` is set to `Correction`. - All benefits and deductions are blocked when the `off_cycle_reason` is set to `Bonus`. These elections can be overridden with the `skip_regular_deductions` boolean. scope: `payrolls:run` # OpenAPI definition ```json { "openapi": "3.1.0", "tags": [ { "name": "Payrolls" } ], "info": { "title": "Gusto API", "version": "2026-06-15", "termsOfService": "https://gusto.com/about/terms/developer-terms-of-service", "description": "Welcome to Gusto's Embedded Payroll API documentation!", "contact": { "name": "Developer Relations", "email": "developer@gusto.com" }, "x-release-status": "stable" }, "servers": [ { "url": "https://api.gusto-demo.com", "description": "Demo", "x-speakeasy-server-id": "demo" } ], "security": [ { "CompanyAccessAuth": [] } ], "components": { "schemas": { "Not-Found-Error-Object": { "description": "Not Found \n \nThe requested resource does not exist. Make sure the provided ID/UUID is valid.", "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "error_key", "category" ], "properties": { "error_key": { "type": "string", "description": "Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error." }, "category": { "type": "string", "description": "Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration." }, "message": { "type": "string", "description": "Provides details about the error - generally this message can be surfaced to an end user." } } } } }, "x-examples": { "not_found": { "errors": [ { "error_key": "request", "category": "not_found", "message": "The requested resource was not found." } ] }, "deprecated_accept_terms_of_service": { "errors": [ { "error_key": "request", "category": "deprecated_endpoint", "message": "The requested endpoint is no longer supported in the requested API version. Use POST /v1/partner_managed_companies/:company_uuid/terms_of_service instead" } ] }, "deprecated_retrieve_terms_of_service": { "errors": [ { "error_key": "request", "category": "deprecated_endpoint", "message": "The requested endpoint is no longer supported in the requested API version. Use PUT /v1/partner_managed_companies/:company_uuid/terms_of_service instead" } ] } } }, "Unprocessable-Entity-Error-Object": { "description": "Unprocessable Entity\n \nThis may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.\n", "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Entity-Error-Object" } } }, "x-examples": { "tax_filing_invalid_status": { "errors": [ { "error_key": "status", "category": "invalid_attribute_value", "message": "Status must be one of: not_started, in_progress, blocked, accepted, not_required, failed" } ] }, "tax_filing_invalid_sort_by": { "errors": [ { "error_key": "sort_by", "category": "invalid_attribute_value", "message": "Sort by must be one of period_start, period_end, due_date, filed_at, optionally suffixed with :asc or :desc" } ] }, "tax_filing_invalid_period_start": { "errors": [ { "error_key": "period_start", "category": "invalid_attribute_value", "message": "Period start must be a valid ISO 8601 date" } ] }, "tax_filing_invalid_jurisdiction": { "errors": [ { "error_key": "jurisdiction", "category": "invalid_attribute_value", "message": "Jurisdiction must be two-letter state codes or US (invalid: XX)" } ] }, "tax_payment_invalid_sort_by": { "errors": [ { "error_key": "sort_by", "category": "invalid_parameter", "message": "Unknown sort_by: bogus:asc. Must be one of amount, due_date, payment_sent_on, period_end, period_start, optionally suffixed with :asc or :desc" } ] }, "tax_payment_inverted_range": { "errors": [ { "error_key": "due_date_to", "category": "invalid_attribute_value", "message": "Due date to must be greater than or equal to due date from" } ] }, "partner_managed_company_disassociate_not_associated": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Could not disassociate from embedded payroll: company not associated with partner." } ] }, "bulk_report_invalid_report_type": { "errors": [ { "error_key": "batch", "category": "nested_errors", "errors": [ { "idx": 0, "category": "nested_errors", "errors": [ { "error_key": "report_type", "category": "invalid_attribute_value", "message": "Invalid report type: invalid_type" } ] } ] } ] }, "nested_disbursement_errors": { "errors": [ { "error_key": "disbursements", "category": "nested_errors", "metadata": { "employee_uuid": "invalid-uuid-1" }, "errors": [ { "error_key": "employee_uuid", "category": "not_found", "message": "Disbursement not found." } ] }, { "error_key": "disbursements", "category": "nested_errors", "metadata": { "employee_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "errors": [ { "error_key": "payment_method", "category": "invalid_attribute_value", "message": "Payment method must be one of: Direct Deposit, Check." }, { "error_key": "payment_status", "category": "invalid_attribute_value", "message": "Payment status is not valid for payment method 'InvalidMethod'." } ] } ] }, "webhook_subscription_url_missing": { "errors": [ { "error_key": "url", "category": "invalid_attribute_value", "message": "URL can't be blank" } ] }, "webhook_subscription_invalid_entity_type": { "errors": [ { "error_key": "subscription_entities.entity_type", "category": "invalid_attribute_value", "message": "Entity type is not included in the list" } ] }, "invalid_token": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Invalid verification token" } ] }, "notification_supporting_data_invalid": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Invalid notification: supporting data is no longer valid." } ] }, "employee_payment_details_invalid_filter_combination": { "errors": [ { "error_key": "base", "category": "invalid_request_error", "message": "Cannot filter by both employee_uuid and payroll_uuid simultaneously." } ] }, "contractor_document_sign_missing_agree": { "errors": [ { "error_key": "agree", "category": "invalid_attribute_value", "message": "You must agree to sign the document electronically" } ] }, "contractor_document_sign_invalid_ip_address": { "errors": [ { "error_key": "signed_by_ip_address", "category": "invalid_attribute_value", "message": "Signed by ip address is invalid" } ] }, "contractor_document_sign_missing_fields": { "errors": [ { "error_key": "fields", "category": "nested_errors", "errors": [ { "error_key": "dogs_name", "category": "invalid_attribute_value", "message": "Field is required." }, { "error_key": "dogs_favorite_food", "category": "invalid_attribute_value", "message": "Field is required." }, { "error_key": "dogs_signature", "category": "invalid_attribute_value", "message": "Field is required." } ] } ] }, "contractor_document_sign_already_signed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This form has already been signed" } ] }, "contractor_document_unsupported_form_type": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Form type is not supported" } ] }, "bank_account_create_unfunded_payments": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "FundingMethod has unfunded payments" } ] }, "bank_account_delete_unfunded_payments": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "FundingMethod has unfunded payments" } ] }, "bank_account_verify_incorrect_deposits": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Your bank account cannot be verified. Please check the test deposit amounts." } ] }, "bank_account_verify_already_verified": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Your bank account has already been verified." } ] }, "bank_account_missing_routing": { "errors": [ { "error_key": "routing_number", "category": "invalid_attribute_value", "message": "Routing number is required." } ] }, "plaid_processor_token_missing": { "errors": [ { "error_key": "processor_token", "category": "invalid_attribute_value", "message": "Processor token param is missing or the value is empty: processor_token" } ] }, "plaid_bank_account_linking_unavailable": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This company's bank account can't be linked through this endpoint. Contact Gusto support to set it up." } ] }, "contractor_bank_account_invalid_account_number": { "errors": [ { "error_key": "account_number", "category": "invalid_attribute_value", "message": "Invalid account number format" } ] }, "contractor_bank_account_invalid_account_type": { "errors": [ { "error_key": "account_type", "category": "invalid_attribute_value", "message": "Account type's value is not included in the list" } ] }, "contractor_payment_method_invalid_type": { "errors": [ { "error_key": "type", "category": "invalid_attribute_value", "message": "Payment method must be 'Check' or 'Direct Deposit'" } ] }, "company_attachment_missing_document": { "errors": [ { "error_key": "base", "category": "missing_parameter", "message": "document is required." } ] }, "company_attachment_document_not_a_file": { "errors": [ { "error_key": "document", "category": "invalid_attribute_value", "message": "Parameter `document` must be an uploaded file. Send it in a multipart/form-data request, not a JSON body." } ] }, "company_attachment_invalid_category": { "errors": [ { "error_key": "category", "category": "invalid_attribute_value", "message": "Category invalid_category is not supported. Supported categories: gep_notice, compliance." } ] }, "company_attachment_invalid_file_type": { "errors": [ { "error_key": "file", "category": "invalid_attribute_value", "message": "Uh oh. That file type is not allowed. Supported file types are .qbb, .qbm, .gif, .jpg, .png, .pdf, .xls, .xlsx, .doc and .docx" }, { "error_key": "file_file_name", "category": "invalid_attribute_value", "message": "File file name is invalid" } ] }, "provision_missing_user": { "errors": [ { "error_key": "user", "category": "missing_parameter", "message": "user is required." } ] }, "provision_invalid_email": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Invalid email address." } ] }, "admin_missing_required_field": { "errors": [ { "error_key": "last_name", "category": "missing_parameter", "message": "last_name is required." } ] }, "admin_duplicate_email": { "errors": [ { "error_key": "email", "category": "invalid_attribute_value", "message": "User has already been taken" }, { "error_key": "company", "category": "invalid_attribute_value", "message": "Company is invalid" } ] }, "sandbox_w2_already_generated": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "W2 already generated for this year" } ] }, "sandbox_w2_invalid_year": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Cannot generate form for year 1800" } ] }, "sandbox_1099_invalid_year": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Please enter a year between 2015 and 2024" } ] }, "employee_bank_account_missing_name": { "errors": [ { "error_key": "name", "category": "invalid_attribute_value", "message": "Name is required" } ] }, "employee_bank_account_invalid_account_number": { "errors": [ { "error_key": "account_number", "category": "invalid_attribute_value", "message": "Invalid account number" } ] }, "employee_bank_account_duplicate": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Bank account with the same details already exists" } ] }, "employee_bank_account_invalid_routing_on_update": { "errors": [ { "error_key": "routing_number", "category": "invalid_attribute_value", "message": "Invalid routing number" } ] }, "payment_configs_missing_parameter": { "errors": [ { "error_key": "base", "category": "missing_parameter", "message": "At least one parameter must be provided" } ] }, "payment_configs_invalid_fast_payment_limit": { "errors": [ { "error_key": "fast_payment_limit", "category": "invalid_attribute_value", "message": "Fast payment limit should be a number" } ] }, "pay_periods_invalid_end_date": { "errors": [ { "error_key": "end_date", "category": "invalid_parameter", "message": "End date cannot be more than 3 months in future" } ] }, "company_industry_selection_naics_code_required": { "errors": [ { "error_key": "naics_code", "category": "invalid_attribute_value", "message": "Naics code is required." } ] }, "company_industry_selection_naics_code_invalid": { "errors": [ { "error_key": "naics_code", "category": "invalid_attribute_value", "message": "Naics code must be equal to 6 digits." } ] }, "company_industry_selection_sics_codes_invalid": { "errors": [ { "error_key": "sic_codes", "category": "invalid_attribute_value", "message": "Sic codes must be equal to 4 digits" } ] }, "time_off_policy_name_required": { "errors": [ { "error_key": "name", "category": "invalid_attribute_value", "message": "Name is required." } ] }, "time_off_policy_unlimited_invalid_accrual_rate": { "errors": [ { "error_key": "accrual_rate", "category": "invalid_operation", "message": "Accrual rate must be blank for unlimited policies." } ] }, "time_off_policy_pending_requests": { "errors": [ { "error_key": "time_off_policy", "category": "invalid_operation", "message": "Cannot deactivate policy with pending time off requests." } ] }, "time_off_policy_employees_required": { "errors": [ { "error_key": "employees", "category": "invalid_attribute_value", "message": "Employees are required." } ] }, "time_off_policy_unlimited_balance_update": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Can not adjust balances for unlimited policies." } ] }, "payroll_sync_invalid_pay_schedule": { "errors": [ { "error_key": "pay_schedule_uuid", "category": "invalid_attribute_value", "message": "Pay schedule uuid could not be found." } ] }, "payroll_sync_no_employees": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "There are no employees to run payroll for in the selected pay period." } ] }, "payroll_sync_empty_export": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "There are no hours to sync to payroll for the selected pay period." } ] }, "payroll_update_payroll_item_validation_error": { "errors": [ { "error_key": "employee_compensations", "category": "nested_errors", "errors": [ { "error_key": "payment_method", "category": "invalid_attribute_value", "message": "Payment method cannot be changed for check-only payrolls. All employees must be paid by check." } ] } ] }, "payroll_update_recurring_reimbursement_error": { "errors": [ { "error_key": "employee_compensations", "category": "nested_errors", "errors": [ { "error_key": "reimbursements", "category": "invalid_attribute_value", "message": "Cannot update recurring reimbursements through payroll updates. Update the recurring reimbursement directly." } ] } ] }, "migrate_company_terms_of_service": { "errors": [ { "error_key": "base", "category": "migration_blocker", "message": "Terms of service must be accepted by a company payroll admin.", "metadata": { "key": "terms_of_service" } } ] }, "migrate_company_already_migrated": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "The operation was already performed for this company.", "metadata": { "key": "migrated_company" } } ] }, "partner_managed_company_create_missing_company": { "errors": [ { "error_key": "company", "category": "missing_parameter", "message": "company is required." } ] }, "partner_managed_company_create_invalid_name": { "errors": [ { "error_key": "name", "category": "invalid_attribute_value", "message": "Company name must be at least 2 characters" } ] }, "partner_managed_company_tos_invalid_ip_address": { "errors": [ { "error_key": "ip_address", "category": "invalid_attribute_value", "message": "A valid user's IP Address is required in order to accept terms of service." } ] }, "partner_managed_company_tos_missing_external_user_id": { "errors": [ { "error_key": "external_user_id", "category": "invalid_attribute_value", "message": "Your platform's User ID is required in order to accept terms of service." } ] }, "partner_managed_company_tos_invalid_user_email": { "errors": [ { "error_key": "email", "category": "invalid_attribute_value", "message": "Email does not belong to company user." } ] }, "holiday_pay_policy_already_exists": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Company already has a holiday pay policy." } ] }, "holiday_pay_policy_not_exists": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Company does not have a holiday pay policy, please create one" } ] }, "holiday_pay_policy_invalid_employees": { "errors": [ { "error_key": "employees", "category": "invalid_attribute_value", "message": "Invalid employee uuids provided." } ] }, "onboarded_employee": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Cannot delete onboarded employee" } ] }, "garnishment_invalid_amount": { "errors": [ { "error_key": "amount", "category": "invalid_attribute_value", "message": "Amount must be greater than or equal to 0" } ] }, "garnishment_pay_period_exceeds_annual": { "errors": [ { "error_key": "pay_period_maximum", "category": "invalid_attribute_value", "message": "Pay period maximum must be less than annual maximum" } ] }, "garnishment_type_cannot_change": { "errors": [ { "error_key": "garnishment_type", "category": "invalid_attribute_value", "message": "Garnishment type cannot change" } ] }, "garnishment_child_support_invalid_fips": { "errors": [ { "error_key": "child_support", "category": "nested_errors", "errors": [ { "error_key": "fips_code", "category": "invalid_attribute_value", "message": "FIPS code is not valid for CA" } ] } ] }, "garnishment_child_support_missing_fields": { "errors": [ { "error_key": "child_support", "category": "nested_errors", "errors": [ { "error_key": "state", "category": "invalid_attribute_value", "message": "Select a valid state agency" }, { "error_key": "payment_period", "category": "invalid_attribute_value", "message": "Select a valid payment period" }, { "error_key": "case_number", "category": "invalid_attribute_value", "message": "Case number is required" } ] } ] }, "invalid_attribute": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "There is an error in the request body." } ] }, "pay_schedule_missing_anchor_dates": { "errors": [ { "error_key": "anchor_pay_date", "category": "invalid_attribute_value", "message": "can't be blank" }, { "error_key": "anchor_end_of_pay_period", "category": "invalid_attribute_value", "message": "can't be blank" } ] }, "pay_schedule_invalid_frequency": { "errors": [ { "error_key": "frequency", "category": "invalid_attribute_value", "message": "is not included in the list" } ] }, "pay_schedule_malformed_dates": { "errors": [ { "error_key": "anchor_pay_date", "category": "invalid_attribute_value", "message": "is invalid" }, { "error_key": "anchor_end_of_pay_period", "category": "invalid_attribute_value", "message": "is invalid" } ] }, "pay_schedule_pay_days_must_be_paired": { "errors": [ { "error_key": "second_pay_period_pay_day", "category": "invalid_attribute_value", "message": "Second pay period pay day must be provided together with the other pay day" } ] }, "pay_schedule_workweek_start_day_not_yet_changeable": { "errors": [ { "error_key": "workweek_start_day", "category": "invalid_attribute_value", "message": "Workweek start day can only be changed once per pay period. Please wait until 2022-10-05 to change it again." } ] }, "skip_payroll_invalid_payroll_type": { "errors": [ { "error_key": "payroll_type", "category": "invalid_attribute_value", "message": "Payroll type is not valid." } ] }, "paid_holidays_invalid_year": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Invalid year provided." } ] }, "tax_requirements_invalid_requirement_key": { "errors": [ { "error_key": "requirement_sets", "category": "nested_errors", "metadata": { "key": "misc", "effective_from": "", "state": "NY" }, "errors": [ { "error_key": "requirements", "category": "nested_errors", "metadata": { "key": "1-2-3-4" }, "errors": [ { "error_key": "key", "category": "invalid_attribute_value", "message": "Key is required" } ] } ] } ] }, "tax_requirements_invalid_value_type": { "errors": [ { "error_key": "requirement_sets", "category": "nested_errors", "metadata": { "key": "misc", "effective_from": "", "state": "NY" }, "errors": [ { "error_key": "requirements", "category": "nested_errors", "metadata": { "key": "71653ec0-00b5-4c66-a58b-22ecf21704c5" }, "errors": [ { "error_key": "value", "category": "invalid_attribute_value", "message": "Expected a value of type boolean, but got string" } ] } ] } ] }, "tax_requirements_domain_validation_failure": { "errors": [ { "error_key": "requirement_sets", "category": "nested_errors", "metadata": { "key": "taxrates", "effective_from": "2026-01-01", "state": "NY" }, "errors": [ { "error_key": "requirements", "category": "nested_errors", "metadata": { "key": "e0ac2284-8d30-4100-ae23-f85f9574868b" }, "errors": [ { "error_key": "value", "category": "invalid_attribute_value", "message": "SUI Tax Rate must be between 0.00% and 9.825%" } ] } ] } ] }, "company_cannot_enable_contractor_only": { "errors": [ { "error_key": "contractor_only", "category": "invalid_attribute_value", "message": "Contractor only cannot be enabled for existing companies." } ] }, "company_missing_parameter": { "errors": [ { "error_key": "base", "category": "missing_parameter", "message": "contractor_only is required." } ] }, "starting_after_uuid_invalid": { "errors": [ { "error_key": "starting_after_uuid", "category": "invalid_attribute_value", "message": "Parameter 'starting_after_uuid' does not correspond to a valid event." } ] }, "resource_uuid_invalid": { "errors": [ { "error_key": "resource_uuid", "category": "invalid_attribute_value", "message": "Parameter 'resource_uuid' does not correspond to a valid resource." } ] }, "payroll_gross_up_invalid_net_pay": { "errors": [ { "error_key": "net_pay", "category": "invalid_attribute_value", "message": "Net pay must be a number." } ] }, "payroll_accruing_hours_invalid": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Hours cannot be negative." } ] }, "payroll_cannot_cancel": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Payroll cannot be canceled." } ] }, "frozen_payroll": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This payroll has already been processed. Its data cannot be updated or altered." } ] }, "frozen_payroll_processing": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This payroll is being processed and cannot be updated at this time." } ] }, "unmodifiable_payroll_type": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This type of payroll cannot be modified or processed. It is reserved for system processes." } ] }, "employee_uuids_required": { "errors": [ { "error_key": "employee_uuids", "category": "invalid_attribute_value", "message": "At least one employee_uuid is required to create an off-cycle payroll." } ] }, "invalid_employee_uuids_format": { "errors": [ { "error_key": "employee_uuids", "category": "invalid_attribute_value", "message": "Parameter employee_uuids must be an array." } ] }, "maximum_employee_uuids_surpassed": { "errors": [ { "error_key": "employee_uuids", "category": "invalid_attribute_value", "message": "Exceeded maximum of 100 for lookup." } ] }, "maximum_off_roster_additions_surpassed": { "errors": [ { "error_key": "employee_uuids", "category": "invalid_attribute_value", "message": "Cannot add more than 25 new employees to the payroll per call." } ] }, "invalid_employee_uuid": { "errors": [ { "error_key": "employee_uuids", "category": "invalid_attribute_value", "message": "Invalid Employee UUID(s).", "metadata": { "entity_type": "Employee", "entity_uuid": "invalid-uuid-123" } } ] }, "payroll_blocker_missing_bank_info": { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company must have a bank account in order to run payroll.", "metadata": { "key": "missing_bank_info" } } ] }, "payroll_blocker_missing_employee_setup": { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company must add employees in order to run payroll.", "metadata": { "key": "missing_employee_setup" } } ] }, "payroll_blocker_missing_federal_tax_setup": { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company must complete federal tax setup in order to run payroll.", "metadata": { "key": "missing_federal_tax_setup" } } ] }, "payroll_blocker_missing_bank_verification": { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company bank account must be verified in order to run payroll.", "metadata": { "key": "missing_bank_verification" } } ] }, "payroll_blocker_suspended": { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company is suspended and cannot run payroll.", "metadata": { "key": "suspended" } } ] }, "submission_blocker_missing_selection": { "errors": [ { "error_key": "submission_blockers", "category": "invalid_attribute_value", "message": "Submission blockers selections required" } ] }, "submission_blocker_invalid_option": { "errors": [ { "error_key": "submission_blockers", "category": "nested_errors", "metadata": { "blocker_type": "fast_ach_threshold_exceeded" }, "errors": [ { "error_key": "selected_option", "category": "invalid_attribute_value", "message": "Selection is not available to resolve Fast ACH Threshold Exceeded. Please choose one of Wire In, Move To Four Day" } ] } ] }, "invalid_version": { "errors": [ { "error_key": "base", "category": "invalid_resource_version", "message": "You are attempting to update a resource using an out-of-date version." } ] }, "payroll_update_stale_employee_compensation_version": { "errors": [ { "error_key": "base", "category": "invalid_resource_version", "message": "Supplied Version (stale-version) is invalid.", "metadata": { "entity_type": "Employee", "entity_uuid": "a8e9d2c6-1f3b-4d5a-9c8e-7f0b2d4c6e8a" } } ] }, "employee_create_self_onboarding_missing_email": { "errors": [ { "error_key": "email", "category": "invalid_attribute_value", "message": "Email is required to invite the employee to self-onboard" } ] }, "employee_benefit_simple_ira_elective_mismatch": { "errors": [ { "error_key": "elective", "category": "invalid_attribute_value", "message": "Elective must be true for matching Simple IRA benefits" } ] }, "signatory_email_required": { "errors": [ { "error_key": "email", "category": "invalid_attribute_value", "message": "Email is required" } ] }, "signatory_company_already_has_signatory": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Cannot have more than one signatory in a company. Please remove the existing signatory before adding a new one." } ] }, "mixed_disbursement_errors": { "errors": [ { "error_key": "disbursements", "category": "nested_errors", "metadata": { "contractor_payment_uuid": "invalid-uuid-1" }, "errors": [ { "error_key": "contractor_payment_uuid", "category": "not_found", "message": "Disbursement not found." } ] }, { "error_key": "disbursements", "category": "nested_errors", "metadata": { "contractor_payment_uuid": "d0dfa222-ad08-4ea7-a06a-717688c3b179" }, "errors": [ { "error_key": "payment_method", "category": "invalid_attribute_value", "message": "Payment method must be one of: Direct Deposit, Check." }, { "error_key": "payment_status", "category": "invalid_attribute_value", "message": "Payment status is not valid for payment method 'InvalidMethod'." } ] } ] }, "not_found": { "errors": [ { "error_key": "request", "category": "not_found", "message": "The requested resource was not found." } ] }, "finish_onboarding_incomplete": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Company is not ready to exit onboarding." } ] }, "federal_tax_invalid_ein": { "errors": [ { "error_key": "ein", "category": "invalid_attribute_value", "message": "EIN must be 9 digits" } ] }, "federal_tax_ein_cannot_change": { "errors": [ { "error_key": "ein", "category": "invalid_attribute_value", "message": "EIN cannot be updated after company has been onboarded. Please contact support to update the EIN." } ] }, "federal_tax_legal_name_cannot_change": { "errors": [ { "error_key": "legal_name", "category": "invalid_attribute_value", "message": "Legal name cannot be updated after company has been onboarded. Please contact support to update the legal name." } ] }, "ein_collision": { "errors": [ { "error_key": "ein", "category": "invalid_attribute_value", "message": "EIN is already in use" } ] }, "company_location_validation": { "errors": [ { "error_key": "street_1", "category": "invalid_attribute_value", "message": "Must include a street address" }, { "error_key": "city", "category": "invalid_attribute_value", "message": "Must include a city" }, { "error_key": "state", "category": "invalid_attribute_value", "message": "State is in the wrong format" }, { "error_key": "zip", "category": "invalid_attribute_value", "message": "Please enter a valid zip code (e.g. 12345)." }, { "error_key": "phone_number", "category": "invalid_attribute_value", "message": "Phone number must be 10 digits" } ] }, "conflict": { "errors": [ { "error_key": "request", "category": "duplicate_operation", "message": "A resource with these attributes already exists." } ] }, "invalid_parameter": { "errors": [ { "error_key": "request", "category": "invalid_parameter", "message": "The provided parameter is invalid or missing." } ] }, "invalid_sort_by": { "errors": [ { "error_key": "sort_by", "category": "invalid_parameter", "message": "Invalid sort order or direction." } ] }, "flow_invalid_entity": { "errors": [ { "error_key": "entity_type", "category": "invalid_attribute_value", "message": "Invalid flow entity" }, { "error_key": "entity_uuid", "category": "invalid_attribute_value", "message": "Invalid flow entity" } ] }, "flow_nested_options_errors": { "errors": [ { "error_key": "options", "category": "nested_errors", "metadata": { "flow_type": "company_forms" }, "errors": [ { "error_key": "form_types", "category": "invalid_attribute_value", "message": "Supplied value 'invalid' contains no permitted values" } ] } ] }, "basic": { "errors": [ { "error_key": "base", "category": "payroll_blocker", "message": "Company must complete all onboarding requirements in order to run payroll.", "metadata": { "key": "needs_onboarding" } } ] }, "contractor_already_onboarded": { "errors": [ { "error_key": "onboarding_status", "category": "invalid_attribute_value", "message": "Contractor is already fully onboarded" } ] }, "contractor_is_active_pending_dismissal": { "errors": [ { "error_key": "is_active", "category": "invalid_attribute_value", "message": "Cannot deactivate while a dismissal is scheduled. Use the cancel termination endpoint to remove the pending dismissal first." } ] }, "contractor_is_active_pending_dismissal_uncancelable": { "errors": [ { "error_key": "is_active", "category": "invalid_attribute_value", "message": "Cannot deactivate while a non-cancelable dismissal is in progress. The dismissal has already been processed." } ] }, "contractor_is_active_pending_rehire": { "errors": [ { "error_key": "is_active", "category": "invalid_attribute_value", "message": "Cannot reactivate while a rehire is scheduled. Use the cancel rehire endpoint to remove the pending rehire first." } ] }, "contractor_rehire_start_date_required": { "errors": [ { "error_key": "start_date", "category": "invalid_attribute_value", "message": "Start date is required" } ] }, "contractor_rehire_no_pending": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "No pending rehire to cancel" } ] }, "contractor_termination_end_date_required": { "errors": [ { "error_key": "end_date", "category": "invalid_attribute_value", "message": "End date is required" } ] }, "contractor_termination_no_pending_dismissal": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "No pending dismissal to cancel" } ] }, "contractor_address_invalid_attribute": { "errors": [ { "error_key": "street_1", "category": "invalid_attribute_value", "message": "Must include a street address" } ] }, "contractor_payment_invalid_wage": { "errors": [ { "error_key": "wage", "category": "invalid_attribute_value", "message": "Wage must be greater than or equal to 0." } ] }, "contractor_payment_cannot_cancel": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Payment has already been processed and cannot be cancelled. Contact support directly." } ] }, "contractor_payment_should_not_be_funded": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This payment should not be funded." } ] }, "contractor_payments_preview_no_payments": { "errors": [ { "error_key": "contractor_payments", "category": "invalid_attribute_value", "message": "Please enter a contractor payment before continuing." } ] }, "ytd_benefit_amounts_invalid_tax_year": { "errors": [ { "error_key": "tax_year", "category": "invalid_attribute_value", "message": "Tax year must be greater than or equal to 2000" } ] }, "printable_payroll_checks_invalid_printing_format": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Invalid printing_format 'bad_name', only 'top' and 'bottom' supported" } ] }, "recovery_case_not_redebitable": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Unable to initiate another redebit at this time. Please contact support." } ] }, "recovery_case_exceeded_retries": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "You exceeded the maximum redebit attempts. Please contact support." } ] }, "report_invalid_columns": { "errors": [ { "error_key": "columns", "category": "invalid_attribute_value", "message": "Invalid column(s): unexpected_column" } ] }, "general_ledger_invalid_aggregation": { "errors": [ { "error_key": "aggregation", "category": "invalid_attribute_value", "message": "Invalid aggregation option." } ] }, "report_template_invalid_report_type": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Invalid report type" } ] }, "time_sheet_invalid_entries": { "errors": [ { "error_key": "entries", "category": "invalid_attribute_value", "message": "Entries are invalid" } ] }, "time_sheet_invalid_attribute": { "errors": [ { "error_key": "time_zone", "category": "invalid_attribute_value", "message": "Time zone is invalid" } ] }, "time_sheet_version_invalid": { "errors": [ { "error_key": "version", "category": "invalid_attribute_value", "message": "Version 'somefakeversion' does not match the latest version of this object" } ] }, "time_sheets_batch_overlapping_shifts": { "errors": [ { "error_key": "time_sheets", "category": "invalid_attribute_value", "message": "Time sheets shifts overlap for entity 123e4567-e89b-12d3-a456-426614174000 of type Employee." } ] }, "time_sheets_batch_duplicate_external_ids": { "errors": [ { "error_key": "time_sheets", "category": "invalid_attribute_value", "message": "Time sheets duplicate external ids: shift-1001." } ] }, "time_sheets_batch_too_many_time_sheets": { "errors": [ { "error_key": "time_sheets", "category": "invalid_attribute_value", "message": "Time sheets is too big (maximum is 500 elements)." } ] }, "time_sheets_batch_idempotency_key_already_used": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Batch with idempotency key 2f0c6a4e-8f3b-4d0e-9a51-6f1d2c7b9e10 already exists." } ] }, "time_sheets_batch_invalid_time_sheet": { "errors": [ { "error_key": "time_sheets[0]", "category": "nested_errors", "errors": [ { "error_key": "shift_started_at", "category": "invalid_attribute_value", "message": "Shift started at is required" } ] } ] }, "time_off_request_cannot_delete": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This time off request cannot be deleted." } ] }, "time_off_request_cannot_approve": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Cannot approve this request." } ] }, "time_off_request_missing_employer_note": { "errors": [ { "error_key": "employer_note", "category": "missing_parameter", "message": "'employer_note' is required" } ] }, "time_off_request_invalid_status_filter": { "errors": [ { "error_key": "status", "category": "invalid_parameter", "message": "Parameter `status` contains invalid value(s): cancelled. Allowed values: pending, approved, declined, consumed." } ] }, "resource": { "errors": [ { "error_key": "first_name", "category": "invalid_attribute_value", "message": "First name is required" }, { "error_key": "date_of_birth", "category": "invalid_attribute_value", "message": "Date of birth is not a valid date" } ] }, "nested": { "errors": [ { "error_key": "contractor_payments", "category": "nested_errors", "metadata": { "contractor_uuid": "72ae4617-daa9-4ed7-85e0-18ed5d0ee835" }, "errors": [ { "error_key": "hours", "category": "invalid_attribute_value", "message": "Ella Fitzgerald is paid fixed wage and hours cannot be set on a contractor payment" } ] }, { "error_key": "contractor_payments", "category": "nested_errors", "metadata": { "contractor_uuid": "2d7bf62c-babf-4a12-8292-340e2d9cab28" }, "errors": [ { "error_key": "wage", "category": "invalid_attribute_value", "message": "Isaiah Berlin is paid hourly and wage cannot be set on a contractor payment" } ] } ] }, "compensation_invalid_rate": { "errors": [ { "error_key": "rate", "category": "invalid_attribute_value", "message": "Rate is not a valid number" } ] }, "compensation_invalid_payment_unit": { "errors": [ { "error_key": "payment_unit", "category": "invalid_attribute_value", "message": "Payment unit must be one of Hour, Week, Month, or Year" } ] }, "compensation_already_processed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Compensation has already been processed on payroll. It is no longer modifiable." } ] }, "termination_already_terminated": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee may only have one termination" } ] }, "termination_invalid_effective_date": { "errors": [ { "error_key": "effective_date", "category": "invalid_attribute_value", "message": "Effective date is not a valid date" } ] }, "termination_effective_date_required": { "errors": [ { "error_key": "effective_date", "category": "invalid_attribute_value", "message": "Effective date is required" } ] }, "termination_already_in_effect": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee has already been terminated" } ] }, "termination_payroll_exists": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Cannot cancel a termination with a termination payroll" } ] }, "termination_rehired": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Unable to modify a termination with a future rehire." } ] }, "job_title_required": { "errors": [ { "error_key": "title", "category": "invalid_attribute_value", "message": "Title is required" } ] }, "job_primary_cannot_delete": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee's primary job cannot be set to inactive." } ] }, "job_exempt_multiple_jobs": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Only hourly employees can have multiple jobs." } ] }, "job_invalid_hire_date": { "errors": [ { "error_key": "hire_date", "category": "invalid_attribute_value", "message": "Hire date is invalid" } ] }, "job_duplicate_title": { "errors": [ { "error_key": "title", "category": "invalid_attribute_value", "message": "Employee cannot have two jobs with the same title." } ] }, "i9_authorization_unneeded_document_params": { "errors": [ { "error_key": "expiration_date", "category": "invalid_attribute_value", "message": "For the submitted authorization status, expiration date is not allowed" }, { "error_key": "document_type", "category": "invalid_attribute_value", "message": "For the submitted authorization status, document type is not allowed" } ] }, "i9_authorization_not_self_onboarding": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee is not self-onboarding." } ] }, "i9_authorization_employee_already_signed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee has already signed the form." } ] }, "i9_employer_sign_invalid_params": { "errors": [ { "error_key": "signed_by_ip_address", "category": "invalid_attribute_value", "message": "Signed by IP address is invalid" }, { "error_key": "signer_title", "category": "invalid_attribute_value", "message": "Signer title is required" }, { "error_key": "agree", "category": "invalid_attribute_value", "message": "You must agree to sign electronically" }, { "error_key": "signature_text", "category": "invalid_attribute_value", "message": "Signature text is required" } ] }, "i9_employer_sign_employee_not_signed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee has not signed I-9" } ] }, "i9_employer_sign_already_signed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "I-9 has already been signed by the employer" } ] }, "i9_documents_already_signed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "I-9 cannot be updated as it has already been signed by the employer" } ] }, "i9_documents_invalid_params": { "errors": [ { "error_key": "documents", "category": "nested_errors", "metadata": { "document_type": "invalid_type" }, "errors": [ { "error_key": "document_type", "category": "invalid_attribute_value", "message": "Document type's value is not included in the list" }, { "error_key": "document_title", "category": "invalid_attribute_value", "message": "Document title's value is not included in the list" } ] } ] }, "i9_documents_not_array": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Parameter `documents` must be an array" } ] }, "company_benefit_missing_benefit_type": { "errors": [ { "error_key": "base", "category": "missing_parameter", "message": "benefit_type is required." } ] }, "company_benefit_invalid_benefit_type": { "errors": [ { "error_key": "benefit_type", "category": "invalid_attribute_value", "message": "Benefit type does not correspond with a supported benefit" } ] }, "company_benefit_missing_description": { "errors": [ { "error_key": "description", "category": "invalid_attribute_value", "message": "Description is required" } ] }, "company_benefit_cannot_disable": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Company benefit cannot be disabled while employees are still enrolled" } ] }, "company_benefit_cannot_change_type": { "errors": [ { "error_key": "benefit_type", "category": "invalid_attribute_value", "message": "The associated benefit cannot be changed" } ] }, "company_benefit_invalid_contribution_exclusions": { "errors": [ { "error_key": "contribution_exclusions", "category": "invalid_attribute_value", "message": "Expected contribution_exclusions array of hashes." } ] }, "employee_benefits_invalid_parameter": { "errors": [ { "error_key": "employee_benefits", "category": "invalid_parameter", "message": "Missing or invalid parameter 'employee_benefits'." } ] }, "time_off_activity_invalid_type": { "errors": [ { "error_key": "base", "category": "invalid_parameter", "message": "Expected one of: vacation, sick" } ] }, "employee_benefit_negative_company_contribution": { "errors": [ { "error_key": "company_contribution", "category": "invalid_attribute_value", "message": "Company contribution must be greater than or equal to 0" } ] }, "employee_benefit_active_requires_contribution_or_deduction": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "An active employee benefit must have either a company contribution or an employee deduction" } ] }, "employee_benefit_invalid_effective_date": { "errors": [ { "error_key": "effective_date", "category": "invalid_attribute_value", "message": "Effective date is not a valid date" } ] }, "employee_benefit_duplicate_type": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Employee cannot have more than one 401(k)" } ] }, "employee_benefit_invalid_limit_option": { "errors": [ { "error_key": "limit_option", "category": "invalid_attribute_value", "message": "Limit option must be one of \"Family\", \"Individual\"" } ] }, "employee_benefit_coverage_amount_only_for_gtl": { "errors": [ { "error_key": "coverage_amount", "category": "invalid_attribute_value", "message": "Coverage amount is only applicable for group term life employee benefit." } ] }, "employee_benefit_destroy_invalid": { "errors": [ { "error_key": "benefit_type", "category": "invalid_parameter", "message": "This application is not permitted to modify benefits of type 100 (Other (taxable))." } ] }, "company_benefit_has_employees": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "There are employees associated with this benefit, please remove these employees before deleting the benefit." } ] }, "company_benefit_partnered": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This benefit is managed by the partner and cannot be deleted." } ] }, "rehire_delete_already_effective": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Unable to delete the rehire that is already effective, please terminate the employee instead." } ] }, "rehire_not_terminated": { "errors": [ { "error_key": "effective_date", "category": "invalid_attribute_value", "message": "Cannot rehire if employee has not been terminated" } ] }, "rehire_missing_required_fields": { "errors": [ { "error_key": "effective_date", "category": "invalid_attribute_value", "message": "Effective date is required" }, { "error_key": "work_location_uuid", "category": "invalid_attribute_value", "message": "Work location not found" }, { "error_key": "file_new_hire_report", "category": "invalid_attribute_value", "message": "File new hire report is required" } ] }, "rehire_invalid_work_location": { "errors": [ { "error_key": "work_location_uuid", "category": "invalid_attribute_value", "message": "Work location not found" } ] }, "rehire_no_future_employment": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "The employee does not have any future employment, please rehire the employee first." } ] }, "earning_type_missing_name": { "errors": [ { "error_key": "name", "category": "invalid_attribute_value", "message": "Name is required" } ] }, "earning_type_duplicate_name": { "errors": [ { "error_key": "name", "category": "invalid_attribute_value", "message": "There is already an earning called Bonus" } ] }, "earning_type_invalid_category": { "errors": [ { "error_key": "category", "category": "invalid_attribute_value", "message": "Category is not valid" } ] }, "earning_type_included_in_overtime_pay_invalid_category": { "errors": [ { "error_key": "included_in_overtime_pay", "category": "invalid_attribute_value", "message": "Category must be 'Other' to set included_in_overtime_pay" } ] }, "earning_type_category_not_modifiable": { "errors": [ { "error_key": "category", "category": "invalid_attribute_value", "message": "Category is not modifiable" } ] }, "earning_type_included_in_overtime_pay_not_modifiable": { "errors": [ { "error_key": "included_in_overtime_pay", "category": "invalid_attribute_value", "message": "Included in overtime pay is not modifiable" } ] }, "department_duplicate_title": { "errors": [ { "error_key": "title", "category": "invalid_attribute_value", "message": "Department name has already been taken." } ] }, "department_has_active_members": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "You cannot delete a department that has active team members. Please remove them first." } ] }, "department_invalid_employees": { "errors": [ { "error_key": "employees", "category": "invalid_attribute_value", "message": "Employees must be valid" }, { "error_key": "contractors", "category": "invalid_attribute_value", "message": "Contractors must be valid" } ] }, "form_already_signed": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This form has already been signed" } ] }, "form_no_signature_required": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This form does not require a signature" } ] }, "form_invalid_ip_address": { "errors": [ { "error_key": "signed_by_ip_address", "category": "invalid_attribute_value", "message": "Signed by ip address is invalid" } ] }, "form_preparer_not_supported": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This form does not allow preparer information" } ] }, "invoice_period_invalid_format": { "errors": [ { "error_key": "base", "category": "invalid_parameter", "message": "Invalid invoice_period param format, should be 'YYYY-MM'" } ] }, "invoice_period_future": { "errors": [ { "error_key": "base", "category": "invalid_parameter", "message": "Invalid invoice_period param, cannot be a future invoice period" } ] }, "invoice_company_uuids_max_exceeded": { "errors": [ { "error_key": "base", "category": "invalid_parameter", "message": "Invalid company_uuids passed, max of 50" } ] }, "wire_in_request_invalid_date_sent": { "errors": [ { "error_key": "date_sent", "category": "invalid_attribute_value", "message": "Date sent must be a valid date" } ] }, "wire_in_request_missing_bank_name": { "errors": [ { "error_key": "bank_name", "category": "invalid_attribute_value", "message": "Bank name must be present" } ] }, "wire_in_request_invalid_amount_sent": { "errors": [ { "error_key": "amount_sent", "category": "invalid_attribute_value", "message": "Amount sent must be a number" } ] }, "wire_in_request_additional_notes_too_long": { "errors": [ { "error_key": "additional_notes", "category": "invalid_attribute_value", "message": "Additional notes must be less than 255 characters" } ] }, "wire_in_request_not_awaiting_funds": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Wire in request status must be awaiting funds" } ] }, "external_payroll_missing_check_date": { "errors": [ { "error_key": "check_date", "category": "invalid_attribute_value", "message": "Check date is required" } ] }, "external_payroll_missing_payment_period_dates": { "errors": [ { "error_key": "payment_period_start_date", "category": "invalid_attribute_value", "message": "Payment period start date is required" }, { "error_key": "payment_period_end_date", "category": "invalid_attribute_value", "message": "Payment period end date is required" } ] }, "external_payroll_net_pay_less_than_zero": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Net pay less than zero for one or more external payroll items" } ] }, "external_payroll_invalid_payroll_item": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Invalid payload or parameters" } ] }, "external_payrolls_locked": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "External Payrolls have already been finalized or a payroll has already been processed." } ] }, "employee_bank_account_destroy_invalid": { "errors": [ { "error_key": "base", "category": "invalid_attribute_value", "message": "Cannot delete this bank account." } ] }, "external_payroll_invalid_liability_selection": { "errors": [ { "error_key": "tax_id", "category": "invalid_attribute_value", "message": "Tax is required" } ] }, "invalid_tax_liability_selection": { "errors": [ { "error_key": "tax_id", "category": "invalid_attribute_value", "message": "Tax is required" } ] }, "external_payroll_invalid_tax_liability_selections": { "errors": [ { "error_key": "tax_id", "category": "invalid_attribute_value", "message": "Tax liability selections are not valid" } ] }, "member_portal_already_complete": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "Member has already complete member portal registration." } ] }, "member_portal_not_eligible": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This member is not eligible for a member portal invitation in their current onboarding status (admin_onboarding_incomplete). Invite the member to self-onboard before sending a member portal invitation." } ] }, "member_portal_member_info_incomplete_missing_start_date": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This member has not completed onboarding. Cannot proceed without member's job start date." } ] }, "member_portal_member_info_incomplete_missing_email": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This member has not completed onboarding. Cannot proceed without an email." } ] }, "member_portal_already_cancelled": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This invitation has already been cancelled." } ] }, "member_portal_not_cancellable": { "errors": [ { "error_key": "base", "category": "invalid_operation", "message": "This invitation is no longer cancellable." } ] } } }, "Entity-Error-Object": { "type": "object", "required": [ "error_key", "category" ], "properties": { "error_key": { "type": "string", "description": "Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error." }, "category": { "type": "string", "description": "Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration. If category is `nested_errors`, the object will contain a nested `errors` property with entity errors." }, "message": { "type": "string", "description": "Provides details about the error - generally this message can be surfaced to an end user." }, "metadata": { "type": "object", "description": "Contains relevant data to identify the resource in question when applicable. For example, to identify an entity `entity_type` and `entity_uuid` will be provided.", "oneOf": [ { "$ref": "#/components/schemas/Metadata-With-Multiple-Entities" }, { "$ref": "#/components/schemas/Metadata-With-One-Entity" } ] }, "errors": { "type": "array", "description": "Will only exist if category is `nested_errors`. It is possible to have multiple levels of nested errors.", "items": { "type": "object", "properties": { "error_key": { "type": "string", "description": "Specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error." }, "category": { "type": "string", "description": "Specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration. If category is `nested_errors`, the object will contain a nested `errors` property with entity errors." }, "message": { "type": "string", "description": "Provides details about the error - generally this message can be surfaced to an end user." }, "metadata": { "type": "object", "description": "Contains relevant data to identify the resource in question when applicable. For example, to identify an entity `entity_type` and `entity_uuid` will be provided." } } } } } }, "Metadata-With-One-Entity": { "type": "object", "description": "single entity", "additionalProperties": true, "properties": { "entity_type": { "type": "string", "description": "Name of the entity that the error corresponds to." }, "entity_uuid": { "type": "string", "description": "Unique identifier for the entity." }, "valid_from": { "type": [ "string", "null" ] }, "valid_up_to": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] } } }, "Metadata-With-Multiple-Entities": { "type": "object", "description": "multiple entities", "required": [ "entities" ], "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/Metadata-With-One-Entity" } } } }, "Payroll-Partner-Owned-Disbursement-Type": { "type": [ "boolean", "null" ], "description": "Will money movement for the payroll be performed by the partner rather than by Gusto?" }, "Payroll-Deadline-Type": { "type": "string", "format": "date-time", "description": "A timestamp that is the deadline for the payroll to be run in order for employees to be paid on time. If payroll has not been run by the deadline, a prepare request will update both the check date and deadline to reflect the soonest employees can be paid and the deadline by which the payroll must be run in order for said check date to be met.", "readOnly": true }, "Payroll-Check-Date-Type": { "type": "string", "description": "The date on which employees will be paid for the payroll.", "readOnly": true }, "Payroll-Processed-Type": { "type": "boolean", "description": "Whether or not the payroll has been successfully processed. Note that processed payrolls cannot be updated. Additionally, a payroll is not guaranteed to be processed just because the payroll deadline has passed. Late payrolls are not uncommon. Conversely, users may choose to run payroll before the payroll deadline.", "readOnly": true }, "Payroll-Processed-Date-Type": { "type": [ "string", "null" ], "description": "The date at which the payroll was processed. Null if the payroll isn't processed yet.", "readOnly": true }, "Payroll-Calculated-At-Type": { "type": [ "string", "null" ], "format": "date-time", "description": "A timestamp of the last valid payroll calculation. Null if there isn't a valid calculation.", "readOnly": true }, "Payroll-Payroll-Uuid-Type": { "type": "string", "description": "The UUID of the payroll.", "readOnly": true }, "Payroll-Company-Uuid-Type": { "type": "string", "description": "The UUID of the company for the payroll.", "readOnly": true }, "Payroll-Off-Cycle-Type": { "type": "boolean", "description": "Indicates whether the payroll is an off-cycle payroll", "readOnly": true }, "Off-Cycle-Reason-Type": { "anyOf": [ { "type": "string", "enum": [ "Adhoc", "Benefit reversal", "Bonus", "Correction", "Dismissed employee", "Hired employee", "Wage correction", "Tax reconciliation", "Reversal", "Disability insurance distribution", "Transition from old pay schedule" ] }, { "type": "null" } ], "description": "The off-cycle reason. Only included for off-cycle payrolls.", "readOnly": true }, "Auto-Pilot-Type": { "type": "boolean", "description": "Indicates whether the payroll has automatic payroll enabled", "readOnly": true }, "Payroll-External-Type": { "type": "boolean", "description": "Indicates whether the payroll is an external payroll", "readOnly": true }, "Payroll-Final-Termination-Payroll-Type": { "type": "boolean", "description": "Indicates whether the payroll is the final payroll for a terminated employee. Only included for off-cycle payrolls.", "readOnly": true }, "Payroll-Skip-Regular-Deductions-Type": { "type": [ "boolean", "null" ], "description": "Block regular deductions and contributions for this payroll. Only included for off-cycle payrolls.", "readOnly": true }, "Payroll-Withholding-Pay-Period-Type": { "description": "The payment schedule tax rate the payroll is based on. Only included for off-cycle payrolls.", "readOnly": true, "anyOf": [ { "type": "string", "enum": [ "Every week", "Every other week", "Twice per month", "Monthly", "Quarterly", "Semiannually", "Annually" ] }, { "type": "null" } ] }, "Payroll-Fixed-Withholding-Rate-Type": { "type": [ "boolean", "null" ], "description": "Enable taxes to be withheld at the IRS's required rate of 22% for federal income taxes. State income taxes will be taxed at the state's supplemental tax rate. Otherwise, we'll sum the entirety of the employee's wages and withhold taxes on the entire amount at the rate for regular wages. Only included for off-cycle payrolls.", "readOnly": true }, "Payroll-Pay-Period-Type": { "type": "object", "readOnly": true, "properties": { "start_date": { "type": [ "string", "null" ], "description": "The start date, inclusive, of the pay period.", "readOnly": true }, "end_date": { "type": [ "string", "null" ], "description": "The start date, inclusive, of the pay period.", "readOnly": true }, "pay_schedule_uuid": { "type": [ "string", "null" ], "description": "The UUID of the pay schedule for the payroll.", "readOnly": true } } }, "Payroll-Payroll-Status-Meta-Type": { "type": "object", "description": "Information about the payroll's status and expected dates", "properties": { "cancellable": { "type": "boolean", "description": "true if the payroll may be cancelled.", "readOnly": true }, "expected_check_date": { "type": "string", "description": "The date an employee will be paid if the payroll is submitted now.", "readOnly": true }, "initial_check_date": { "type": [ "string", "null" ], "description": "The normal check date for the associated pay period. Returns `null` for off-cycle payrolls (not meaningful for off-cycle).", "readOnly": true }, "expected_debit_time": { "type": "string", "description": "The time the employer's account will be debited if the payroll is submitted now.", "readOnly": true }, "payroll_late": { "type": [ "boolean", "null" ], "description": "expected_check_date > initial_check_date. Returns `null` for off-cycle payrolls (not meaningful for off-cycle).", "readOnly": true }, "initial_debit_cutoff_time": { "type": "string", "description": "Payroll must be submitted at or before this time to avoid late payroll.", "readOnly": true } } }, "Payroll-Employee-Compensations-Base-Type": { "type": "object", "properties": { "employee_uuid": { "type": "string", "description": "The UUID of the employee.", "readOnly": true }, "excluded": { "type": "boolean", "description": "This employee will be excluded (skipped) from payroll calculation and will not be paid for the payroll. Cancelling a payroll would reset all employees' excluded back to false.", "readOnly": true }, "first_name": { "type": [ "string", "null" ], "description": "The first name of the employee. Requires `employees:read` scope.", "readOnly": true }, "preferred_first_name": { "type": [ "string", "null" ], "description": "The preferred first name of the employee. Requires `employees:read` scope.", "readOnly": true }, "last_name": { "type": [ "string", "null" ], "description": "The last name of the employee. Requires `employees:read` scope.", "readOnly": true }, "gross_pay": { "type": [ "string", "null" ], "description": "The employee's gross pay (as a string-formatted decimal, e.g. \"1234.56\"), equal to regular wages + cash tips + payroll tips + any other additional earnings + `pay_adjustments`, excluding imputed income.", "readOnly": true }, "net_pay": { "type": [ "string", "null" ], "description": "The employee's net pay (as a string-formatted decimal, e.g. \"1234.56\"), equal to gross_pay - employee taxes - employee deductions or garnishments - cash tips. This value is only available for processed payrolls.", "readOnly": true }, "check_amount": { "type": [ "string", "null" ], "description": "The employee's check amount (as a string-formatted decimal, e.g. \"1234.56\"), equal to net_pay + reimbursements. This value is only available for processed payrolls.", "readOnly": true }, "payment_method": { "description": "The employee's compensation payment method. Is *only* `Historical` when retrieving external payrolls initially run outside of Gusto, then put into Gusto.", "anyOf": [ { "type": "string", "enum": [ "Direct Deposit", "Check", "Historical" ] }, { "type": "null" } ] }, "memo": { "type": [ "string", "null" ], "description": "Custom text that will be printed as a personal note to the employee on a paystub.", "readOnly": true }, "fixed_compensations": { "type": "array", "uniqueItems": false, "description": "An array of fixed compensations for the employee. Fixed compensations include tips and bonuses. On regular payrolls, reimbursements are sent via the dedicated `reimbursements` array instead. Off-cycle payrolls continue to include reimbursements in `fixed_compensations`. If this payroll has been processed, only fixed compensations with a value greater than 0.00 are returned. For an unprocessed payroll, all active fixed compensations are returned.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the compensation. This also serves as the unique, immutable identifier for this compensation." }, "amount": { "type": "string", "description": "The amount of the compensation for the pay period." }, "job_uuid": { "type": "string", "description": "The UUID of the job for the compensation.", "readOnly": true }, "breakdowns": { "type": "array", "uniqueItems": false, "description": "Per-workweek amounts for this compensation, one entry per workweek\noverlapping the pay period.\n", "items": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "The start date of the workweek." }, "end_date": { "type": "string", "format": "date", "description": "The end date of the workweek." }, "amount": { "type": "string", "format": "float", "description": "The dollar amount for this workweek." } } }, "readOnly": true } } } }, "hourly_compensations": { "type": "array", "uniqueItems": false, "description": "An array of hourly compensations for the employee. Hourly compensations include regular, overtime, and double overtime hours. If this payroll has been processed, only hourly compensations with a value greater than 0.00 are returned. For an unprocessed payroll, all active hourly compensations are returned.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the compensation. This also serves as the unique, immutable identifier for this compensation." }, "hours": { "type": "string", "description": "The number of hours to be compensated for this pay period." }, "amount": { "type": "string", "description": "The amount of the compensation. This field is only available after the payroll is calculated and cannot be used for updating hourly compensations." }, "job_uuid": { "type": "string", "description": "The UUID of the job for the compensation.", "readOnly": true }, "compensation_multiplier": { "type": "number", "description": "The amount multiplied by the base rate to calculate total compensation per hour worked.", "readOnly": true }, "flsa_status": { "type": "string", "description": "The FLSA Status of the employee's primary job compensation", "readOnly": true }, "breakdowns": { "type": "array", "uniqueItems": false, "description": "Per-workweek hours for this compensation, one entry per workweek\noverlapping the pay period.\n", "items": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "The start date of the workweek." }, "end_date": { "type": "string", "format": "date", "description": "The end date of the workweek." }, "hours": { "type": "string", "format": "float", "description": "The number of hours worked during this workweek." } } }, "readOnly": true } } } }, "paid_time_off": { "type": "array", "uniqueItems": false, "description": "An array of all paid time off the employee is eligible for this pay period.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the PTO. This also serves as the unique, immutable identifier for the PTO." }, "hours": { "type": "string", "description": "The hours of this PTO taken during the pay period." }, "amount": { "type": [ "string", "null" ], "description": "The dollar amount paid for this PTO entry during the pay period (as a string-formatted decimal, e.g. \"1234.56\"). Only available for processed payrolls.", "readOnly": true }, "final_payout_unused_hours_input": { "type": [ "string", "null" ], "description": "The outstanding hours paid upon termination. This field is only applicable for termination payrolls." }, "approved_request_hours": { "type": [ "string", "null" ], "description": "Total hours of approved time off requests overlapping this pay period for this time-off policy. Only populated on unprocessed (draft) payrolls; absent on processed payrolls. Read-only.\n", "readOnly": true } } } }, "reimbursements": { "type": "array", "uniqueItems": false, "description": "An array of reimbursements for the employee.", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The dollar amount of the reimbursement for the pay period." }, "description": { "type": [ "string", "null" ], "description": "The description of the reimbursement. Null for unnamed reimbursements." }, "uuid": { "type": [ "string", "null" ], "description": "The UUID of the reimbursement. Null for unnamed reimbursements. This field is only available for unprocessed payrolls.", "readOnly": true }, "recurring": { "type": "boolean", "description": "Whether the reimbursement is recurring. This field is only available for unprocessed payrolls.", "readOnly": true } }, "required": [ "amount", "description" ] } }, "custom_withholdings": { "type": "object", "description": "The one-time custom withholding overrides applied to this payroll for this employee.\n`federal` is null when no federal one-time override is set; `state` is an empty\narray when no state one-time overrides are set.\n", "properties": { "federal": { "type": [ "object", "null" ], "description": "Federal one-time custom withholding override applied to this payroll.", "properties": { "override_type": { "type": "string", "enum": [ "one_time" ], "description": "Override mode. Only `one_time` is currently exposed." }, "amount": { "type": "string", "description": "The amount that was withheld for this payroll." }, "amount_type": { "type": "string", "enum": [ "fixed", "percent" ], "description": "How to interpret the amount." } } }, "state": { "type": "array", "description": "State one-time custom withholding overrides applied to this payroll, one entry per state field.", "items": { "type": "object", "properties": { "employee_state_field_uuid": { "type": "string", "description": "The UUID of the EmployeeStateField this withholding applies to." }, "override_type": { "type": "string", "enum": [ "one_time" ], "description": "Override mode. Only `one_time` is currently exposed." }, "amount": { "type": "string", "description": "The amount that was withheld for this payroll." }, "amount_type": { "type": "string", "enum": [ "fixed", "percent" ], "description": "How to interpret the amount." } } } } } } } }, "Payroll-Unprocessed-Employee-Compensations-Type": { "allOf": [ { "$ref": "#/components/schemas/Payroll-Employee-Compensations-Base-Type" }, { "$ref": "#/components/schemas/Versionable" }, { "type": "object", "properties": { "version": { "description": "The current version of this employee compensation. This field is only available for prepared payrolls. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/api-fundamentals#optimistic-version-control) for information on how to use this field." } } } ] }, "Payroll-Payment-Speed-Changed-Type": { "type": "object", "description": "Only applicable when a payroll is moved to four day processing instead of fast ach.", "properties": { "original_check_date": { "type": "string", "description": "Original check date when fast ach applies.", "readOnly": true }, "current_check_date": { "type": "string", "description": "Current check date.", "readOnly": true }, "original_debit_date": { "type": "string", "description": "Original debit date when fast ach applies.", "readOnly": true }, "current_debit_date": { "type": "string", "description": "Current debit date.", "readOnly": true }, "reason": { "type": "string", "description": "The reason why the payroll is moved to four day.", "readOnly": true } } }, "Created-At-Type": { "type": "string", "format": "date-time", "description": "Datetime for when the resource was created.", "readOnly": true }, "Payroll-Processing-Request": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "description": "The status of the payroll processing request", "readOnly": true, "enum": [ "calculating", "calculate_success", "submitting", "submit_success", "processing_failed" ] }, "errors": { "description": "Errors that occurred during async payroll processing", "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Entity-Error-Object" } } } }, "Payroll-Fixed-Compensation-Types-Type": { "type": "array", "items": { "type": "object", "readOnly": true, "properties": { "name": { "description": "The name of an available type of fixed compensation.", "type": "string", "readOnly": true } } } }, "Payroll-Unprocessed": { "description": "An unprocessed payroll with employee compensations.", "x-examples": { "success_status": { "uuid": "4428f108-e46e-4ab6-ba20-03cea031cfc0", "employee_compensations": [], "payroll_uuid": "4428f108-e46e-4ab6-ba20-03cea031cfc0", "company_uuid": "42b5333b-ee39-493a-bf7e-f41f2bd67848", "payroll_status_meta": { "cancellable": false, "expected_check_date": "2025-06-17", "initial_check_date": "2025-06-17", "expected_debit_time": "2025-06-11T23:00:00Z", "payroll_late": false, "initial_debit_cutoff_time": "2025-06-11T23:00:00Z" }, "off_cycle": true, "auto_payroll": false, "off_cycle_reason": "Bonus", "withholding_pay_period": "Twice per month", "skip_regular_deductions": true, "fixed_withholding_rate": true, "final_termination_payroll": false, "processed": false, "processed_date": "", "calculated_at": "", "pay_period": { "start_date": "2025-06-10", "end_date": "2025-06-16", "pay_schedule_uuid": "" }, "check_date": "2025-06-17", "external": false, "payroll_deadline": "2025-06-11T23:00:00Z", "fixed_compensation_types": [ { "name": "Bonus" }, { "name": "Commission" }, { "name": "Paycheck Tips" }, { "name": "Cash Tips" }, { "name": "Correction Payment" }, { "name": "Reimbursement" } ], "created_at": "2025-06-11T19:40:52Z", "partner_owned_disbursement": "" } }, "type": "object", "properties": { "payroll_deadline": { "$ref": "#/components/schemas/Payroll-Deadline-Type" }, "check_date": { "$ref": "#/components/schemas/Payroll-Check-Date-Type" }, "processed": { "$ref": "#/components/schemas/Payroll-Processed-Type" }, "processed_date": { "$ref": "#/components/schemas/Payroll-Processed-Date-Type" }, "calculated_at": { "$ref": "#/components/schemas/Payroll-Calculated-At-Type" }, "uuid": { "$ref": "#/components/schemas/Payroll-Payroll-Uuid-Type" }, "payroll_uuid": { "$ref": "#/components/schemas/Payroll-Payroll-Uuid-Type" }, "company_uuid": { "$ref": "#/components/schemas/Payroll-Company-Uuid-Type" }, "off_cycle": { "$ref": "#/components/schemas/Payroll-Off-Cycle-Type" }, "off_cycle_reason": { "$ref": "#/components/schemas/Off-Cycle-Reason-Type" }, "auto_payroll": { "$ref": "#/components/schemas/Auto-Pilot-Type" }, "external": { "$ref": "#/components/schemas/Payroll-External-Type" }, "final_termination_payroll": { "$ref": "#/components/schemas/Payroll-Final-Termination-Payroll-Type" }, "withholding_pay_period": { "$ref": "#/components/schemas/Payroll-Withholding-Pay-Period-Type" }, "skip_regular_deductions": { "$ref": "#/components/schemas/Payroll-Skip-Regular-Deductions-Type" }, "fixed_withholding_rate": { "$ref": "#/components/schemas/Payroll-Fixed-Withholding-Rate-Type" }, "pay_period": { "$ref": "#/components/schemas/Payroll-Pay-Period-Type" }, "workweeks": { "type": [ "array", "null" ], "description": "The workweeks overlapping this payroll's pay period, one entry per workweek.\nNull when workweek boundaries can't be determined for this payroll (e.g. some\noff-cycle payrolls without a defined payment period).\n", "items": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "The start date of the workweek." }, "end_date": { "type": "string", "format": "date", "description": "The end date of the workweek." } } }, "readOnly": true }, "payroll_status_meta": { "$ref": "#/components/schemas/Payroll-Payroll-Status-Meta-Type" }, "employee_compensations": { "type": "array", "uniqueItems": false, "items": { "$ref": "#/components/schemas/Payroll-Unprocessed-Employee-Compensations-Type" } }, "payment_speed_changed": { "$ref": "#/components/schemas/Payroll-Payment-Speed-Changed-Type" }, "created_at": { "$ref": "#/components/schemas/Created-At-Type" }, "fixed_compensation_types": { "$ref": "#/components/schemas/Payroll-Fixed-Compensation-Types-Type" }, "processing_request": { "$ref": "#/components/schemas/Payroll-Processing-Request" }, "partner_owned_disbursement": { "$ref": "#/components/schemas/Payroll-Partner-Owned-Disbursement-Type" } } }, "Versionable": { "type": "object", "properties": { "version": { "type": "string", "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field." } } } }, "securitySchemes": { "CompanyAccessAuth": { "type": "http", "scheme": "bearer", "description": "Company-level authentication" } } }, "paths": { "/v1/companies/{company_id}/payrolls": { "post": { "summary": "Create an off-cycle payroll", "parameters": [ { "name": "X-Gusto-API-Version", "in": "header", "schema": { "type": "string", "enum": [ "2026-06-15" ], "default": "2026-06-15" }, "description": "Determines the date-based API version associated with your API call. If none is provided, your application's [minimum API version](https://docs.gusto.com/embedded-payroll/docs/api-versioning#minimum-api-version) is used." }, { "name": "company_id", "in": "path", "description": "The UUID of the company", "required": true, "schema": { "type": "string" } } ], "x-gusto-rswag": true, "operationId": "post-v1-companies-company_id-payrolls", "security": [ { "CompanyAccessAuth": [] } ], "description": "Creates a new, unprocessed, off-cycle payroll.\n\n## `off_cycle_reason`\nBy default:\n- External benefits and deductions will be included when the `off_cycle_reason` is set to `Correction`.\n- All benefits and deductions are blocked when the `off_cycle_reason` is set to `Bonus`.\n\nThese elections can be overridden with the `skip_regular_deductions` boolean.\n\nscope: `payrolls:run`", "tags": [ "Payrolls" ], "x-gusto-integration-type": [ "embedded" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "examples": { "success_status": { "value": { "$ref": "#/components/schemas/Payroll-Unprocessed/x-examples/success_status" } } }, "schema": { "$ref": "#/components/schemas/Payroll-Unprocessed" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "examples": { "not_found": { "value": { "$ref": "#/components/schemas/Not-Found-Error-Object/x-examples/not_found" } } }, "schema": { "$ref": "#/components/schemas/Not-Found-Error-Object" } } } }, "422": { "description": "Unprocessable Entity\n\nThis may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.\n", "content": { "application/json": { "examples": { "invalid_attribute": { "value": { "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/invalid_attribute" } }, "employee_uuids_required": { "value": { "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object/x-examples/employee_uuids_required" } } }, "schema": { "$ref": "#/components/schemas/Unprocessable-Entity-Error-Object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "off_cycle", "off_cycle_reason", "start_date", "end_date" ], "properties": { "off_cycle": { "type": "boolean", "description": "Whether it is an off cycle payroll." }, "off_cycle_reason": { "type": "string", "enum": [ "Bonus", "Correction", "Adhoc", "Dismissed employee", "Transition from old pay schedule" ], "description": "An off cycle payroll reason. Select one from the following list." }, "start_date": { "type": "string", "format": "date", "description": "Pay period start date." }, "end_date": { "type": "string", "format": "date", "description": "Pay period end date." }, "pay_schedule_uuid": { "description": "A pay schedule is required for transition from old pay schedule payroll to identify the matching transition pay period.", "type": "string" }, "employee_uuids": { "description": "A list of employee UUIDs to include on the payroll. At least one UUID is required for non-termination off-cycle payrolls.", "type": "array", "minItems": 1, "items": { "type": "string" } }, "check_date": { "type": "string", "format": "date", "description": "Payment date." }, "withholding_pay_period": { "description": "The payment schedule tax rate the payroll is based on.", "type": "string", "enum": [ "Every week", "Every other week", "Twice per month", "Monthly", "Quarterly", "Semiannually", "Annually" ] }, "skip_regular_deductions": { "description": "Block regular deductions and contributions for this payroll.", "type": "boolean" }, "fixed_withholding_rate": { "description": "Enable taxes to be withheld at the IRS's required rate of 22% for federal income taxes. State income taxes will be taxed at the state's supplemental tax rate. Otherwise, we'll sum the entirety of the employee's wages and withhold taxes on the entire amount at the rate for regular wages.", "type": "boolean" }, "is_check_only_payroll": { "description": "When true, all employees in the payroll will be paid by check and the check date can be set to today or any future business day (rather than requiring ACH lead time). Payment methods cannot be changed on check-only payrolls.", "type": "boolean" } } } } } } } } } } ```