Bulk GET Requests

When a specific set of resources need to be requested from Check’s API, it is possible to provide the resource IDs to the list endpoint via the id query parameter. For example, one can fetch the details for a specified set of employees via the id query parameter by calling GET /employees?id=emp_aaa111&id=emp_bbb222&id=emp_ccc333&id=ddd444. Leveraging this feature reduces the number of Check API calls a client needs to make, improving performance. This is especially important for large datasets.

When the number of requested resources exceeds the page limit, the response will be paginated as documented in the pagination guide.

If a provided ID references a resource that does not exist, this will be indicated by the resource’s absence in the response.

There is no hard limit on the number of IDs supported per request, but each ID will increase the time it takes to receive a response.

Supported Resources

Bulk GET requests are currently supported for the following resources:

Example: Fetching all employees on a payroll

For example, consider the case of fetching all employees on a payroll. The requests below show the API requests involved, and the code block is an example implementation in JavaScript.

API Requests

GET /payrolls/pay_abc123

{
  "id": "pay_abc123",
  "items": [
    {
      "id": "itm_pqngIDA674QGlxaq3FCE",
      "payroll": "pay_lpeGFBOknAdXfSArMMnB",
      "employee": "emp_aaa111",
      "net_pay": "123.45",
      ...
    },
    {
      "id": "itm_ZSyIVUmBkr8aKEMj9JS2",
      "payroll": "pay_lpeGFBOknAdXfSArMMnB",
      "employee": "emp_bbb222",
      "net_pay": "678.90",
      ...
    },
    {
      "id": "itm_GkUmHOh4FUWNvW7RQ1p0",
      "payroll": "pay_lpeGFBOknAdXfSArMMnB",
      "employee": "emp_ccc333",
      "net_pay": "987.65",
      ...
    },
    {
      "id": "itm_cmmDLIYJEPNv7r1WICDS",
      "payroll": "pay_lpeGFBOknAdXfSArMMnB",
      "employee": "emp_ddd444",
      "net_pay": "432.10",
      ...
    }
  ],
  ...
}

To fetch the employees of this payroll, the bulk behavior of /employees can be used:

GET /employees?id=emp_aaa111&id=emp_bbb222&id=emp_ccc333&id=ddd444

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "emp_aaa111",
      "first_name": "First",
      "last_name": "Employee",
      ...
    },
    {
      "id": "emp_bbb222",
      "first_name": "Second",
      "last_name": "Employee",
      ...
    },
    {
      "id": "emp_ccc333",
      "first_name": "Third",
      "last_name": "Employee",
      ...
    },
    {
      "id": "emp_ddd444",
      "first_name": "Fourth",
      "last_name": "Employee",
      ...
    }
  ]
}

Sample implementation

This sample JavaScript implementation shows how an API client could obtain all employees on a given payroll.

import fetch from "node-fetch";
import qs from "qs";

const apiKey = process.env.API_KEY;
const baseUrl = "https://sandbox.checkhq.com";
const payrollId = "pay_abc123";
const fetchOptions = {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
};

async function main() {
  const payroll = await fetch(`${baseUrl}/payrolls/${payrollId}`, fetchOptions)
    .then((response) => response.json());

  // Gather an array of all employee IDs on the payroll.
  const employeeIds = payroll.items.map((item) => item.employee);
  
  // Request a page of employees.
  const queryParams = qs.stringify({ id: employeeIds }, { arrayFormat: "repeat" });
  let response = await fetch(`${baseUrl}/employees?${queryParams}`, fetchOptions)
    .then((response) => response.json());

  let employees = response.results;

  // Iterate through all additional pages.
  while (response.next) {
    response = await fetch(response.next, fetchOptions)
      .then((response) => response.json());

    employees = employees.concat(response.results);
  }

  // Transform the array of employees into an object keyed by the employee IDs.
  const employeesById = employees.reduce(
    (agg, employee) => ({ ...agg, [employee.id]: employee }),
    {}
  );

  // Present the information sourced from the payroll and the employees.
  console.table(
    payroll.items.map((item) => ({
      "First Name": employeesById[item.employee].first_name,
      "Last Name": employeesById[item.employee].last_name,
      "Net Pay": item.net_pay,
    }))
  );
}

main();