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:

{
    "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.

{
    "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_authorizations: The company has not submitted filing authorization forms for all applicable jurisdictions.

The bank_account step can be incomplete if the company has not completed all three of the following substeps:

  • bank_account_exists: The bank account has not been created in the Check system.
  • bank_account_verified: The bank account has not been verified by Plaid.
  • bank_account_debit_authorization_submitted: The company has not submitted their debit authorization to permit Check to debit from the 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:

{
    "id": "jur_NvIot3gvbIitui4Vmy9Z",
    "name": "Federal",
}

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:

{
    "id": "frm_ozhx2ezrVsd2k2ScL7HU",
    "name": "Federal Form 8655",
}

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:

{
    "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",  
        },
        {
            "id": "jur_87N4QWPZ38kDSvkqAI7D",
            "name": "New York",  
        },     
    ],
    "filing_authorization": [
        {
            "id": "frm_ozhx2ezrVsd2k2ScL7HU",
            "name": "Federal Form 8655",  
        },
        {
            "id": "frm_Iee3dIFvT1uBUYJ4PG7z",
            "name": "New York TR-2000",  
        },    
        {
            "id": "frm_Y43LpYf60wEf3bCaN9Rn",
            "name": "New York TR-579-WT",  
        },
    ],
}

Onboard Status for Employees

Employees can be in a blocking state for two 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 the ssn_submitted substep.
  • 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.

Employees can be in a needs_attention state for three different reasons:

  • withholdings: The employee has not configured withholdings in all applicable jurisdictions.
  • 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 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:

{
    "id": "jur_kSO0VneVfdx5TDDQ9Xnp",
    "name": "Federal",
}

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:

{
    "status": "blocking",
    "blocking_steps": [
        "ssn",
        "company_defined_attributes",
    ],
    "remaining_steps": [
        "ssn",
        "company_defined_attributes",
        "withholdings",
        "payment_method",
    ],
    "ssn": [
        "ssn_submitted",
    ],
    "payment_method": [
        "payment_method_preference_set",
        "bank_account_exists",
        "bank_account_verified",
    ],
    "company_defined_attributes": [
        {
            "id": "jur_kSO0VneVfdx5TDDQ9Xnp",
            "name": "Federal",  
        },
    ],
    "withholdings": [
        {
            "id": "jur_kSO0VneVfdx5TDDQ9Xnp",
            "name": "Federal",  
        },
        {
            "id": "jur_CUlTApePRnDFn9bPVCQE",
            "name": "New York",  
        },  
    ],
}

Onboard Status for Contractors

Contractors can be in a blocking state for three 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.
  • 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 the ssn_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.

Contractors can be in a needs_attention state if they have not completed the payment_method step, in which case they 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.

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:

{
    "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, and the corresponding identification substep will appear. Here is what the onboard object might look like for a blocking business contractor:

{
    "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 blocking individual contractor:

{
    "status": "blocking",
    "blocking_steps": [
        "ssn",
    ],
    "remaining_steps": [
        "ssn",
        "payment_method",
    ],
    "ssn": [
        "ssn_submitted",
    ],
    "payment_method": [
        "payment_method_preference_set",
        "bank_account_exists",
        "bank_account_verified",
    ],
}

Did this page help you?