🧾 Retrieve Paystub Data

Endpoint: GET /paystubs Used to fetch paystub records for a given employee or payroll period. Each record includes gross pay, deductions, net pay, benefits, and the corresponding pay cycle.

---

Introduction

Once you’ve submitted payroll using the 💵 Submit Payroll endpoint, individual paystubs become available for employees included in that payroll batch. These paystubs serve as detailed records of each employee’s earnings, deductions, and payment information for a given period.

The GET /paystubs Endpoint lets you retrieve this data either by employee ID, payroll batch ID, or date range. If you're unfamiliar with how employees are added or payroll is submitted, we strongly recommend reviewing ➕ Add Employee and 💵 Submit Payroll before continuing. These sections explain where to get valid employee IDs and payroll batch references.

In this section, we’ll walk through several retrieval scenarios and explore how to interpret the returned data structure. We’ll also cover common edge cases, such as what to do if your response is empty or missing expected data.

---

Filtering and Query Options

You can request paystub data in multiple ways depending on the context of your application. A typical call might look like this:

bashCopyEditGET /paystubs?employee_id=EMP123

This retrieves all available pay stubs for employee EMP123. Alternatively, you can request all pay stubs from a specific payroll run:

bashCopyEditGET /paystubs?payroll_id=PR456

You may also choose to filter by a date range using from and to parameters:

vbnetCopyEditGET /paystubs?from=2024-01-01&to=2024-01-31

Each of these methods supports pagination and filtering to avoid large or excessive payloads.

---

Figure 1. A Standard Two Employee Payroll Submission

Above is an example of how the standard two-employee payroll submission works in the FlexPay app.

When the request is successful, FlexPay returns a JSON object containing one or more paystub records. Each record includes key values like gross and net pay, breakdowns of deductions, and issue dates.

If pagination is required, a next_page_token will also be included in the response, so you can continue fetching results in batches.

---

Understanding the Response Format

Each paystub contains nested sections, including:

• employee_id

• payroll_id

• period_start / period_end

• gross_pay and net_pay

• deductions object (with taxes, benefits, etc.)

• issued_date

Here’s what a typical JSON response might look like:

jsonCopyEdit{
  "paystubs": [
    {
      "employee_id": "EMP123",
      "payroll_id": "PR456",
      "period_start": "2024-01-01",
      "period_end": "2024-01-15",
      "gross_pay": 2000,
      "net_pay": 1800,
      "deductions": {
        "taxes": 150,
        "benefits": 50
      },
      "issued_date": "2024-01-16"
    }
  ],
  "next_page_token": "abc123"
}

Figure 2. Example paystub JSON response with gross-to-net breakdown

---

Common Pitfalls and Edge Cases

If your query returns no results, there are a few likely causes:

• The employee ID is invalid or not yet associated with a submitted payroll

• The payroll run did not complete successfully (see 💵 Submit Payroll for validation checks)

• Your date range does not overlap with any processed pay periods

• The pay stubs haven’t been generated yet (there may be a short delay after submission)

In many of these cases, simply adjusting your query can resolve the issue. For example, removing or relaxing filters will return more data. Double-checking employee IDs from the ➕ Add Employee section ensures you’re querying valid records.

⚠️ Warning: Relying only on date ranges without anchoring your search to employee_id or payroll_id can increase load and lead to incomplete results in multi-tenant systems. Use identifiers whenever possible.

Also, note that data is read-only — you cannot edit, regenerate, or revoke paystubs from this endpoint. If something’s wrong, you’ll need to cancel and re-run the payroll using the proper tools.

---

Tips for Implementation

• Always store employee IDs returned from ➕ Add Employee locally, so you can retrieve pay stubs without additional lookups

• Display key paystub info (gross, net, issued date) in a user dashboard to reduce support requests

• Use next_page_token to lazily load large datasets for reporting or internal admin portals

✅ Summary

This section explained how to access paystub data via GET /paystubs. You learned how to filter by employee, batch ID, or date range — and how to handle missing or paginated data. With this information, you can build an employee-facing pay history UI or plug into internal reporting workflows.

---

🔄 What’s Next: 📥 Webhooks Overview

Retrieving pay stubs manually is useful, but wouldn’t it be better to get notified as soon as new ones are available? That’s where webhooks come in. In the next section, we’ll walk through how to set up secure, real-time webhooks so your app can:

• Detect when a paystub is generated

• Respond automatically to payroll events

• Eliminate the need to constantly poll the API

📣 Hint: FlexPay will attempt to deliver each webhook event up to three times. Acknowledge delivery with a 200 OK or your system may be marked unreliable. We'll walk through all of this next.

➡️ Continue to 📥 Webhooks Overview