Rippling

Rippling

This connector reads and updates Rippling through its REST API (https://rest.ripplingapis.com): workers and users, the org structure (departments, teams, work locations, levels, titles, employment types, job codes), custom fields, compensation, leave (types, balances, requests), supergroups and time entries.

Personal data: workers, users and compensations hold personal and pay data (names, private emails, phone numbers, home addresses, date of birth, gender, salary). Ask only for the fields the task needs, do not copy them into other systems without a reason, and give the token only the scopes the team uses.

Setup (5 minutes)

1. In Rippling open Developer > API credentials (https://app.rippling.com/api-tokens/tokens) and click New API token. You need the permission Create and manage API Tokens.
2. Name the token and select its scopes. The token can only reach data that both its scopes and the owner's permission profile allow. Pick what you use:
   • companies.read (required, the install check), workers.read, users.read, departments.read, teams.read, work-locations.read, levels.read, titles.read, employment-types.read, job-codes.read, custom-fields.read, supergroups.read.
   • compensations.read only if the agent should see pay.
   • leave-types.read, leave-balances.read, leave-requests.read (and leave-requests.read-write to file or approve leave).
   • time-entries.read (and time-entries.read-write to record time; needs Rippling Time).
   • departments.read-write, teams.read-write, work-locations.read-write, draft-hires.read-write for the matching writes.
3. Copy the token at once (it is shown only once) into RIPPLING_API_TOKEN. rippling_list_companies is the install check.
4. Requests run as the token's owner. A token is revoked when it stays unused for 30 days or when its owner is terminated; prefer an owner whose access is stable.

Workflow

• Company: rippling_list_companies.
• People: rippling_list_workers (filter by status, work_email, user_id, created_at, updated_at) and rippling_get_worker; a worker is the employment record, its user_id points to the login identity read with rippling_list_users and rippling_get_user. Pass expand (e.g. user,manager,department) to embed related objects in one call. Pay: rippling_list_compensations and rippling_get_compensation (the worker's compensation_id). Custom field definitions: rippling_list_custom_fields; values come with expand=custom_fields on workers.
• Org structure: rippling_list_departments, rippling_get_department, rippling_list_teams, rippling_get_team, rippling_list_work_locations, rippling_get_work_location, rippling_list_levels, rippling_get_level, rippling_list_titles, rippling_list_employment_types, rippling_list_job_codes.
• Groups: rippling_list_supergroups, rippling_get_supergroup, rippling_list_supergroup_members.
• Leave: rippling_list_leave_types, rippling_list_leave_balances (filter worker_id eq '...'), rippling_get_leave_balance, rippling_list_leave_requests (e.g. status eq 'PENDING'), rippling_get_leave_request. To book leave use rippling_create_leave_request; to approve, reject or cancel use rippling_update_leave_request with status.
• Time: rippling_list_time_entries, rippling_get_time_entry, rippling_create_time_entry (send an idempotency_key so a retry cannot create a duplicate), rippling_update_time_entry.
• Org changes: rippling_create_department, rippling_update_department, rippling_create_team, rippling_update_team, rippling_create_work_location, rippling_update_work_location.
• Hiring: rippling_create_draft_hires creates up to five draft hires that go through Rippling's review and approval before anyone is hired.

Switched off at install: rippling_delete_team and rippling_delete_time_entry; they cannot be undone, so an admin switches them on when the team needs them.

Filters: filter takes an OData-style expression on the fields each tool names: status eq 'ACTIVE', updated_at ge 2026-01-01T00:00:00, status in ('HIRED','ACCEPTED'), combined with and / or. Quote strings with single quotes. At most 64 nodes per filter.

Reading the answers

• Lists answer { "results": [...], "next_link": "..." }. Ids are 24-character hex strings.
• Dates are YYYY-MM-DD, timestamps ISO 8601 with offset. Money is { "currency_type": "USD", "value": 120000 } in major units.
• A field the token may not see is null and named in __meta.redacted_fields with the reason; an expanded object can also be null for that reason. Check scopes and the owner's permissions before concluding a value is empty.
• Worker status: INIT, HIRED, ACCEPTED, ACTIVE, TERMINATED.

Paging: default 50, limit up to 100. When next_link is not null, call again with cursor set to the cursor value inside next_link; stop when next_link is null.

Limits and errors: 600 requests per 10 seconds per endpoint and token, then 429 (wait and retry). 400 means a bad filter, an unexpandable field or limit over 100; 401 a revoked or wrong token; 403 a missing scope or permission; 404 an unknown id.