Introduction to the Company Eligibles API — purpose, main flows, and key concepts.
Company Eligibles API
The Company Eligibles API lets HR systems control who has access to TotalPass benefits. Through it, you can add, remove, and transfer employees in bulk — and verify in real time whether a specific employee is currently eligible.
Context
Built for HR systems and ERPs, this API removes the need to manage employee eligibility manually through the TotalPass dashboard. Instead, your system handles the entire lifecycle automatically: onboarding new hires, offboarding terminations, and transferring employees between entities.
How it works
The API has two main flows:
Managing eligible employees — send a bulk request and receive an operation_id back immediately. Your system then checks GET /operations/{id} periodically until the job finishes.
Checking eligibility — query whether one or more employee documents are currently active. These endpoints respond immediately and do not modify any data.
All endpoints require a Bearer token obtained via POST /api/v1/login. Tokens last 24 hours and can be silently renewed using a refresh token — no credentials needed again.
Core Concepts
- Company Group — your organization's account on TotalPass. It groups one or more companies and owns the list of eligible employees.
- Eligible Employee — an employee linked to a company within your group. Only eligible employees can access TotalPass benefits.
- Company — a specific entity (identified by CNPJ or similar) within a company group. Employees are always tied to a company, not directly to the group.
- Operation — a record that tracks a bulk job (
bulk_create,bulk_delete, orbulk_transfer) and the result of each individual employee in that request.
Available Operations
| Category | What you can do |
|---|---|
| Authentication | Obtain, renew, and revoke access tokens |
| Eligibility | Check whether one or more employees are currently eligible |
| Eligibles | Add, remove, or transfer employees in bulk |
| Operations | Track the progress and results of bulk jobs |
| Company Groups | Retrieve your group's configuration and company list |
Benefits
- Automation — keep TotalPass in sync with your HR system without manual intervention.
- Auditability — every bulk job records the outcome per employee, including error details, making it easy to identify and retry failures.
- Real-time eligibility checks — confirm an employee is active before granting access to benefits.
- Scalability — process up to 200 employees per request without blocking your system.
Additional Information
- Your credentials (
identifierandauth_token) are provided during onboarding. Reach out to your TotalPass integration representative if you do not have them. - Each bulk request supports up to 200 employees.
- Refresh tokens are one-time use. If the same token is used twice, all active sessions for your company group are revoked immediately as a security measure.
- The login and refresh endpoints allow up to 10 requests per minute per IP address.
- Submitting a duplicate bulk operation returns
422 Unprocessable Content. Use thesourcefield to tag requests with your system's identifier and make duplicates easier to trace.
Environments
| Environment | Base URL |
|---|---|
| Production | https://company-eligibles-api.totalpass.com |
Contact
For questions or help with your integration, reach out to TotalPass support: