📘 Sample JSON Responses

Understanding FlexPay's JSON Payloads for Seamless Integration

In any API integration, understanding the exact structure and content of JSON responses is crucial. FlexPay’s JSON responses follow consistent patterns that you’ll quickly recognize if you’ve already worked through the ➕ Add Employee and 💵 Submit Payroll endpoints. These JSON payloads provide not only the raw data you need but also metadata and status indicators that ensure your application can respond intelligently.

When you receive a response from FlexPay’s API, it generally includes the following key elements: a status code, a message indicating success or failure, and a data object that holds the requested resource or action result. The data itself may contain nested objects, arrays, timestamps, and identifiers that you’ll need to map to your internal models or UI components. Recognizing these structures upfront makes error handling and debugging far simpler.

For example, the response from a successful employee creation will include an employee_id that you can reference in subsequent calls like 💵 Submit Payroll. Similarly, the payroll submission response contains a payroll_id along with status field indicating whether the payroll is pending, processing, or completed.

Figure 1. Typical JSON Response Structure

FlexPay also maintains strict consistency in field naming and data types across all endpoints, which helps when building reusable components in your front-end or server-side logic. Fields such as created_at and updated_at Timestamps use ISO 8601 format for easy parsing.

Figure 2. Example JSON Snippit for Employee Creation in FlexPay

When errors occur, like submitting invalid payroll data or requesting a non-existent paystub, the JSON response includes clear error codes and descriptive messages. This feature is invaluable for building user-friendly error states and logs in your application. Handling these gracefully can be achieved by referencing our previous sections, such as 🔐 Authentication & Rate Limits, which detail how to manage API errors and retries.

⚠️ Warning: Always check the status and error fields before processing data to avoid corrupting your records or triggering faulty UI updates. See 🔐 Authentication & Rate Limits for handling rate-limit responses properly.

Common JSON Response Examples

Employee Creation (POST /employees)

jsonCopyEdit{
  "status": "success",
  "message": "Employee successfully created",
  "data": {
    "employee_id": "EMP12345",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[e-mail]",
    "created_at": "2025-05-25T14:23:55Z"
  }
}

This response confirms the new employee’s record creation and provides an identifier you will use in payroll submissions and paystub retrievals. If you refer back to the ➕ Add Employee section, you’ll see how this payload is returned after a successful POST request.

Payroll Submission (POST /payroll)

jsonCopyEdit{
  "status": "processing",
  "message": "Payroll is being processed",
  "data": {
    "payroll_id": "PR67890",
    "employee_ids": ["EMP12345", "EMP67890"],
    "submitted_at": "2025-05-26T08:15:30Z"
  }
}

Here, the payroll is accepted but is still undergoing processing. The presence of an array of employee IDs indicates batch processing capability. This directly connects to our earlier 💵 Submit Payroll details on how to interpret payroll states.

Paystub Retrieval (GET /paystubs/{paystub_id})

jsonCopyEdit{
  "status": "success",
  "message": "Paystub retrieved",
  "data": {
    "paystub_id": "PS54321",
    "employee_id": "EMP12345",
    "gross_pay": 2000.00,
    "taxes": 300.00,
    "net_pay": 1700.00,
    "issued_date": "2025-05-27"
  }
}

This typical payload provides the paystub details needed to display or archive employee compensation information.

---

🛠️ Tips for Working with JSON Responses

• Use JSON schema validation in your integration to catch malformed or unexpected payloads early.

• Always log raw JSON responses in development for easier troubleshooting.

• Normalize timestamps to your app’s timezone only at the presentation layer.

• Cache frequently requested data like employee info to reduce API calls and improve performance.

• When working with nested objects, write helper functions to extract and map data cleanly.

⚠️ Warning: Be mindful of sensitive employee data such as email addresses and pay amounts. Ensure your app enforces strict access controls and data encryption in transit and at rest.

---

✅ Summary

The Sample JSON Responses you’ve reviewed here form the backbone of your FlexPay integration. By carefully examining the structure and contents of these responses, you can ensure that your application interprets data correctly and handles both success and error cases gracefully.

Keep in mind the importance of validating responses, respecting sensitive data, and handling asynchronous states like payroll processing. These best practices will improve your app’s stability and user trust.

---

🔄 What’s Next: Use Cases and Recipes

Now that you're done with the API documentation section of Flexpay, it's time to dive into some use cases! These will teach you all about the basics of integration and things like "Paying Contractors Only", "Syncing with Time Tracking", and "Re-Running Failed Payroll".

Ready to learn how to do integrations? Click "Next" or here to learn how to integrate with QuickBooks.

🟢 Remember: You can always reference this section’s JSON examples to validate your paystub retrieval logic and build consistent UI displays.