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 be completed: 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.

KeyMessageHow to Resolve
eftps_in_errorWe could not make payments to the Electronic Federal Tax Payment System.Please contact support.
geocode_errorCompany or employee address could not be verified. Please ensure all addresses are valid.Confirm the company and employee addresses are all valid.
geocode_neededCompany or employee address verification is missing. Please ensure all addresses are entered correctly.Confirm the company and employee addresses are completed.
missing_signatoryA signatory who is authorized to sign documents on behalf of your company is required.Confirm that the company has a signatory.
invalid_signatoryPlease 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_completeSome 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_approvalCompany needs to be approved to run payroll.We are reviewing the company onboarding information, wait for the company.approved webhook to continue.
soft_suspendedCompany 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.
suspendedCompany is suspended and cannot run payroll.Please contact support if you believe this is an error.
wc_pending_approvalWorker'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_reviewPayroll 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_onboardingCompany must complete all onboarding requirements in order to run payroll.Confirm that all company onboarding steps are completed.
missing_addressesCompany must add addresses in order to run payroll.Missing company onboarding requirement.

Confirm that company addresses have been added.
missing_federal_tax_setupCompany 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_selectionCompany must complete industry selection in order to run payroll.Missing company onboarding requirement.

Confirm that a company industry has been selected.
missing_bank_infoCompany 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_setupCompany must add employees in order to run payroll.Missing company onboarding requirement.

Confirm that the company has employees added.
missing_state_tax_setupCompany 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_scheduleCompany must have a pay schedule in order to run payroll.Missing company onboarding requirement.

Confirm that the company has added a pay schedule.
missing_formsCompany forms must be signed in order to run payroll.Missing company onboarding requirement.

Confirm that all company forms have been signed.
missing_bank_verificationCompany 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_caseCompany 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_requestCompany 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_companyCompany 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.