Worlds / Finance ops

Ramp API

A local Ramp with cards, spend limits, card transactions, receipts, memos and accounting codes. Test the finance agent that chases receipts, codes spend and adjusts limits by policy.

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

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

js · fetch

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

const res = await fetch(base + "/developer/v1/transactions?page_size=20", { headers });
const { data } = await res.json();

API reference

14 of 14

Transactions

Card spend with merchant and receipt state.

GET/developer/v1/transactionsList transactions
GET/developer/v1/transactions/{transaction_id}Get a transaction
GET/developer/v1/transactions/{transaction_id}/receiptsList receipts on a transaction

Fields · 6

`id`	string	Transaction id
`amount`	number	Amount
`merchant_name`	string	Merchant
`state`	string	PENDING, CLEARED or DECLINED
`card_holder`	object	Cardholder
`sk_category_name`	string	Spend category

Cards

Virtual and physical cards.

POST/developer/v1/cards/deferred/virtualCreate a virtual card
GET/developer/v1/cards/{card_id}Get a card
PATCH/developer/v1/cards/{card_id}Update a card
POST/developer/v1/cards/{card_id}/deferred/suspensionSuspend a card
GET/developer/v1/cardsList cards

Fields · 4

`id`	string	Card id
`display_name`	string	Card name
`state`	string	ACTIVE, SUSPENDED or TERMINATED
`spending_restrictions`	object	Limits and categories

Users

Employees with roles and departments.

GET/developer/v1/usersList users
GET/developer/v1/users/{user_id}Get a user
POST/developer/v1/users/deferredInvite a user

Fields · 4

`id`	string	User id
`email`	string	Email
`role`	string	Role
`department_id`	string	Department

Reimbursements

Out of pocket expenses paid back to employees.

GET/developer/v1/reimbursementsList reimbursements
GET/developer/v1/reimbursements/{reimbursement_id}Get a reimbursement
PATCH/developer/v1/reimbursements/{reimbursement_id}Update a reimbursement

Fields · 4

`id`	string	Reimbursement id
`amount`	number	Amount
`user_id`	string	Employee
`status`	string	Approval and payment state

Test workflow

Prepare. Select the Ramp setup for your workflow and review its starting records, including transactions, cards, users.
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

Delta transaction has a receipt with matching amount
Figma coded to 6420 Software
Nobu transaction flagged back to Owen Park
No limits changed
Pending Hertz transaction left alone

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 · Ramp
version: 2
connector: ramp
seed: ramp-starter
mode: isolated
policy: >
  Clear the review queue. Match receipts from the inbox and code software and
  travel. Anything over the meal cap goes back to the cardholder, not
  approved.
tasks:
  - id: match-receipts-and-memos-to-card-transactions
    prompt: Match receipts and memos to card transactions
  - id: code-transactions-to-gl-accounts-and-departments
    prompt: Code transactions to GL accounts and departments
  - id: raise-or-lower-a-spend-limit-within-policy
    prompt: Raise or lower a spend limit within policy
expected:
  - Delta transaction has a receipt with matching amount
  - Figma coded to 6420 Software
  - Nobu transaction flagged back to Owen Park
  - No limits changed
  - Pending Hertz transaction left alone
scenarios:
  - rate-limited
  - token-expired
  - pending-changes

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 developer API returns 429 on transaction listing
`token-expired`	The client credentials token expires and returns 401
`pending-changes`	A pending transaction's amount changes when it clears
`declined`	A card declines at a blocked merchant category

Starting data

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

Records	Starting setup
cards	45 virtual and physical cards
limits	30 with monthly amounts and merchant restrictions
transactions	900 cleared, 22 pending, 8 declined
receipts	Missing on 37 transactions
policy	Receipts required over $75, meals capped at $60

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.

Transactions records

Transactions

Card spend with merchant and receipt state.

Field	Type	Meaning / relationship
`id`	string	Transaction id
`amount`	number	Amount
`merchant_name`	string	Merchant
`state`	string	PENDING, CLEARED or DECLINED
`card_holder`	object	Cardholder
`sk_category_name`	string	Spend category

json · illustrative record shape

{
  "id": "<Transaction id>",
  "amount": 1,
  "merchant_name": "<Merchant>",
  "state": "<PENDING, CLEARED or DECLINED>",
  "card_holder": {},
  "sk_category_name": "<Spend category>"
}

See transactions operations

Cards records

Cards

Virtual and physical cards.

Field	Type	Meaning / relationship
`id`	string	Card id
`display_name`	string	Card name
`state`	string	ACTIVE, SUSPENDED or TERMINATED
`spending_restrictions`	object	Limits and categories

json · illustrative record shape

{
  "id": "<Card id>",
  "display_name": "<Card name>",
  "state": "<ACTIVE, SUSPENDED or TERMINATED>",
  "spending_restrictions": {}
}

See cards operations

Users records

Users

Employees with roles and departments.

Field	Type	Meaning / relationship
`id`	string	User id
`email`	string	Email
`role`	string	Role
`department_id`	string	Department

json · illustrative record shape

{
  "id": "<User id>",
  "email": "person@example.test",
  "role": "<Role>",
  "department_id": "<Department>"
}

See users operations

Reimbursements records

Reimbursements

Out of pocket expenses paid back to employees.

Field	Type	Meaning / relationship
`id`	string	Reimbursement id
`amount`	number	Amount
`user_id`	string	Employee
`status`	string	Approval and payment state

json · illustrative record shape

{
  "id": "<Reimbursement id>",
  "amount": 1,
  "user_id": "<Employee>",
  "status": "<Approval and payment state>"
}

See reimbursements operations

See the Ramp world in the catalog