Deel

What your agents can doCopy Anchor Link

Agents search Deel's REST and SCIM APIs to manage workers and contracts, inspect payroll and invoices, handle time off and timesheets, and work with recruiting, immigration and IT records. Access depends on your Deel products and permissions.

Agents can upload and download files. Beta endpoints require the headers and version specified by Deel. Helios sends X-Version: 2026-01-01 unless the API request specifies another version.

AuthenticationCopy Anchor Link

Both methods require Environment, either production or sandbox. Sandbox uses separate credentials. Helios sends API requests to api.letsdeel.com in production or api-staging.letsdeel.com in sandbox.

Deel API tokenCopy Anchor Link

Create a token in Deel Developer Center, choose Deel API token in Helios, and enter API token. Use an organization token with the permissions your workflows need, including organizations:read, webhooks:read and webhooks:write.

Creating tokens and webhooks requires an Org Admin or IT Developer Admin account. Organization tokens do not expire. Replace revoked tokens in Helios.

Your own Deel appCopy Anchor Link

Create a Deel Organization app and register the callback URL shown by Helios. Choose Your own Deel app, select Environment, enter Client ID and Client secret, then authorize access.

Helios uses the production endpoints in Deel's REST OAuth guide. Sandbox authorization uses app.demo.deel.com with the same /oauth2 paths, because the sandbox host in Deel's guides fails the TLS handshake. Refresh tokens rotate after each use. Helios stores the replacement and schedules weekly refreshes.

Helios requests the following 92 scopes, which are the scopes Deel's Developer Center offers to Organization apps. Deel refuses the authorization with "Invalid scopes for User type" when an Organization app asks for other scopes, such as the OpenID or worker scopes. If authorization fails for another reason, check partnership access with Deel.

Users:read
Users:write
accounting:read
adjustments:read
adjustments:write
agentic-workflows:write
ai:read
ai:write
api-logs:read
approvals:read
approvals:write
ats.applications.notes:write
ats:read
ats:write
benefits:read
benefits:write
candidates:read
candidates:write
compensation-management:read
compensation-management:write
contracts:read
contracts:write
equities:read
equities:write
files:read
files:write
forms:read
global-payroll:read
global-payroll:write
groups:read
groups:write
hr-suite:read
hr-suite:write
i-9:read
i-9:write
immigration:read
immigration:write
invoice-adjustments:read
invoice-adjustments:write
invoice:create
it-agreements:read
it-assets:read
it-assets:write
it-orders:read
it-orders:write
it-policies:read
it-policies:write
it-products:read
it-seats:read
it-seats:write
it-service-requests:read
it-service-requests:write
job-architecture:read
job-architecture:write
jobs:read
jobs:write
knowledge-hub:read
legal-entity:read
legal-entity:write
milestones:read
milestones:write
off-cycle-payments:read
off-cycle-payments:write
on-demand-payroll:read
on-demand-payroll:write
organizations:read
organizations:write
payment-statements:read
payment-statements:write
payments:read
payslips:read
people:read
people:write
profile:read
profile:write
public-token:write
screenings:read
screenings:write
talents:read
talents:write
tasks:read
tasks:write
time-off:read
time-off:write
time-tracking:read
time-tracking:write
timesheets:read
timesheets:write
treasury-vendorbill:write
webhooks:read
webhooks:write
withdrawals:read

Admin access also requests admin:worker, the Embedded worker-token scope. Enable it only for an app approved for that access.

TriggersCopy Anchor Link

Helios subscribes to all 55 events below and updates its existing webhook where possible. If Deel refuses an event, Helios tries the other catalog events and marks uncovered events unavailable with the vendor's reason.

Deel's webhook guides use contract.signed and payment.completed in examples. Deel's event reference does not list them, and Deel's API rejects contract.signed as an unknown event, so Helios does not offer them. Contract signing changes the contract's status, which contract.status_updated reports.

Filters use fields in each event's payload. Every event offers Organization ID and Organization name. Depending on the event, you can also filter by resource, contract or worker ID, status, job posting, country, document type, invoice ID or email. Email patterns ignore case. For contract.created, Worker email uses nonempty worker.expected_email, falling back to invitations.worker_email. Worker v2 events contain only the worker ID. Empty filters accept all values; selected filters fail when the delivery lacks the field.

Payslip, tax-document, reviewed-adjustment and reviewed-timesheet payloads can contain arrays. Each delivery starts one event, and filters inspect all its resources. Multiple selected filters can match different resources in that delivery.

Helios prefers data.meta.event_id for deduplication. When it is absent, Helios hashes the event type, organization, top-level timestamp and resource. Deel documents timestamp as the time the event occurred. A retry whose resource changed gets a different ID. Helios accepts signed retries without an age check.

Errors and limitsCopy Anchor Link

• A failed connection test can mean a token is invalid, belongs to the other environment or lacks organizations:read.
• Webhook setup requires webhooks:read and webhooks:write.
• Reauthorize if the rotating refresh token expires or is revoked.
• Deel limits API requests to five per second per organization, shared across tokens. Helios uses its standard retries for rate limits and transient errors.
• Deel retries failed webhook deliveries and can disable a subscription after repeated failures. Scheduled OAuth setup re-enables the webhook; reconnect an API-token connection to rerun setup.

See Deel's sandbox guide, webhook quickstart and rate limits.