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: truebut for certain steps to becompleted: falseif 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.The signatory verification is successful if "identity_verification_status": "Pass" is returned. | 
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. | 
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 9 months ago