Rippling Sensor

What it ingests

Org chart from Rippling REST — the HRIS objects, not payroll or ATS:

Rippling object	Ontology entity	Signal
Company	Organization	company
Department	Organization	department
Team	Organization	team
Worker	Person (identity)	worker

A department or team is an org unit (the HubSpot company analog); a worker is identity — they resolve to Person via work email / name, the same contract as a HubSpot contact. Each object kind has its own signal, so you can disable a noisy stream from the source's bindings without disabling the source.

This is Rippling alone. Workday and BambooHR are sibling sources with different APIs. Greenhouse is the ATS sibling — do not configure this source against Greenhouse.

Read-only and poll-based against https://rest.ripplingapis.com. Rippling webhooks exist but are configured in the Rippling UI, never via API, so they cannot be provisioned at install time.

Compensation, personal email, date of birth, and demographic fields are never requested.

Credential

References a rippling_api_token credential by id. The secret is a Rippling API token. Rippling authenticates with Authorization: Bearer <token>. Rippling is a single cloud API, so there is no site URL beside the token.

OAuth app-install tokens are a different product and will not authenticate this source.

curl -sS -X POST https://your-corveil-host/api/credentials \
  -H "Authorization: Bearer <admin>" -H "Content-Type: application/json" \
  -d '{"type":"rippling_api_token","name":"acme-rippling","secret":"<api-token>"}'

Config fields

Key	Required	Notes
enabled_objects	no	Comma-separated Rippling object kinds. Blank polls every supported kind. Unknown names are rejected at configure time.

Supported object names: companies, departments, teams, workers.

There is no default_entity_type. This source emits Organization across three signals, so a single override would retarget all of them.

Provider-side setup

1. In Rippling, go to Tools → Developer → API Tokens.
2. Create an API token. Tokens inherit the permission profile of the user who creates them — create it as an admin who can read the org chart.
3. Grant at least companies.read, departments.read, teams.read, and workers.read. Scopes are per resource — a token that can list companies may still 403 on workers.
4. Copy the token. Store only the token value, not Bearer ….

Wire-up

POST /api/sensors

{
  "sensor_type": "rippling",
  "name": "Acme Rippling",
  "config": {
    "enabled_objects": "companies, departments, teams, workers"
  },
  "credentials": { "api_token": "<rippling_api_token credential id>" }
}

Verify

Run Test connection. It authenticates the token against the first enabled object's list endpoint, so a 401/403 fails at save/test rather than on the first poll. Rippling tokens are scoped per resource; the probe uses an object this source is actually configured to read.

Once polling, each object kind's count appears in the per-poll summary log (companies_collected, workers_collected, …). A kind stuck at zero while the others move is the signal to check that kind's scope.

How incremental sync works

• Every object filters on updated_at gte. A test pins the literal so a typo cannot silently re-read the whole roster every tick.
• Each poll re-reads a two-minute overlap. List clocks can lag the write, so a strict resume would step permanently past a record that was briefly behind.
• next_link is host-pinned. The next URL is absolute and this client sends Authorization on every request, so a poisoned link is refused (Greenhouse / Bitbucket's same posture).
• Deletes are invisible. A record vanishing from results is not treated as a deletion.
• Terminated workers still sync when they appear in /workers (status is stored on the event). Rippling's list includes them unless you filter them out server-side; v1 does not.

Not included

• Workday. Sibling HRIS source with a different API; do not configure this source against Workday.
• BambooHR. Different vendor; stays coming-soon. Do not configure this source against it.
• Greenhouse / Lever. ATS products; Greenhouse has its own sensor.
• Compensation, personal email, demographics. Never requested. Expanding compensation is refused by a test.
• OAuth / marketplace apps. Only needed for multi-customer marketplace distribution.
• Webhooks. Rippling supports them, but subscriptions are created in the Rippling UI, never via API — so they cannot be provisioned at install time. Polling is the supported path.
• Leave, time entries, job requisitions, candidates. Deferred.