Company onboarding via API
Set up a company on Check’s platform programmatically for seamless payroll integration.
Overview
This doc is a prescriptive guide on how to programmatically set up a company on Check’s platform, from initial company creation → ready for payroll.
The guide skews to a technical audience, and is meant to lead an engineer and product manager through the series of endpoints needed for integration to complete an end-to-end setup.
Goals and assumptions
This guide assumes that you have all of the information needed to set up a company on Check already in your system, or available to you. It does not cover extracting data from a previous payroll provider, and does not touch on any of Check’s setup products like Full Service Setup or Self-Service Setup.
To programmatically set up a company to run payroll on Check’s system via the API, follow these steps, along with the required objects and properties. This guide outlines the sequence of API requests necessary to ensure the company is correctly configured to run payroll.
1. Create a Company
Create the company using the /companies endpoint. You will need to include the following minimum required properties:
legal_name
address(includingline1,city,state, andpostal_code)
Example Request:
curl -X POST <https://sandbox.checkhq.com/companies> \\\\
-H 'Content-Type: application/json' \\\\
-H 'Authorization: Bearer <API_KEY>' \\\\
-d '{
"address": {
"line1": "20 W 34th St",
"postal_code": "10001",
"city": "New York",
"state": "NY"
},
"start_date": "2020-05-20",
"trade_name": "Good Web Design",
"legal_name": "Good Web Design, Inc."
}'
Save the returned id for future operations.
2. Create Workplaces
Each company can have multiple workplaces representing different physical locations. Use the /workplaces endpoint to add all workplaces where any employees were paid year to date, with the following minimum properties:
company(theidfrom the previous step)
address(similar to the company’s address properties)
3. Configure Company Tax Parameters
Update the company’s tax parameters using the /company_tax_parameters endpoint. This step requires mapping the company’s tax settings to Check’s tax parameters.
It is in this step that you will set up the company’s tax information in Check, including:
- Federal Employer Identification Number
- SUI rates
- State tax IDs
- And more…
An important exercise will be ensuring that you have a mapping from these fields in your system to those in Check’s Tax Parameters API.
4. Create a Company Bank Account
Set up a bank account to fund payroll using the /bank_accounts endpoint with one of the following properties:
raw_bank_account(includesaccount_number,routing_number, etc.)
plaid_bank_account(if using Plaid for bank verification). Note: if you already have Plaid access to your customer’s bank account, you can exchange your access token for a Plaid Processor Token and pass that to Check instead.
5. Create Employees and/or Contractors
The next step is to create all of the employees and contractors who work for this company. Note: it is critical to add active and terminated employees from the current calendar year, as Check will take responsibility for filing tax forms such as the W-2 and 1099 for all employees of the business at year end.
Employees and contractors are created using separate endpoints (/employees and /contractors), with different required fields. The common properties include:
Employees:
company(company ID)
last_name
dob
start_date
residence(address details)
ssn
workplaces(list of workplace IDs)primary_workplaceshould also be set for each employee. This will dictate the employee’s primary SUI state in the case that they are multi-state.
Contractors:
company
last_name
type(businessorindividual)
einorssn
payment_method
address
6. Configure Employee Tax Parameters and Elections
Use the /employee_tax_parameters and /employee_tax_elections endpoints to update employee-specific tax settings. This step includes setting parameters such as state and federal withholdings.
7. Configure Employee Benefits and Deductions
Set up employee benefits and deductions through the /benefits and /post_tax_deduction endpoints, respectively.
8. Create External Payrolls
In order to ensure that Check has an accurate picture of YTD wages and taxes paid out by the company YTD — which is critical to ensure both accurate calculation of go-forward payrolls and accurate tax filing at the end of the quarter and year — all historical payrolls that have been run year to date must be uploaded into Check. This should be done using the External Payrolls API.
You should create one payroll per closed quarter (period_start / period_end should be the first and last day of the quarter.
Earnings should be mapped to workplaces, which is a requirement for accurate taxation and filing.
For open quarters (meaning quarters that are still in progress), you should create one payroll per pay period.
9. Final Setup Steps
Use the /start_implementation endpoint to mark the company as fully set up and submit for review by Check's activation team.
10. Obtain Signatures of Filing and Debit Authorization
Once the migration is complete, the employer must sign the following forms before they are able to run payroll:
- Terms of Service
- Debit Authorization
- Filing Authorization
These authorization forms allow Check to debit the employer’s bank account, and to file and pay taxes on their behalf. The Signatory Agreements and Filing Authorization components render these forms for employers to sign.
Use the /components/signatory_agreements and /components/filing_authorization endpoints to generate component links, which can be sent directly to the employer or embedded in your product.
11. Company Goes Live
Once all configurations are complete, verify the implementation status. The company is considered live when implementation_status is marked as complete. The company is now ready to run payroll.
Last updated on June 30, 2024