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.

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.
`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 the`GET v1/companies/{company_uuid}/onboarding_status` endpoint . Complete new onboarding steps and then run the payroll.