Direct integration endpoints

August 1, 2020
Ian Zapolsky

Head of Product

by 
Ian Zapolsky

Today we’re excited to announce the launch of several new features: the Bank Account API, the SSN API, the Employee Withholdings API, and the onboard_status field on the employee resource. These features are designed to support developers who opt not to use Check Onboard for employees, and instead want to build their own onboarding flows.

Bank Account API

The Bank Account API provides a way to supply Check with bank account information that you’ve already collected through another provider, such as Plaid.

You can create bank account resources like so:

Bank Accounts can be associated with companies or employees. When a bank account is created for an employee or a company, it will show up on the employee or company object. For example:

We limit the number of Bank Accounts that can be associated with a company or employee to one. If you create a new Bank Account for a company or employee that already has an existing one, the previous account will be automatically removed and replaced with the new account.

We do not perform bank account verification aside from basic validation on the account and routing numbers. As a result, this API should not be used to create Bank Accounts with account and routing numbers that were manually keyed in by customers.

In order for an employee’s pay to be sent to their linked bank account, you will need to configure their “payment_method_preference” like so:

The possible values of “payment_method_preference” are:

  • null: the initial value
  • manual: used to specify that an employee wishes to be paid via paper check from their employer
  • direct_deposit: used to specify that an employee has authorized their pay to get sent to a bank account

This information is used to populate the default PayrollItem.payment_method for the employee if not explicitly set.

SSN API

We've added the ability to securely configure an employee's Social Security Number (SSN) directly on the employee resource. You can set an employee's SSN at time of creation using the write-only ssn parameter like so:

You can also modify this value on an existing employee:

The employee resource will surface information about an employee’s current SSN through the new read-only field ssn_last_four in the response body:

(Note: If an employee cannot obtain an SSN because of their residency status, the “ssn” field can be used to store their Individual Tax Identification Number).

Employee Withholdings API

Employees have a list of necessary forms to complete before we consider them onboarded. The list is determined by their residence address and workplace addresses. You can query the status of an employee’s onboard forms like so:

Example response body:

You can use submitted_at to determine whether or not a form is completed. With the relevant form IDs in hand, you can determine which parameters are necessary to submit by querying:

Example (abbreviated) response body:

With the above parameters in hand, you can then create a submission for the employee like so:

Example request body:

Example response body:

Once every form in an employee’s form list has a recorded submission the employee’s withholding forms are considered completely configured.

onboard_status

To query whether a particular employee is completely onboarded you can look at the new onboard_status field on the employee resource. The possible values of this field are completed or needs_attention. An employee’s onboard_status will start off with a value of needs_attention. In order to transition to a status of completed, you will need to:

  1. Set a SSN on the employee
  2. Configure the employee’s withholdings
  3. a. Either set the employee’s payment_method_preference to manual
    b. Or set the employee’s payment_method_preference to direct_deposit and link a bank account to the employee

Once you complete all three steps the employee is considered onboarded, and their onboard_status will transition to completed.

More from the Check blog

March 14, 2024

Hitting New Milestones: Check's 2023 Year End and 2024 Year Start Super Bowl

What's your industry's Super Bowl? For embedded payroll, year-end is crunch time! Find out how Check navigated the busiest season for embedded payroll, new product launches from Check, and why 2024 is poised for innovation in the industry. Learn how Check can streamline your payroll process!

Read more >

Equal Pay Day 2024: How pay transparency can close the gap

March 12, 2024 is Equal Pay Day in the United States to highlight the significant gender pay gap that still exists. Our COO Corinne Beksha talks about how her personal experience has impacted her view on pay transparency, especially in her role here at Check.

Read more >