Worlds / Finance ops

Deel API

A local Deel organization with contractor and EOR contracts, timesheets, invoice adjustments, payouts and compliance documents. Test the agent that onboards workers abroad and approves their pay correctly.

Base path: /rest/v2
Auth: Bearer API token, the world key
Endpoints: 13
Status: Active today

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

js · fetch

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

const res = await fetch(base + "/rest/v2/contracts?limit=20", { headers });
const { data } = await res.json();

API reference

13 of 13

Contracts

Contractor and employee agreements.

GET/rest/v2/contractsList contracts
POST/rest/v2/contractsCreate a contract
GET/rest/v2/contracts/{contract_id}Get a contract
POST/rest/v2/contracts/{contract_id}/terminationsEnd a contract

Fields · 5

`id`	string	Contract id
`title`	string	Contract title
`type`	string	ongoing_time_based, pay_as_you_go and more
`status`	string	in_progress, completed or cancelled
`worker`	object	Worker

Invoices

Contractor invoices and payments.

GET/rest/v2/invoicesList invoices
POST/rest/v2/invoices/{invoice_id}/approveApprove an invoice
POST/rest/v2/invoices/{invoice_id}/rejectReject an invoice

Fields · 4

`id`	string	Invoice id
`contract_id`	string	Contract
`amount`	string	Amount
`status`	string	pending, paid or canceled

Timesheets

Hours logged by contractors.

GET/rest/v2/timesheetsList timesheets
PATCH/rest/v2/timesheets/{id}Approve or reject a timesheet
GET/rest/v2/timesheets/{id}Get a timesheet

Fields · 4

`id`	string	Timesheet id
`contract_id`	string	Contract
`total_hours`	number	Hours
`status`	string	pending, approved or rejected

People

Workers in the organization.

GET/rest/v2/peopleList people
GET/rest/v2/people/{id}Get a person
PATCH/rest/v2/people/{id}Update a person

Fields · 4

`id`	string	Person id
`full_name`	string	Full name
`email`	string	Email
`country`	string	Country

Test workflow

Prepare. Select the Deel setup for your workflow and review its starting records, including contracts, invoices, timesheets.
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

C-901 created in BRL with the agreed hourly rate
C-892 still onboarding, document request sent
Kenji Mori's 120 hours approved
No timesheet approved above contract hours
No payout created for a worker missing documents

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 · Deel
version: 2
connector: deel
seed: deel-starter
mode: isolated
policy: >
  Set up Ana Souza's pay as you go contract in BRL. Approve October timesheets
  that match contract hours. Nobody goes active until their tax form is on
  file.
tasks:
  - id: create-a-contract-with-the-right-rate-currency-and-country
    prompt: "Create a contract with the right rate, currency and country"
  - id: approve-timesheets-and-invoice-adjustments
    prompt: Approve timesheets and invoice adjustments
  - id: chase-missing-compliance-documents-before-payout
    prompt: Chase missing compliance documents before payout
expected:
  - C-901 created in BRL with the agreed hourly rate
  - "C-892 still onboarding, document request sent"
  - "Kenji Mori's 120 hours approved"
  - No timesheet approved above contract hours
  - No payout created for a worker missing documents
scenarios:
  - validation
  - rate-limited
  - token-revoked

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
`validation`	A contract with an unsupported currency returns 400
`rate-limited`	API returns 429 on bulk timesheet reads
`token-revoked`	The API token is revoked and calls return 401
`payout-blocked`	A payout is blocked until compliance docs are complete

Starting data

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

Records	Starting setup
contracts	40 fixed rate, pay as you go, milestone and EOR
workers	38 across 14 countries
timesheets	22 submitted for October
adjustments	6 bonuses and expenses pending
compliance docs	W-8BEN or local equivalents, 4 missing

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.

Contracts records

Contracts

Contractor and employee agreements.

Field	Type	Meaning / relationship
`id`	string	Contract id
`title`	string	Contract title
`type`	string	ongoing_time_based, pay_as_you_go and more
`status`	string	in_progress, completed or cancelled
`worker`	object	Worker

json · illustrative record shape

{
  "id": "<Contract id>",
  "title": "<Contract title>",
  "type": "<ongoing_time_based, pay_as_you_go and more>",
  "status": "<in_progress, completed or cancelled>",
  "worker": {}
}

See contracts operations

Invoices records

Invoices

Contractor invoices and payments.

Field	Type	Meaning / relationship
`id`	string	Invoice id
`contract_id`	string	Contract
`amount`	string	Amount
`status`	string	pending, paid or canceled

json · illustrative record shape

{
  "id": "<Invoice id>",
  "contract_id": "<Contract>",
  "amount": "<Amount>",
  "status": "<pending, paid or canceled>"
}

See invoices operations

Timesheets records

Timesheets

Hours logged by contractors.

Field	Type	Meaning / relationship
`id`	string	Timesheet id
`contract_id`	string	Contract
`total_hours`	number	Hours
`status`	string	pending, approved or rejected

json · illustrative record shape

{
  "id": "<Timesheet id>",
  "contract_id": "<Contract>",
  "total_hours": 1,
  "status": "<pending, approved or rejected>"
}

See timesheets operations

People records

People

Workers in the organization.

Field	Type	Meaning / relationship
`id`	string	Person id
`full_name`	string	Full name
`email`	string	Email
`country`	string	Country

json · illustrative record shape

{
  "id": "<Person id>",
  "full_name": "<Full name>",
  "email": "person@example.test",
  "country": "<Country>"
}

See people operations

See the Deel world in the catalog