Onboard Status

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_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.

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 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",
    "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:

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

{
    "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.
• workplaces: The employee does not have a primary workplace. 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.

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:

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

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

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:

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

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

{
    "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",
    ],
}