The Check API Developer Hub

Welcome to the Check API developer hub. You'll find comprehensive guides and documentation to help you start working with Check API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Quickstart

Securely and reliably integrate payroll into your product.

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.

Note: bank account linking is not required for development in sandbox environments.

Set up a test environment (Postman)

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

Run in PostmanRun in Postman

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"
    },
    "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. We will create employees next, but first, 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 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.

4. 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>'

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.

Updated 5 days ago

Quickstart


Securely and reliably integrate payroll into your product.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.