Payroll Blockers
If there is a payroll blocker throughout the process, you will receive a payroll_blocker
category 422 error. You will be able to get the reason for the error using the metadata
.
{
"errors": [
{
"error_key": "base",
"category": "payroll_blocker",
"message": "Company or employee address could not be verified. Please ensure all addresses are valid.",
"metadata": {
"key": "geocode_error"
}
}
]
}
You can also view the payroll blockers for a given company using the GET companies/{company_uuid}/payrolls/blockers
endpoint.
curl --request GET \
--url https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/blockers \
--header 'X-Gusto-API-Version: 2023-09-01' \
--header 'accept: application/json'
const fetch = require('node-fetch');
const url = 'https://api.gusto-demo.com/v1/companies/company_uuid/payrolls/blockers';
const options = {method: 'GET', headers: {accept: 'application/json'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
It is possible for company onboarding status response to be
onboarding_completed: true
but for certain steps to becompleted: false
if making updates post-onboarding. New forms may be generated and require signature.
Below is a list of all possible metadata key
values and how to resolve them.
Key | Message | How to Resolve |
---|---|---|
eftps_in_error | We could not make payments to the Electronic Federal Tax Payment System. | Please contact support. |
geocode_error | Company or employee address could not be verified. Please ensure all addresses are valid. | Confirm the company and employee addresses are all valid. |
geocode_needed | Company or employee address verification is missing. Please ensure all addresses are entered correctly. | Confirm the company and employee addresses are completed. |
missing_signatory | A signatory who is authorized to sign documents on behalf of your company is required. | Confirm that the company has a signatory. |
invalid_signatory | Please ensure that the identity verification of the company signatory is successful. | Use the GET companies/{company_uuid}/signatories endpoint to check the identity_verification_status . |
pay_schedule_setup_not_complete | Some employees don’t have a pay schedule set up yet. Please complete this step to run payroll. | Verify that all employees have a pay schedule. |
needs_approval | Company needs to be approved to run payroll. | We are reviewing the company onboarding information, wait for the company.approved webhook to continue. |
soft_suspended | Company is placed in a "soft" suspension state and requires missing/incorrect information to be corrected. | Company is placed in a "soft" suspension state and requires missing/incorrect information to be corrected. Validate the state tax information is completed and correct. If state tax information is correct, please contact support. |
suspended | Company is suspended and cannot run payroll. | Please contact support if you believe this is an error. |
wc_pending_approval | Worker's compensation policy needs to be accepted. | The worker’s compensation process has not been completed and may require more information. Please contact support. |
pending_payroll_review | Payroll is blocked. We are reviewing payroll information in your account. Please contact support if you believe this is an error. | Please contact support if you believe this is an error. |
needs_onboarding | Company must complete all onboarding requirements in order to run payroll. | Confirm that all company onboarding steps are completed. |
missing_addresses | Company must add addresses in order to run payroll. | Missing company onboarding requirement. Confirm that company addresses have been added. |
missing_federal_tax_setup | Company must complete federal tax setup in order to run payroll. | Missing company onboarding requirement. Confirm that company federal tax setup has been completed. |
missing_industry_selection | Company must complete industry selection in order to run payroll. | Missing company onboarding requirement. Confirm that a company industry has been selected. |
missing_bank_info | Company must have a bank account in order to run payroll. | Missing company onboarding requirement. Confirm that a company bank account has been added. |
missing_employee_setup | Company must add employees in order to run payroll. | Missing company onboarding requirement. Confirm that the company has employees added. |
missing_state_tax_setup | Company must complete state tax setup in order to run payroll. | Missing company onboarding requirement. Confirm that the company has completed state tax setup. |
missing_pay_schedule | Company must have a pay schedule in order to run payroll. | Missing company onboarding requirement. Confirm that the company has added a pay schedule. |
missing_forms | Company forms must be signed in order to run payroll. | Missing company onboarding requirement. Confirm that all company forms have been signed. |
missing_bank_verification | Company bank account must be verified in order to run payroll. | Missing company onboarding requirement. Confirm that the company bank account has been verified. |
pending_recovery_case | Company has an open recovery case that must be resolved in order to unblock payroll. | Use the POST v1/companies/{company_uuid}/flows endpoint to create a company_recovery_cases flow . You may view all recovery cases for a company and initiate a redebit. Click [here] for more information on initiating a redebit for a recovery case. |
pending_information_request | Company has an open information request that must be submitted and approved in order to unblock payroll. | Use the POST v1/companies/{company_uuid}/flows endpoint to create a company_information_requests flow. You may view all information requests for a company and respond to them. This submitted information will be reviewed by our risk team; please wait for the notification.information_request.resolved webhook to continue. |
contractor_only_company | Company is set to contractor_only and cannot run payroll. Update the company and complete additional onboarding steps to process payroll. | Use the PUT v1/companies/{company_uuid} endpoint to update the company, then fetch any new onboarding steps using theGET v1/companies/{company_uuid}/onboarding_status endpoint . Complete new onboarding steps and then run the payroll. |
Updated 2 months ago