---
updatedAt: 2025-11-07T12:44:25.000Z
agentTools:
projectIndex: https://docs.checkhq.com/llms.txt
---
# Onboard Status
See what's blocking payroll for your companies, employees, and contractors
Check `company`, `employee`, and `contractor` objects all expose an `onboard` object to provide insight into the status of each entity and the onboarding steps needed before you can run payroll for that entity.
Each entity's `onboard` object contains the `status` field. `status` can have the following values:
* `completed`: The company, employee, or contractor is onboarded and ready to process payroll.
* `needs_attention`: The company, employee, or contractor has not completed one or more onboarding steps, and running payroll may produce different calculations than intended.
* `blocking`: The company, employee, or contractor is missing critical information that will prevent us from running payroll.
There are various reasons why `status` may not be `completed` that differ for companies, employees, and contractors which depend on the necessary steps remaining to run payroll for that entity. The `onboard` object includes `blocking_steps` and `remaining_steps` arrays, which contain strings of the respective steps preventing the entity from being in a `completed` state. The `blocking_steps` array includes all remaining steps that put the entity into a `blocking` state. The `remaining_steps` array includes all remaining steps, both blocking and non-blocking. If only non-blocking steps remain (e.g. the `blocking_steps` array is empty), the entity's `status` will be `needs_attention`. If an entity is `completed`, both arrays will be empty.
Here is an example of the `onboard` object for a `completed` entity:
```json Completed onboard object
{
"status": "completed",
"blocking_steps": [],
"remaining_steps": [],
}
```
There are also different reasons as to why each remaining step may not be complete. These reasons are essential pieces of information to help provide actionable guidance for your users. For each remaining step, the `onboard` object will have an array field that holds each of the remaining substeps needed for that step to be complete.
Here is an example of the `onboard` object for a company that still needs to submit their debit authorization.
```json Blocking onboard object
{
"status": "blocking",
"blocking_steps": [
"bank_account"
],
"remaining_steps": [
"bank_account"
],
"bank_account": [
"bank_account_debit_authorization_submitted",
],
}
```
This company's `status` is `blocking`, and from examining the `blocking_steps` field, you can see that the `bank_account` step is the remaining blocking step. On inspecting the `bank_account` field, you can see that the `bank_account_debit_authorization_submitted` substep is the reason why, and you will be able to direct your user to complete this substep.
The list of `blocking_steps`, `remaining_steps`, and the corresponding substeps vary for companies, employees, and contractors.
## Onboard Status for Companies
Companies can be in a `blocking` state for three different reasons:
* `bank_account`: The company has not completed linking their bank account to Check and authorizing Check to make debits from this account.
* `setup_parameters`: The company has not finished setting up their taxes for all applicable jurisdictions.
* `filing_authorization`: The company has not submitted filing authorization forms for all applicable jurisdictions.
If a company is in a `blocking` state, the company will be unable to run payroll.
**Note:** In our Sandbox environment, we have relaxed some of our validations so that companies in a `blocking` are permitted to run payrolls. We made this decision in order to remove friction from testing the end-to-end payroll flow.
Companies can be in a `needs_attention` state for two different reasons:
* `setup_parameters`: The company has marked that they have "applied for" certain setup parameters. When setup parameters have been marked as applied for, they do not block payroll, but should be completed as soon as the company receives the parameter.
* `filing_authorization`: Some necessary state filing authorization forms require submission of one or more setup parameters before they are able to be submitted. If the form is blocked by a setup parameter, then it will be in the `needs_attention` state, which doesn't block payroll. After all required setup parameters have been submitted, the form will be in the `blocking` state until it has been submitted.
If a company is in a `needs_attention` state, the company will still be able to run payroll, but the missing information should be provided as soon as possible.
The `bank_account` step is considered incomplete until the company finishes all three of these sub-steps:
* `bank_account_exists`: The company must create a bank account in the Check system.
* `bank_account_verified`: The company must verify their bank account through Plaid.
* `bank_account_debit_authorization_submitted`: The company must submit authorization allowing Check to withdraw funds from their linked bank account.
If the `setup_parameters` step is blocking due to a jurisdiction that has not been set up, the `setup_parameters` substep array will contain information corresponding to the jurisdictions that still need to be set up. Here is an example object for the federal jurisdiction:
```json Federal jurisdiction object
{
"id": "jur_NvIot3gvbIitui4Vmy9Z",
"name": "Federal",
"status": "blocking",
}
```
If a company still has not completed the `filing_authorization` step for any required jurisdiction, the `filing_authorization` substeps array contains a similar object corresponding to the required forms. Here is an example object for the Federal Form 8655:
```json Federal Form 8655 object
{
"id": "frm_ozhx2ezrVsd2k2ScL7HU",
"name": "Federal Form 8655",
"status": "blocking",
}
```
Here is an example of a company's `onboard` object when it is blocking for all three steps, with remaining tax setup and filing authorization required in both Federal and New York jurisdictions:
```json Company onboard object
{
"status": "blocking",
"blocking_steps": [
"bank_account",
"setup_parameters",
"filing_authorization",
],
"remaining_steps": [
"bank_account",
"setup_parameters",
"filing_authorization",
],
"bank_account": [
"bank_account_exists",
"bank_account_verified",
"bank_account_debit_authorization_submitted",
],
"setup_parameters": [
{
"id": "jur_NvIot3gvbIitui4Vmy9Z",
"name": "Federal",
"status": "blocking",
},
{
"id": "jur_87N4QWPZ38kDSvkqAI7D",
"name": "New York",
"status": "blocking",
},
],
"filing_authorization": [
{
"id": "frm_ozhx2ezrVsd2k2ScL7HU",
"name": "Federal Form 8655",
"status": "blocking",
},
{
"id": "frm_Iee3dIFvT1uBUYJ4PG7z",
"name": "New York TR-2000",
"status": "blocking",
},
{
"id": "frm_Y43LpYf60wEf3bCaN9Rn",
"name": "New York TR-579-WT",
"status": "blocking",
},
],
}
```
## Onboard Status for Employees
Employees can be in a `blocking` state for four different reasons:
* `company_defined_attributes`: The employee's employer has not submitted the required information for the employee. For more information on company-defined attributes, see [this guide](https://docs.checkhq.com/docs/collecting-employee-information-from-employers).
* `workplaces`: The employee does not have a primary workplace. Primary workplace affects which taxes are calculated, especially for employees who live and work across multiple states. If the employee does not have a primary workplace, the `workplaces` substep array will contain the `primary_workplace_set` substep.
* `withholdings`: The employee has not configured withholding parameters in all applicable, blocking jurisdictions. Currently, the only jurisdiction with blocking withholding parameters is Indiana, where the Indiana residence county and principal employment county are both required to run payroll.
* `employee_details`: The employee does not have a `start_date`, `dob`, or `residence` field. They can set a `dob` and `residence` via Employee Onboard, and their employer submits their `start_date`.
If an employee is in a `blocking` state, the employee's company will be unable to include that employee on a payroll.
**Note:** In our Sandbox environment, we have relaxed some of our validations so that employees in a `blocking` may be included on payrolls. We made this decision in order to remove friction from testing the end-to-end payroll flow.
Employees can be in a `needs_attention` state for three different reasons:
* `ssn`: The employee has not submitted their SSN or Individual Taxpayer Identification Number (ITIN) if they do not have an SSN. If the employee has not submitted their SSN or ITIN, the `ssn` substep array will contain both `ssn_submitted` and `ssn_validated` substep. If the employee has submitted their SSN or ITIN, but it has found to be invalid, the `ssn` substep array will contain `ssn_validated` as a remaining step.
* `withholdings`: The employee has not configured withholding parameters in all applicable jurisdictions. If these parameters are not complete, payroll still can be run, and Check will use the parameter's default values, which may affect the amount that is withheld from the employee's pay.
* `payment_method`: The employee has not set their payment method preference and will need to be paid manually (by cash or paper check).
* `company_defined_attributes`: The employee's employer has not submitted optional information for the employee.
If an employee is in a `needs_attention` state, the employee's company will be able to include the employee when running payroll, but the missing information should be provided as soon as possible.
If the employee's employer has not submitted either the required or optional company defined attributes, the `company_defined_attributes` substep array will contain information corresponding to the jurisdictions that ask for this information. If the employee has not set up withholdings, the `withholdings` substep array will contain similar information for corresponding jurisdictions without setup. Here is an example of an object corresponding to the Federal jurisdiction that might be in either array:
```json Federal jurisdiction object
{
"id": "jur_kSO0VneVfdx5TDDQ9Xnp",
"name": "Federal",
"status": "needs_attention",
}
```
The `payment_method` step can be incomplete if the employee has neither chosen to be paid manually or set up their bank account. The `payment_method` substep array will contain the following substeps:
* `payment_method_preference_set`: The employee has not chosen to either be paid manually or via direct deposit.
* `bank_account_exists`: The employee's bank account has not been created in the Check system.
* `bank_account_verified`: The employee's bank account has not been verified by Plaid.
Here is an example of an employee's `onboard` object when it is blocking for all steps, with remaining withholdings required in both Federal and New York jurisdictions and remaining company defined attributes required federally:
```json Employee onboard object
{
"status": "blocking",
"blocking_steps": [
"company_defined_attributes",
"workplaces"
],
"remaining_steps": [
"ssn",
"company_defined_attributes",
"workplaces",
"withholdings",
"payment_method"
],
"ssn": [
"ssn_submitted",
"ssn_validated"
],
"payment_method": [
"payment_method_preference_set",
"bank_account_exists",
"bank_account_verified",
],
"company_defined_attributes": [
{
"id": "jur_kSO0VneVfdx5TDDQ9Xnp",
"name": "Federal",
"status": "blocking",
},
],
"withholdings": [
{
"id": "jur_kSO0VneVfdx5TDDQ9Xnp",
"name": "Federal",
"status": "needs_attention",
},
{
"id": "jur_CUlTApePRnDFn9bPVCQE",
"name": "New York",
"status": "needs_attention",
},
],
"workplaces": [
"primary_workplace_set"
],
"employee_details": [
"dob",
"start_date",
"residence"
]
}
```
## Onboard Status for Contractors
Contractors can be in a `blocking` state for four different reasons:
* `type`: The contractor has not indicated whether they will be contracting as an `individual` or a `business`. If the employee has not submitted their contracting type, the `type` substep array will contain the `type_submitted` substep.
* `ein`: The contractor has indicated that they will be contracting as a `business` and has not submitted their Federal EIN. If the employee has not submitted their EIN, the `ein` substep array will contain the `ein_submitted` substep.
* `address`: The contractor has not provided an address yet. The `address` substep array will contain the `address_submitted` substep until they do so.
If a contractor is in a `blocking` state, the contractor's company will be unable to include that employee on a payroll.
**Note:** In our Sandbox environment, we have relaxed some of our validations so that contractors in a `blocking` may be included on payrolls. We made this decision in order to remove friction from testing the end-to-end payroll flow.
Contractors can be in a `needs_attention` state for two different reasons:
* `ssn`: The contractor has indicated that they will be contracting as an `individual` and has not submitted their SSN or Individual Taxpayer Identification Number (ITIN) if they do not have an SSN. If the contractor has not submitted their SSN or ITIN, the `ssn` substep array will contain both the `ssn_submitted` and `ssn_validated` substep. If the employee has submitted their SSN or ITIN, but it has found to be invalid, the `ssn` substep array will contain `ssn_validated` as a remaining step.
* `payment_method`: The contractor has not set their payment method preference and will need to be paid manually (by cash or paper check).
The `payment_method` substep array will contain the following substeps:
* `payment_method_preference_set`: The contractor has not chosen to either be paid manually or via direct deposit.
* `bank_account_exists`: The contractor's bank account has not been created in the Check system.
* `bank_account_verified`: The contractor's bank account has not been verified by Plaid.
If a contractor is in a `needs_attention` state, the contractor's company will be able to include the contractor when running payroll, but the missing information should be provided as soon as possible.
Here is an example of a contractor's `onboard` object when it is `blocking` because the contractor has not submitted the `type` they will be contracting as:
```json Contractor onboard object
{
"status": "blocking",
"blocking_steps": [
"type",
],
"remaining_steps": [
"type",
"payment_method",
],
"type": [
"type_submitted",
],
"payment_method": [
"payment_method_preference_set",
"bank_account_exists",
"bank_account_verified",
],
}
```
Once the contractor has submitted their type, the contractor will still be `blocking` if missing an EIN or `needs_attention` if missing an SSN, and the corresponding identification substep will appear. Here is what the `onboard` object might look like for a `blocking` `business` contractor:
```json Business contractor onboard object
{
"status": "blocking",
"blocking_steps": [
"ein",
],
"remaining_steps": [
"ein",
"payment_method",
],
"ein": [
"ein_submitted",
],
"payment_method": [
"payment_method_preference_set",
"bank_account_exists",
"bank_account_verified",
],
}
```
Here is what the `onboard` object might look like for a `needs_attention` `individual` contractor:
```json Individual contractor onboard object
{
"status": "needs_attention",
"blocking_steps": [],
"remaining_steps": [
"ssn",
"payment_method",
],
"ssn": [
"ssn_submitted",
"ssn_validated",
],
"payment_method": [
"payment_method_preference_set",
"bank_account_exists",
"bank_account_verified",
],
}
```