Connect Rippling

Connect Rippling so joiners, leavers, job and team changes, and pay changes reach Flowstate without anyone typing them in again. The forecast and budgets then work from the people you employ today.

You need access to integrations. Ask your Flowstate admin. First decide whether Rippling is where people changes are made: see Get your people data into Flowstate.

How it connects

Flowstate reads your people from Rippling’s API, using an API token you create in Rippling. Use a scheduled sync for Rippling. Rippling sends people webhooks only to apps listed in its App Shop, not to tokens a customer creates, so there are no events to react to.

What you need from Rippling

• A Rippling admin with Manage the API Tokens app or Create and manage API Tokens.
• A permission profile that covers The entire company for the person who creates the token. A token sees only what its creator can see, so a manager’s token sees only their reports.
• An API token with read access to workers, users, compensations, departments, teams, work locations, employment types and titles. Add headcount positions if you want them brought in as vacancies.
• A token owner who’s staying. Rippling revokes a token when its owner is terminated, or when it goes unused for over 30 days, and ownership can’t be transferred. A daily or more frequent schedule keeps it in use.

Set it up

In Rippling

1. Go to Tools → Developer → API Tokens.
2. Create a token and choose its scopes.
3. Copy the token. Rippling shows it once, and only its owner can change its scopes later.

In Flowstate

1. Ask your Flowstate contact to switch on custom integrations for your organisation. They provide the hook for Rippling and help your technical team configure it.
2. Go to Settings → Integrations → Custom Integrations: select Browse catalog and open Custom Integrations.
3. Select Create Integration. Enter a Name, such as Rippling, and a Source System Key, such as rippling. Select Create. You can’t change the key later.
4. Under Credentials, select Add Credential and store the API token, using the key name your Flowstate contact gives you.
5. Under Hooks, select Create Hook. Choose Pull as the Hook Type and Employee as the Entity Type, then select Create. Add the hook’s code and select Save Code. Add hooks for contractors and vacancies the same way if you bring them in.
6. On the hook’s Settings tab, turn on Run on schedule and choose an Interval. For Daily, choose a Preferred hour. Select Save Code.
7. Select Test (Dry Run) and open Preview. Check that nobody already in Flowstate is about to be created a second time.
8. Turn the hook on with the switch at the top of the editor, and confirm Enable Hook.

Each step in more detail: Manage a custom integration in Settings.

What syncs

To set location, work type or line manager, go to Resourcing → People and teams → People, open the person and change them under Employee details. Your technical team can also set them through the REST API. Nothing goes back to Rippling.

How changes arrive

• When. On the schedule you chose, from Every 15 minutes to Daily.
• Edits made in Flowstate. Anything the sync sends, such as role, team, dates and pay, is set back to Rippling’s value on the next run. Make those changes in Rippling. Location, work type and line manager stay as you set them. More in Edits made in Flowstate.
• Leavers. An end date in Rippling becomes the person’s end date in Flowstate. They stay in past months of the forecast and effort. The sync never deletes anyone.
• Rehires. Rippling gives a returning person a new worker ID. Before the next run, your technical team points their existing Flowstate record at the new ID and clears the old end date, through the REST API. Otherwise the new worker fails to sync, because their work email is already in use. See Leavers.
• Future-dated pay. A pay change with a future effective date comes across on the next run and shows as Scheduled on the Compensation tab until that date.

Check it’s working

1. Open the hook and select Execution History.
2. Find the latest run with Scheduled under Triggered By. It shows Completed, with a count under Records.
3. If some records failed, the run’s log has a line for each one, with the reason.
4. Go to Resourcing → People and teams → People and compare a few people with Rippling: a recent joiner, a recent leaver (Filter → Status → Include off-boarded) and someone with a recent pay change. Check Role, Current team, Employment dates and the Compensation tab.

If something’s not right

Runs suddenly fail with an authentication error. Rippling revoked the token: its owner left, or it went unused for over 30 days. Have an admin who’s staying create a new token, then update the credential.

Only some people come across, or details are blank. The token can’t see them. A blank value from Rippling means the data exists but the token has no permission for it. Check the owner’s permission profile covers The entire company, and that the token has the scopes listed above.

Runs fail because Rippling blocked requests. Rippling blocks every request for 10 seconds when more than 300 arrive from one address in 10 seconds. Ask your Flowstate contact to look at the hook.

Contractors show up as employees. Check their employment type in Rippling is a contractor type.

For your technical team

API. Rippling REST API at https://rest.ripplingapis.com. Pin a dated version with Rippling-Api-Version: YYYY-MM-DD, or set it on the token. Rippling lists its older V1 APIs as legacy.

Auth. Authorization: Bearer <token>. Access is the creator’s permission profile combined with the scopes chosen.

Scopes. workers.read, users.read, compensations.read (sensitive), departments.read, teams.read, work-locations.read, employment-types.read, titles.read. For vacancies: headcount-positions.read, headcount-positions.compensation.read, job-requisitions.read. For the change feed: worker-changes.read, worker-change-fields.read.

Endpoints.

• GET /workers/ takes filter (on status, work_email, user_id, created_at, updated_at), expand (such as user, manager, compensation), order_by (id, created_at, updated_at), limit (default 50, max 100) and cursor. Follow next_link until it’s null. For changes since the last run, filter updated_at with gt; check the filter in Rippling’s reference.
• GET /compensations, or expand=compensation: annual_compensation{currency_type, value}, hourly_wage, monthly_compensation, annual_salary_equivalent, salary_effective_date, payment_type. Current package only.
• GET /headcount-positions: position_type (OPEN_HEADCOUNT, FUTURE_START, ACTIVE, CLOSED), position_sub_type, title, department_id, work_location_id, employment_type_id, target_start_date, worker_id, backfill_for_id. Job requisitions: GET /job-requisitions.
• Worker Changes (GET /worker-changes/, GET /worker-change-fields/) is an audit feed of hires, changes and offboarding with from_value and to_value, including pay field keys such as compensation.base_salary. Poll by applied_on, not effective_on, or future-dated changes are missed. It needs an entitlement switched on by your Rippling Technical Account Manager.

Fields.

• worker.id is one period of work. A rehire creates a new worker under the same user_id.
• employment_type_id resolves to CompanyEmploymentType.type (CONTRACTOR or EMPLOYEE). amount_worked is FULL-TIME, PART-TIME or TEMPORARY.
• department_id resolves to Department{name, parent_id}; manager_id expands with manager,manager.user; location{type, work_location_id} resolves to WorkLocation{name, address}.
• status: INIT, HIRED, ACCEPTED, ACTIVE, TERMINATED. Also start_date, end_date, original_start_date, termination_details.
• null means the data exists but the token can’t see it. Also check you requested the expand you need.

Limits. 300 requests per IP in a sliding 10-second window; over that, all requests are blocked for 10 seconds. Page size max 100. expand depth 2, with up to 10 expanded fields. A filter can have at most 64 nodes.

Webhooks. Webhooks created at Tools → Developer → Webhooks fire only for custom object records. Worker events (employee.created, employee.updated, employee.terminated and others) go only to App Shop partner apps, form-encoded, with no HMAC signature documented. A customer integration polls.

Rippling docs.

• REST API
• API tokens
• Permissions
• API limits
• List workers
• Worker changes
• Headcount position