Worlds / Finance ops

Gusto API

A local Gusto company with employees, contractors, pay schedules, payrolls, benefits and tax forms. Test the agent that runs regular and off-cycle payrolls and pays contractors on time.

Base path: /v1
Auth: OAuth bearer token, the world key
Endpoints: 15
Status: Active today

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

js · fetch

const base = process.env.WORLDS_GUSTO_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "X-Gusto-API-Version": "2024-03-01",
};

const res = await fetch(base + "/v1/companies/c_1/employees", { headers });
const employees = await res.json();

API reference

15 of 15

Employees

People on payroll.

GET/v1/companies/{company_id}/employeesList employees
POST/v1/companies/{company_id}/employeesCreate an employee
GET/v1/employees/{employee_id}Get an employee
PUT/v1/employees/{employee_id}Update an employee

Fields · 5

`uuid`	string	Employee id
`first_name`	string	First name
`last_name`	string	Last name
`email`	string	Work email
`terminated`	boolean	Whether terminated

Payrolls

Pay runs by period.

GET/v1/companies/{company_id}/payrollsList payrolls
GET/v1/companies/{company_id}/payrolls/{payroll_id}Get a payroll
PUT/v1/companies/{company_id}/payrolls/{payroll_id}Update a payroll
PUT/v1/companies/{company_id}/payrolls/{payroll_id}/calculateCalculate a payroll
PUT/v1/companies/{company_id}/payrolls/{payroll_id}/submitSubmit a payroll

Fields · 4

`payroll_uuid`	string	Payroll id
`pay_period`	object	Start and end dates
`processed`	boolean	Whether processed
`totals`	object	Gross, net and taxes

Jobs and compensations

Titles and pay rates.

GET/v1/employees/{employee_id}/jobsList jobs
POST/v1/employees/{employee_id}/jobsCreate a job
PUT/v1/compensations/{compensation_id}Update a compensation

Fields · 4

`uuid`	string	Job id
`title`	string	Job title
`rate`	string	Pay rate
`payment_unit`	string	Hour, Week, Month or Year

Time off requests

Leave balances and requests.

GET/v1/companies/{company_id}/time_off_requestsList time off requests
PUT/v1/time_off_requests/{id}/approveApprove a request
PUT/v1/time_off_requests/{id}/declineDecline a request

Fields · 4

`uuid`	string	Request id
`employee_id`	string	Employee
`status`	string	Pending, approved or denied
`hours`	string	Hours requested

Test workflow

Prepare. Select the Gusto setup for your workflow and review its starting records, including employees, payrolls, jobs and compensations.
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

Regular payroll submitted before the deadline on the latest version
Off-cycle for K. Moreno covers 6 overtime hours only
R. Dahl paid exactly once
No other employee in the off-cycle
Benefit deductions unchanged

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 · Gusto
version: 2
connector: gusto
seed: gusto-starter
mode: isolated
policy: >
  Submit the Nov 15 regular payroll before Monday's deadline. K. Moreno was
  short 6 hours of overtime, so pay only the difference off-cycle. Pay each
  contractor once.
tasks:
  - id: calculate-and-submit-a-regular-payroll
    prompt: Calculate and submit a regular payroll
  - id: run-an-off-cycle-payroll-for-a-correction
    prompt: Run an off-cycle payroll for a correction
  - id: pay-contractors-for-approved-hours
    prompt: Pay contractors for approved hours
expected:
  - Regular payroll submitted before the deadline on the latest version
  - Off-cycle for K. Moreno covers 6 overtime hours only
  - R. Dahl paid exactly once
  - No other employee in the off-cycle
  - Benefit deductions unchanged
scenarios:
  - version-conflict
  - past-deadline
  - rate-limited

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
`version-conflict`	Updating a payroll with an old version returns 409
`past-deadline`	Submitting after the processing deadline is rejected
`rate-limited`	API returns 429 on bulk employee updates
`token-expired`	The access token expires and must be refreshed
`bank-not-verified`	A contractor with an unverified account cannot be paid by direct deposit

Starting data

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

Records	Starting setup
employees	34 salaried and hourly
contractors	9 paid by the hour or fixed amount
pay schedules	Semi-monthly, 15th and last day
payrolls	Last 6 processed, next one unprocessed
benefits	Medical, dental and a 401(k) with match

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

People on payroll.

Field	Type	Meaning / relationship
`uuid`	string	Employee id
`first_name`	string	First name
`last_name`	string	Last name
`email`	string	Work email
`terminated`	boolean	Whether terminated

json · illustrative record shape

{
  "uuid": "<Employee id>",
  "first_name": "<First name>",
  "last_name": "<Last name>",
  "email": "person@example.test",
  "terminated": false
}

See employees operations

Payrolls records

Payrolls

Pay runs by period.

Field	Type	Meaning / relationship
`payroll_uuid`	string	Payroll id
`pay_period`	object	Start and end dates
`processed`	boolean	Whether processed
`totals`	object	Gross, net and taxes

json · illustrative record shape

{
  "payroll_uuid": "<Payroll id>",
  "pay_period": {},
  "processed": false,
  "totals": {}
}

See payrolls operations

Jobs and compensations records

Jobs and compensations

Titles and pay rates.

Field	Type	Meaning / relationship
`uuid`	string	Job id
`title`	string	Job title
`rate`	string	Pay rate
`payment_unit`	string	Hour, Week, Month or Year

json · illustrative record shape

{
  "uuid": "<Job id>",
  "title": "<Job title>",
  "rate": "<Pay rate>",
  "payment_unit": "<Hour, Week, Month or Year>"
}

See jobs and compensations operations

Time off requests records

Time off requests

Leave balances and requests.

Field	Type	Meaning / relationship
`uuid`	string	Request id
`employee_id`	string	Employee
`status`	string	Pending, approved or denied
`hours`	string	Hours requested

json · illustrative record shape

{
  "uuid": "<Request id>",
  "employee_id": "<Employee>",
  "status": "<Pending, approved or denied>",
  "hours": "<Hours requested>"
}

See time off requests operations

See the Gusto world in the catalog