Worlds / Hr and identity

BambooHR API

A local BambooHR with employee records, time off policies and requests, approvals and performance reviews. Test the agent that answers HR requests, approves time off and keeps employee fields current.

Base path: /api/gateway.php/acme/v1
Auth: API key over HTTP basic auth, the world key
Endpoints: 14
Status: Active today

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

js · fetch

const base = process.env.WORLDS_BAMBOOHR_URL;
const auth = Buffer.from(process.env.WORLDS_API_KEY + ":x").toString("base64");

const res = await fetch(base + "/api/gateway.php/acme/v1/employees/directory", {
  headers: { Authorization: "Basic " + auth, Accept: "application/json" },
});

const { employees } = await res.json();

API reference

14 of 14

Employees

Employee records and the fields you pick on read.

GET/api/gateway.php/acme/v1/employees/directoryGet the employee directory
GET/api/gateway.php/acme/v1/employees/{id}Get an employee, with a fields query
POST/api/gateway.php/acme/v1/employeesAdd an employee
POST/api/gateway.php/acme/v1/employees/{id}Update an employee

Fields · 6

`id`	string	Employee id
`firstName`	string	First name
`lastName`	string	Last name
`jobTitle`	string	Job title
`department`	string	Department name
`supervisor`	string	Supervisor name

Time off requests

Requests for vacation, sick days and other leave.

GET/api/gateway.php/acme/v1/time_off/requestsList time off requests
PUT/api/gateway.php/acme/v1/employees/{id}/time_off/requestCreate a time off request
PUT/api/gateway.php/acme/v1/time_off/requests/{id}/statusChange a request's status
GET/api/gateway.php/acme/v1/time_off/whos_outList who is out

Fields · 6

`id`	integer	Request id
`employeeId`	integer	Employee who asked
`start`	date	First day off
`end`	date	Last day off
`status`	object	Status code and last changed date
`amount`	object	Unit and amount requested

Time off types and policies

Leave types and the policies employees accrue under.

GET/api/gateway.php/acme/v1/meta/time_off/typesList time off types
GET/api/gateway.php/acme/v1/meta/time_off/policiesList time off policies
GET/api/gateway.php/acme/v1/employees/{id}/time_off/calculatorEstimate future time off balances

Fields · 4

`id`	string	Type id
`name`	string	Type name
`units`	string	Days or hours
`color`	string	Calendar color

Applicant tracking

Job openings and the candidates who applied.

GET/api/gateway.php/acme/v1/applicant_tracking/jobsList job openings
GET/api/gateway.php/acme/v1/applicant_tracking/applicationsList applications
POST/api/gateway.php/acme/v1/applicant_tracking/applications/{id}/statusChange an application's status

Fields · 4

`id`	integer	Application or opening id
`jobTitle`	string	Job title
`status`	string	Opening or application status
`applicant`	object	Name and email of the applicant

Test workflow

Prepare. Select the BambooHR setup for your workflow and review its starting records, including employees, time off requests, time off types and policies.
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

Maya Brooks vacation approved
Owen Price request still Requested with a manager note
Owen Price Vacation balance unchanged
Lena Fox sick day approved
No job info or compensation rows written

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 · BambooHR
version: 2
connector: bamboohr
seed: bamboohr-starter
mode: isolated
policy: >
  Work the time off inbox. Approve requests that fit the remaining balance and
  team coverage. For anything over balance, leave it requested and add a note
  for the manager.
tasks:
  - id: approve-or-deny-time-off-against-the-policy-balance
    prompt: Approve or deny time off against the policy balance
  - id: update-job-info-and-compensation-tables-after-a-promotion
    prompt: Update job info and compensation tables after a promotion
  - id: remind-managers-about-open-performance-reviews
    prompt: Remind managers about open performance reviews
expected:
  - Maya Brooks vacation approved
  - Owen Price request still Requested with a manager note
  - Owen Price Vacation balance unchanged
  - Lena Fox sick day approved
  - No job info or compensation rows written
scenarios:
  - throttled
  - permission-denied
  - field-error

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
`throttled`	The API returns 503 with Retry-After during a bulk update
`permission-denied`	The API key's user lacks access to compensation and gets 403
`field-error`	A bad value returns 400 with the X-BambooHR-Error-Message header
`overlapping-leave`	The request overlaps leave that is already approved

Starting data

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

Records	Starting setup
employees	120 with job info, compensation and emergency contact tables
time off	Vacation, Sick and Bereavement policies with balances
requests	22 time off requests, requested, approved and denied
reviews	An open review cycle with 40 assessments due
who's out	Company holidays and existing approved leave

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

Employee records and the fields you pick on read.

Field	Type	Meaning / relationship
`id`	string	Employee id
`firstName`	string	First name
`lastName`	string	Last name
`jobTitle`	string	Job title
`department`	string	Department name
`supervisor`	string	Supervisor name

json · illustrative record shape

{
  "id": "<Employee id>",
  "firstName": "<First name>",
  "lastName": "<Last name>",
  "jobTitle": "<Job title>",
  "department": "<Department name>",
  "supervisor": "<Supervisor name>"
}

See employees operations

Time off requests records

Time off requests

Requests for vacation, sick days and other leave.

Field	Type	Meaning / relationship
`id`	integer	Request id
`employeeId`	integer	Employee who asked
`start`	date	First day off
`end`	date	Last day off
`status`	object	Status code and last changed date
`amount`	object	Unit and amount requested

json · illustrative record shape

{
  "id": 1,
  "employeeId": 1,
  "start": "<First day off>",
  "end": "<Last day off>",
  "status": {},
  "amount": {}
}

See time off requests operations

Time off types and policies records

Time off types and policies

Leave types and the policies employees accrue under.

Field	Type	Meaning / relationship
`id`	string	Type id
`name`	string	Type name
`units`	string	Days or hours
`color`	string	Calendar color

json · illustrative record shape

{
  "id": "<Type id>",
  "name": "<Type name>",
  "units": "<Days or hours>",
  "color": "<Calendar color>"
}

See time off types and policies operations

Applicant tracking records

Applicant tracking

Job openings and the candidates who applied.

Field	Type	Meaning / relationship
`id`	integer	Application or opening id
`jobTitle`	string	Job title
`status`	string	Opening or application status
`applicant`	object	Name and email of the applicant

json · illustrative record shape

{
  "id": 1,
  "jobTitle": "<Job title>",
  "status": "<Opening or application status>",
  "applicant": {}
}

See applicant tracking operations

See the BambooHR world in the catalog