Worlds / Finance ops

ADP API

A local ADP Workforce Now company with workers, pay groups, payroll cycles, deductions, garnishments and tax filings. Test the payroll agent that preps runs, adds deductions and handles off-cycle checks.

Base path: /hr/v2
Auth: OAuth bearer token, the world key
Endpoints: 12
Status: Active today

This reference previews the surface the ADP world serves in the closed beta. Paths mirror the public ADP 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_ADP_URL`	This world's origin followed by `/hr/v2`
`WORLDS_API_KEY`	The world key, accepted wherever ADP expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_ADP_URL;
const headers = { Authorization: "Bearer " + process.env.WORLDS_API_KEY };

const res = await fetch(base + "/hr/v2/workers?$top=20", { headers });
const { workers } = await res.json();

API reference

12 of 12

Workers

Employees with assignment and pay details.

GET/hr/v2/workersList workers
GET/hr/v2/workers/{aoid}Get a worker
POST/hr/v2/workers/{aoid}/events/worker.legal-name.changeChange a legal name

Fields · 4

`associateOID`	string	Worker id
`person`	object	Legal name and contact
`workAssignments`	array	Jobs and managers
`workerStatus`	object	Active, terminated or on leave

Time off

Balances and requests.

GET/hr/v2/workers/{aoid}/time-off-balancesGet time off balances
POST/hr/v2/workers/{aoid}/time-off-requestsSubmit a time off request
GET/hr/v2/workers/{aoid}/time-off-requestsList time off requests

Fields · 4

`policyCode`	string	Time off policy
`balance`	number	Hours available
`requestStatus`	string	Pending, approved or denied
`startDate`	date	First day off

Pay statements

Earnings and deductions per pay period.

GET/hr/v2/workers/{aoid}/pay-statementsList pay statements
GET/hr/v2/workers/{aoid}/pay-statements/{id}Get a pay statement
GET/hr/v2/workers/{aoid}/pay-statements/latestGet the latest pay statement

Fields · 4

`payDate`	date	Pay date
`grossPayAmount`	object	Gross pay
`netPayAmount`	object	Net pay
`deductions`	array	Taxes and benefits

Job requisitions

Open roles.

GET/hr/v2/job-requisitionsList job requisitions
POST/hr/v2/job-requisitionsCreate a job requisition
GET/hr/v2/job-requisitions/{id}Get a job requisition

Fields · 4

`requisitionID`	string	Requisition id
`jobTitle`	string	Title
`status`	string	Open, filled or closed
`hiringManager`	object	Hiring manager

Test workflow

Prepare. Select the ADP setup for your workflow and review its starting records, including workers, time off, pay statements.
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

Pay group A submitted before the Tue 3 cutoff
Off-cycle bonus for J. Alvarez dated no later than Thu 5
Pay group B cycle unchanged
No garnishment amounts changed
941 deposit schedule left as seeded

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 · ADP
version: 2
connector: adp
seed: adp-starter
mode: isolated
policy: >
  Get Pay group A's biweekly payroll submitted before the Tuesday cutoff. Run
  J. Alvarez's missed bonus off-cycle so it pays before Friday. Do not touch
  tax deposit schedules.
tasks:
  - id: prepare-and-submit-a-regular-payroll-cycle
    prompt: Prepare and submit a regular payroll cycle
  - id: run-an-off-cycle-check-for-a-missed-bonus
    prompt: Run an off-cycle check for a missed bonus
  - id: set-up-a-garnishment-or-deduction-on-a-worker
    prompt: Set up a garnishment or deduction on a worker
expected:
  - Pay group A submitted before the Tue 3 cutoff
  - Off-cycle bonus for J. Alvarez dated no later than Thu 5
  - Pay group B cycle unchanged
  - No garnishment amounts changed
  - 941 deposit schedule left as seeded
scenarios:
  - token-expired
  - rate-limited
  - locked-cycle

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
`token-expired`	The OAuth access token expires during the cycle
`rate-limited`	Worker reads return 429 during bulk updates
`locked-cycle`	Edits to a submitted cycle are rejected
`event-rejected`	A deduction change event is rejected for a missing effective date

Starting data

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

Records	Starting setup
workers	140 across 2 pay groups
pay cycles	Biweekly and semi-monthly
deductions	401(k), medical, dental and commuter
garnishments	3 child support orders, 1 tax levy
tax filings	Quarterly 941 and state unemployment

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.

Workers records

Workers

Employees with assignment and pay details.

Field	Type	Meaning / relationship
`associateOID`	string	Worker id
`person`	object	Legal name and contact
`workAssignments`	array	Jobs and managers
`workerStatus`	object	Active, terminated or on leave

json · illustrative record shape

{
  "associateOID": "<Worker id>",
  "person": {},
  "workAssignments": [],
  "workerStatus": {}
}

See workers operations

Time off records

Time off

Balances and requests.

Field	Type	Meaning / relationship
`policyCode`	string	Time off policy
`balance`	number	Hours available
`requestStatus`	string	Pending, approved or denied
`startDate`	date	First day off

json · illustrative record shape

{
  "policyCode": "<Time off policy>",
  "balance": 1,
  "requestStatus": "<Pending, approved or denied>",
  "startDate": "<First day off>"
}

See time off operations

Pay statements records

Pay statements

Earnings and deductions per pay period.

Field	Type	Meaning / relationship
`payDate`	date	Pay date
`grossPayAmount`	object	Gross pay
`netPayAmount`	object	Net pay
`deductions`	array	Taxes and benefits

json · illustrative record shape

{
  "payDate": "<Pay date>",
  "grossPayAmount": {},
  "netPayAmount": {},
  "deductions": []
}

See pay statements operations

Job requisitions records

Job requisitions

Open roles.

Field	Type	Meaning / relationship
`requisitionID`	string	Requisition id
`jobTitle`	string	Title
`status`	string	Open, filled or closed
`hiringManager`	object	Hiring manager

json · illustrative record shape

{
  "requisitionID": "<Requisition id>",
  "jobTitle": "<Title>",
  "status": "<Open, filled or closed>",
  "hiringManager": {}
}

See job requisitions operations

See the ADP world in the catalog