Worlds / Hr and identity

Rippling API

A local Rippling with employees, departments, devices, third-party app access and payroll runs, all linked to one employee record. Test the agent that onboards and offboards people across every system that record touches.

Base path: /platform/api
Auth: OAuth bearer token, the world key
Endpoints: 13
Status: Active today

This reference previews the surface the Rippling world serves in the closed beta. Paths mirror the public Rippling API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_RIPPLING_URL`	This world's origin followed by `/platform/api`
`WORLDS_API_KEY`	The world key, accepted wherever Rippling expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_RIPPLING_URL;

const res = await fetch(base + "/platform/api/employees?limit=25", {
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  },
});

const employees = await res.json();

API reference

13 of 13

Employees

Active and terminated employees with role and manager.

GET/platform/api/employeesList employees
GET/platform/api/employees/{id}Get an employee
GET/platform/api/employees/include_terminatedList employees including terminated

Fields · 6

`id`	string	Employee id
`name`	string	Full name
`workEmail`	string	Work email
`title`	string	Job title
`manager`	string	Manager's employee id
`employmentType`	string	Full time, part time or contractor

Departments

Departments employees belong to.

GET/platform/api/departmentsList departments
GET/platform/api/departments/{id}Get a department
GET/platform/api/departments/{id}/employeesList employees in a department

Fields · 4

`id`	string	Department id
`name`	string	Department name
`parent`	string	Parent department id
`headcount`	integer	Employees in the department

Groups

Custom groups used for access and policy targeting.

GET/platform/api/groupsList groups
POST/platform/api/groupsCreate a group
PUT/platform/api/groups/{id}Update a group
DELETE/platform/api/groups/{id}Delete a group

Fields · 4

`id`	string	Group id
`name`	string	Group name
`spokeId`	string	App the group belongs to
`users`	array	Employee ids in the group

Leave requests

Time off requests and their approval state.

GET/platform/api/leave_requestsList leave requests
PATCH/platform/api/leave_requests/{id}Approve or decline a request
GET/platform/api/leave_balancesList leave balances

Fields · 5

`id`	string	Leave request id
`roleId`	string	Employee role the request is for
`startDate`	date	First day of leave
`endDate`	date	Last day of leave
`status`	string	Pending, approved or declined

Test workflow

Prepare. Select the Rippling setup for your workflow and review its starting records, including employees, departments, groups.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Only the full-time Sam Okafor record terminated
Slack and GitHub access removed for that record
MacBook M3 locked, not wiped
Contractor record for Sam Okafor unchanged
Jo Park onboarding untouched

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Rippling
version: 2
connector: rippling
seed: rippling-starter
mode: isolated
policy: >
  Offboard Sam Okafor, the full-time engineer whose last day is Friday. Revoke
  all app access and lock the laptop, but do not wipe it until IT confirms the
  handoff.
tasks:
  - id: onboard-a-new-hire-with-the-right-apps-and-a-laptop
    prompt: Onboard a new hire with the right apps and a laptop
  - id: offboard-a-leaver-revoke-apps-lock-and-retrieve-the-device
    prompt: "Offboard a leaver: revoke apps, lock and retrieve the device"
  - id: change-a-department-and-let-app-rules-follow
    prompt: Change a department and let app rules follow
expected:
  - Only the full-time Sam Okafor record terminated
  - Slack and GitHub access removed for that record
  - "MacBook M3 locked, not wiped"
  - Contractor record for Sam Okafor unchanged
  - Jo Park onboarding untouched
scenarios:
  - rate-limited
  - token-expired
  - app-deprovision-failed

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	The employees endpoint returns 429 mid batch
`token-expired`	The OAuth access token expires and writes return 401
`app-deprovision-failed`	Removing GitHub access fails and stays pending
`device-offline`	The lock command queues until the laptop checks in
`approved-pay-run`	A change after approval lands on the next pay run

Starting data

Start each run from the same records and relationships. The overview below describes the Rippling starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
employees	180 across 9 departments, with managers and work locations
devices	160 laptops with assignee, serial and lock state
apps	Slack, Google Workspace, GitHub and Zoom with access rules by department
payroll	Two upcoming pay runs, one already approved
onboarding	6 hires with start dates in the next two weeks

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Employees records

Employees

Active and terminated employees with role and manager.

Field	Type	Meaning / relationship
`id`	string	Employee id
`name`	string	Full name
`workEmail`	string	Work email
`title`	string	Job title
`manager`	string	Manager's employee id
`employmentType`	string	Full time, part time or contractor

json · illustrative record shape

{
  "id": "<Employee id>",
  "name": "<Full name>",
  "workEmail": "person@example.test",
  "title": "<Job title>",
  "manager": "<Manager's employee id>",
  "employmentType": "<Full time, part time or contractor>"
}

See employees operations

Departments records

Departments

Departments employees belong to.

Field	Type	Meaning / relationship
`id`	string	Department id
`name`	string	Department name
`parent`	string	Parent department id
`headcount`	integer	Employees in the department

json · illustrative record shape

{
  "id": "<Department id>",
  "name": "<Department name>",
  "parent": "<Parent department id>",
  "headcount": 1
}

See departments operations

Groups records

Groups

Custom groups used for access and policy targeting.

Field	Type	Meaning / relationship
`id`	string	Group id
`name`	string	Group name
`spokeId`	string	App the group belongs to
`users`	array	Employee ids in the group

json · illustrative record shape

{
  "id": "<Group id>",
  "name": "<Group name>",
  "spokeId": "<App the group belongs to>",
  "users": []
}

See groups operations

Leave requests records

Leave requests

Time off requests and their approval state.

Field	Type	Meaning / relationship
`id`	string	Leave request id
`roleId`	string	Employee role the request is for
`startDate`	date	First day of leave
`endDate`	date	Last day of leave
`status`	string	Pending, approved or declined

json · illustrative record shape

{
  "id": "<Leave request id>",
  "roleId": "<Employee role the request is for>",
  "startDate": "<First day of leave>",
  "endDate": "<Last day of leave>",
  "status": "<Pending, approved or declined>"
}

See leave requests operations

See the Rippling world in the catalog