Quickstart

This guide will demonstrate how to create Companies, Workplaces, Employees, and Payrolls, which are the required steps for employees to get paid reliably and on time.

Set up a test environment (Postman)

To make it easy to follow along we've created this Postman collection.

To use the collection, click "Run in Postman" above to download it to your local machine.

Next select the "Check" environment and set the Current Value for the apiKey variable to your personal Check api key. If there is no "Check" environment present, a new one will need to be created following these steps Postman - Create Environment. Name this environment "Check", and create two variables in this environment: 'apiUrl' with a "Current Value" of "https://sandbox.checkhq.com" and 'apiKey' with a value of your personal Check api key.

1. Create a company

The first action is to create a company, the employer that is paying employees. Each company is a separate tax entity to tax agencies and has one federal Employer Identification Number (EIN).

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."
  }'

You should store at least the returned company ID for future interactions with the Check API.

2. Create a workplace

In order to properly calculate taxes for an employee, Check needs to know the physical location where they do their work. Let's create some workplaces associated with our new company where we can assign those employees.

curl -X POST \
  https://sandbox.checkhq.com/workplaces \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    "company": "<COMPANY_ID>",
    "address": {
      "line1": "175 Varick St",
      "line2": "2nd Floor",
      "postal_code": "10014",
      "city": "New York",
      "state": "NY"
    }
  }'

You should store at least the returned workplace ID for future interactions with the Check API.

3. Create a company bank account

For a company to run payroll through Check, a business bank account from which the payroll will be funded needs to be linked. We will create employees next, but first, let's create a bank account associated with our new company that we can use to fund payroll.

curl -X POST \
  https://sandbox.checkhq.com/bank_accounts \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    "company": "<COMPANY_ID>",
    "raw_bank_account": {
      "account_number": "123456789",
      "routing_number": "026009593",
      "type": "depository",
      "subtype": "checking"
    }
  }'

4. Create employees

Creating an employee is very similar to creating a company. You will make an API request to create an employee entity in Check's systems.

curl -X POST \
  https://sandbox.checkhq.com/employees \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    "first_name": "Bob",
    "last_name": "Smith",
    "company": "<COMPANY_ID>",
    "workplaces": ["<WORKPLACE_ID>"],
    "start_date": "2019-03-01",
    "dob": "1975-11-28",
    "residence": {
      "line1": "123 Main St.",
      "postal_code": "11201",
      "city": "Brooklyn",
      "state": "NY",
      "country": "US"
    }
  }'

You should store at least the returned employee ID for future interactions with the Check API.

5. Present draft payroll entity for approval

You can generate payrolls when your company needs to pay its employees. You should show these to the company for approval. The period start and end dates are inclusive. For payrolls paid via direct deposit, Check ensures that the payday is far enough in the future to allow for all fund movement to complete. For this example, you should set the payday to a date returned by the /paydays endpoint. See the endpoint documentation for more details on what constitutes a valid direct-deposit payday.

curl -X POST \
  https://sandbox.checkhq.com/payrolls \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    "company": "<COMPANY_ID>",
    "period_start": "<YYYY-MM-DD>",
    "period_end": "<YYYY-MM-DD>",
    "payday": "<YYYY-MM-DD, non-bank holiday weekday>",
    "items": [
      {
        "employee": "<EMPLOYEE_ID>",
        "earnings": [
          {
            "type": "hourly",
            "workplace": "<WORKPLACE_ID>",
            "amount": "390.00",
            "hours": 40
          },
          {
            "type": "cash_tips",
            "workplace": "<WORKPLACE_ID>",
            "amount": "10.00"
          }
        ]
      }
    ]
  }'

Note that several fields in the response are null—they will be populated when payroll is approved. After adding payroll items, you can generate a payroll preview, which calculates net amounts and withholdings for all pay using the gross pay and laws applicable on payday. This calculation takes some time and is ephemeral. The calculations will only be persisted upon approval.

curl -X GET \
  'https://sandbox.checkhq.com/payrolls/<PAYROLL_ID>/preview' \
  -H 'Authorization: Bearer <API_KEY>'

Once a company has reviewed its payroll, it can approve the payroll. No further updates to payroll items are allowed after payroll has been approved.

curl -X POST \
  'https://sandbox.checkhq.com/payrolls/<PAYROLL_ID>/approve' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>'

6. Generate paystubs

Check also provides the means to generate paystubs for employees both as a rendered PDF and as a JSON object. Because state regulations generally require that all information in the paystub JSON response be rendered and the paystub be printable, Check recommends directly rendering a singular paystub to PDF to satisfy this requirement.

For more information, see Generating Paystubs in the Check Guides.

To return a Check-designed paystub as a PDF, make a GET call to the /paystubs endpoint with the HTTP header Accept: application/pdf. Check will return a fully rendered paystub for the employee:

GET /employees/<employee_id>/paystubs/<payroll_id>

What's Next

If you've made it this far you are well on your way to incorporating payroll into your product. As a next step we suggest browsing our API Reference. Still have questions? Feel free to shoot us an email.