Best Practices

​

Introduction

The API is designed to work best in an event-driven architecture: whenever something happens in your system (e.g., a new entity is created or updated, or a process is completed), your system notifies the API so that both systems stay in sync in near real-time. This approach minimizes delays, avoids redundant processing, and ensures data consistency across both platforms. At Cobee by Pluxee, we understand, however, that not all clients can implement event-driven integrations. In some cases, integration may rely on scheduled tasks or bulk processing (e.g., exporting CSV files once a day). While this model can work, it requires careful handling to avoid unnecessary API calls and performance overhead. This document focuses on providing enough information to help you optimize performance when integrating with Cobee by Pluxee.

​

Risks of inefficient usage

Using the API in a non-optimized way may lead to:

• Thousands of redundant requests
• Increased latency and processing times
• A higher chance of hitting rate limits

For example, resolving identifiers one by one for every row in a bulk file will often double the number of requests compared to a grouped approach. The following best practices are designed to help you avoid these issues.

​

Best Practices

​

Reuse and cache the Authorization Token

The JWT obtained during authentication has a validity period. To optimize performance and reduce unnecessary authentication requests, reuse the token until it expires. Only then should you request a new token.

​

Filter and limit data

When making requests to list resources, use the available query parameters to filter and limit the data returned. When you need to look up entities, leverage the API’s filtering capabilities to narrow down results. For example, when searching for a company by its legal ID, use the legal_id query parameter as shown on List Companies Endpoint Query Parameters section.

​

Maintain ID Mapping

The most efficient way to interact with the API is to store the identifiers returned by Cobee in your own system. By maintaining this mapping between your internal entities and Cobee’s identifiers, you avoid repeated lookups and minimize the number of API calls required for day-to-day operations. This also makes your integration more robust over time, since each entity can be referenced directly. Entities that expose Cobee IDs include:

• Companies (companyId)
• Employees (employeeId)
• Payroll Cycles (payrollCycleId)

​

When ID Mapping is not possible

Some systems may not be able to persist Cobee by Pluxee identifiers. In these cases, the following can help reduce the impact:

• Use filtering capabilities Whenever you need to look up an entity, use the API’s filtering capabilities to narrow down results. This reduces the amount of data transferred and speeds up lookups.
• Group and organize API calls efficiently Some data relationships imply dependencies (e.g., an employee belongs to a company). If you need to resolve identifiers dynamically, fetching the company ID for each employee individually would effectively double the number of requests. A more efficient approach is to group operations by company, so that only one request per distinct company is needed, instead of one per employee.
• Cache short-lived results Even if you cannot store IDs permanently, consider caching them temporarily during the processing of a bulk file or scheduled job. This avoids repeated lookups within the same execution.
• Plan for rate limits Without ID storage, the number of lookups increases. To avoid hitting API rate limits, design your integration to batch requests, use retries with backoff, and process data in controlled chunks.

​

Rate Limiting

The API enforces rate limits to ensure fair usage and platform stability. If you cannot store IDs and rely heavily on filtering or repeated lookups, you are more likely to hit these limits. Following the practices above—storing Cobee IDs when possible, using filters effectively, and grouping calls—will significantly reduce this risk and improve integration performance. Check the Rate Limits documentation.