Worlds / Real estate

Buildium API

A local Buildium with rentals, tenants, leases, charges, payments, deposits and tasks. Test the bookkeeping agent that posts charges, records payments and handles move outs.

Base path: /v1
Auth: API key headers x-buildium-client-id and x-buildium-client-secret, the world key
Endpoints: 20
Status: Active today

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

js · fetch

const base = process.env.WORLDS_BUILDIUM_URL + "/v1";

const res = await fetch(base + "/leases?leasestatuses=Active&limit=50", {
  headers: {
    "x-buildium-client-id": process.env.WORLDS_API_KEY,
    "x-buildium-client-secret": process.env.WORLDS_API_KEY,
    Accept: "application/json",
  },
});

const leases = await res.json();
console.log(leases.length);

API reference

20 of 20

Rental properties

Rental buildings and their units.

GET/v1/rentalsList rental properties
GET/v1/rentals/{propertyId}Get a rental property
POST/v1/rentalsCreate a rental property
GET/v1/rentals/unitsList rental units

Fields · 5

`Id`	integer	Property id
`Name`	string	Property name
`Address`	object	Address
`NumberUnits`	integer	Unit count
`IsActive`	boolean	Active flag

Leases

Leases and their status.

GET/v1/leasesList leases
GET/v1/leases/{leaseId}Get a lease
POST/v1/leasesCreate a lease
PUT/v1/leases/{leaseId}Update a lease
GET/v1/leases/{leaseId}/transactionsList lease transactions

Fields · 6

`Id`	integer	Lease id
`LeaseType`	string	Fixed, AtWill
`LeaseStatus`	string	Active, Past, Future
`LeaseFromDate`	date	Start
`LeaseToDate`	date	End
`AccountDetails`	object	Rent and deposit

Tenants

Rental tenants.

GET/v1/leases/tenantsList tenants
GET/v1/leases/tenants/{tenantId}Get a tenant
POST/v1/leases/tenantsCreate a tenant

Fields · 5

`Id`	integer	Tenant id
`FirstName`	string	Given name
`LastName`	string	Family name
`Email`	string	Email
`PhoneNumbers`	object	Phone numbers

Work orders

Maintenance work orders.

GET/v1/workordersList work orders
GET/v1/workorders/{workOrderId}Get a work order
POST/v1/workordersCreate a work order
PUT/v1/workorders/{workOrderId}Update a work order

Fields · 6

`Id`	integer	Work order id
`Title`	string	Title
`Description`	string	Details
`WorkOrderStatus`	string	New, InProgress, Completed
`Priority`	string	Priority
`DueDate`	date	Due date

Bills and payments

Vendor bills and tenant charges.

GET/v1/billsList bills
POST/v1/billsCreate a bill
POST/v1/bills/{billId}/paymentsPay a bill
POST/v1/leases/{leaseId}/chargesCreate a lease charge

Fields · 5

`Id`	integer	Bill id
`VendorId`	integer	Vendor
`Date`	date	Bill date
`DueDate`	date	Due date
`Amount`	number	Amount

Test workflow

Prepare. Select the Buildium setup for your workflow and review its starting records, including rental properties, leases, tenants.
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

L-2205 deposit refunded $820 after a $180 damage deduction
L-2208 deposit refund includes its open damage charge
L-2201 payment applied to its own rent charge
No lease ended before its move out date
No refund larger than the deposit held

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 · Buildium
version: 2
connector: buildium
seed: buildium-starter
mode: isolated
policy: >
  Process this week's move outs. Deduct open charges from each deposit before
  refunding the rest, record the payments that came in, and end leases on
  their move out date.
tasks:
  - id: record-tenant-payments-against-open-charges
    prompt: Record tenant payments against open charges
  - id: process-move-outs-and-security-deposit-returns
    prompt: Process move outs and security deposit returns
  - id: create-tasks-from-resident-requests
    prompt: Create tasks from resident requests
expected:
  - L-2205 deposit refunded $820 after a $180 damage deduction
  - L-2208 deposit refund includes its open damage charge
  - L-2201 payment applied to its own rent charge
  - No lease ended before its move out date
  - No refund larger than the deposit held
scenarios:
  - rate-limited
  - payment-reversed
  - validation-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
`rate-limited`	API calls return 429
`payment-reversed`	An ACH payment is returned two days later
`validation-error`	A charge with no GL account is rejected
`credentials-revoked`	The API key stops working mid run

Starting data

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

Records	Starting setup
rentals	4 properties with 70 units
tenants	65 with lease ledgers
charges	Rent, utility and fee charges, 12 open past due
deposits	Security deposits held on every lease
tasks	20 resident requests and to dos

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.

Rental properties records

Rental properties

Rental buildings and their units.

Field	Type	Meaning / relationship
`Id`	integer	Property id
`Name`	string	Property name
`Address`	object	Address
`NumberUnits`	integer	Unit count
`IsActive`	boolean	Active flag

json · illustrative record shape

{
  "Id": 1,
  "Name": "<Property name>",
  "Address": {},
  "NumberUnits": 1,
  "IsActive": false
}

See rental properties operations

Leases records

Leases

Leases and their status.

Field	Type	Meaning / relationship
`Id`	integer	Lease id
`LeaseType`	string	Fixed, AtWill
`LeaseStatus`	string	Active, Past, Future
`LeaseFromDate`	date	Start
`LeaseToDate`	date	End
`AccountDetails`	object	Rent and deposit

json · illustrative record shape

{
  "Id": 1,
  "LeaseType": "<Fixed, AtWill>",
  "LeaseStatus": "<Active, Past, Future>",
  "LeaseFromDate": "<Start>",
  "LeaseToDate": "<End>",
  "AccountDetails": {}
}

See leases operations

Tenants records

Tenants

Rental tenants.

Field	Type	Meaning / relationship
`Id`	integer	Tenant id
`FirstName`	string	Given name
`LastName`	string	Family name
`Email`	string	Email
`PhoneNumbers`	object	Phone numbers

json · illustrative record shape

{
  "Id": 1,
  "FirstName": "<Given name>",
  "LastName": "<Family name>",
  "Email": "person@example.test",
  "PhoneNumbers": {}
}

See tenants operations

Work orders records

Work orders

Maintenance work orders.

Field	Type	Meaning / relationship
`Id`	integer	Work order id
`Title`	string	Title
`Description`	string	Details
`WorkOrderStatus`	string	New, InProgress, Completed
`Priority`	string	Priority
`DueDate`	date	Due date

json · illustrative record shape

{
  "Id": 1,
  "Title": "<Title>",
  "Description": "<Details>",
  "WorkOrderStatus": "<New, InProgress, Completed>",
  "Priority": "<Priority>",
  "DueDate": "<Due date>"
}

See work orders operations

Bills and payments records

Bills and payments

Vendor bills and tenant charges.

Field	Type	Meaning / relationship
`Id`	integer	Bill id
`VendorId`	integer	Vendor
`Date`	date	Bill date
`DueDate`	date	Due date
`Amount`	number	Amount

json · illustrative record shape

{
  "Id": 1,
  "VendorId": 1,
  "Date": "<Bill date>",
  "DueDate": "<Due date>",
  "Amount": 1
}

See bills and payments operations

See the Buildium world in the catalog