Deel SDK: get started

Use an ordinary App for payroll software, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Install

npm install @alter-ai/sdk @alter-ai/deel
# Python (installs core automatically)
pip install alter-sdk-deel

The provider package includes only Deel types and response schemas and pins its contract version.

Connect and call

Configure Deel OAuth, request the scopes the application needs, and retain each customer’s grant ID after Connect consent. Alter supplies the bearer token and the OAuth application’s required x-client-id; neither belongs in operation input. The connection determines production or sandbox routing.

import { App } from "@alter-ai/sdk";
import { DeelIntegration } from "@alter-ai/deel";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const deel = new DeelIntegration(app, { grantId: process.env.DEEL_GRANT_ID! });
  const result = await (await deel.contracts.getContracts({})).wait();
  console.log(result.bodyJson());
} finally {
  await app.close();
}

from alter_sdk import App
from alter_sdk_deel import DeelIntegration

async def list_contracts(api_key: str, grant_id: str):
    async with App(api_key=api_key) as app:
        deel = DeelIntegration(app, {"grant_id": grant_id})
        call = await deel.contracts.get_contracts({})
        result = await call.wait()
        return result.body_json()

Complete versioned contract

Contract 2026-10-27 contains all 520 operations in Deel’s complete official OpenAPI export, including REST and SCIM. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. Native API version headers are pinned in the published contract. Contract 2026-10-27 ships in provider SDK 0.3.2: listing a contract’s amendments now requires only contracts:read, as Deel’s document declares, and Deel’s updated response models are published. Contract 2026-10-26 (SDK 0.2.0) made ats.listApplicationFeedbacks / ats.list_application_feedbacks require headers: {"X-Beta": "true"}, matching Deel’s upstream requirement. The 2026-10-26 and 2026-10-21 contracts remain available for existing clients and pending approvals. The Developer Portal provider view and alter integrations operations deel --version 2026-10-27 also expose the schemas.

Generated calls pin the Alter contract and the operation’s X-Version. Beta operations retain their explicitly documented X-Beta input; inclusion does not grant beta access. Deel’s product, role, scope, subscription and partner approval requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

alter integrations execute deel deel.contracts_getcontracts \
  --version 2026-10-27 --grant "$DEEL_GRANT_ID" --input '{}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters use repeated keys. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

Uploads and approvals

Every binary input is a JSON object with filename, content_type, and content_base64. Fields documented to accept multiple files also accept an array of those objects. Keep the OpenAPI’s input shape, including body.data where present; Alter converts it to Deel’s flat multipart fields and repeats file part names for multiple attachments. Structured non-file parts use OpenAPI’s JSON media type. The official CLI confirms flat fields; these structured-part semantics require provider-side smoke verification before relying on a particular upload workflow.

The shared proxy accepts up to 5 MiB of serialized input and encoded upload data. Base64 adds overhead, so accepted file bytes are smaller than that ceiling; this also applies to Deel endpoints that advertise a larger provider limit. Approval pages show file names, media types, byte lengths and SHA-256 digests, alongside the exact semantic fields. They do not render base64 as document contents. Approval execution uses the frozen input and original contract, rechecks current authority, and does not replay an uncertain write automatically.

Maintenance

The pinned official source, source hash, generated methods and policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions must remain available for installed SDKs and pending approvals.

Sandbox endpoints follow Deel’s partner guide; OAuth’s client header follows its OAuth documentation. Use separate sandbox credentials. Live provider approval and credentials remain required for a real Deel connection.

Policy and sensitive data

Every write has an explicit reviewed method/path family entry in the provider input; unreviewed new writes fail generation. Bank and payout changes, invoice adjustments, payment settings, billing terms and compensation changes include payment; contract invitations include send. Access/session/role management includes admin.

Five operations leave the caller holding a Deel credential, so Alter refuses them by default on every connection with credential_minting_refused, before any call reaches Deel (at the documented path and at its /rest/v2/... spelling):

Operation	TypeScript	Python	What the caller would hold
deel.consent_createconsenttoken_v2026_01_01	consent.createConsentToken	consent.create_consent_token	a JWT consent token that authorizes third-party service connections on the organization’s behalf until it expires
deel.organizations_createorganizationchild	organizations.createOrganizationChild	organizations.create_organization_child	the new child organization’s permanent API token, returned once
deel.organizations_createchildorgsessiontoken_v2026_07_14	organizations.createChildOrgSessionToken	organizations.create_child_org_session_token	a 6-hour session token that authenticates as the child organization
deel.workersession_createworkeraccesstoken_v2026_01_01	workerSession.createWorkerAccessToken	worker_session.create_worker_access_token	a worker access token for Deel’s worker-side API endpoints
deel.eorworkermailboxes_changepassword	eorWorkerMailboxes.changePassword	eor_worker_mailboxes.change_password	the EOR worker mailbox password the caller sets

The methods stay in the SDK. An organization admin who needs one allows it with a credential_minting rule naming provider deel and the operation, outright or behind an approval; see Allow an operation that hands over a credential:

echo '{
  "mode": "allow",
  "provider": "deel",
  "operations": ["deel.workersession_createworkeraccesstoken_v2026_01_01"]
}' | alter policy rules create --type credential_minting --agent <agent-id> \
    --body - --name "Worker portal job mints worker tokens" --yes

Managed Deel body capture is disabled because HR/payroll responses and errors can contain bank or tax identities. Metadata audit remains available. Bank/IBAN/account/ routing, tax and personal identifiers, passport numbers, passwords and upload secrets cannot be retained in frozen approvals, including sensitive headers. Provider-held references and immediately authorized execution remain available.

Identity-verification document scans, ID photos, selfies, proof-of-residence uploads and immigration document contents are refused before approval freezing, even though ordinary upload cards display only file metadata. For KYB document uploads, only ARTICLES_OF_INCORPORATION, CERTIFICATE_OF_GOOD_STANDING and PROOF_OF_AUTHORITY can be retained; personal identity, banking, beneficial-owner, missing and unknown document types are refused. These safeguards apply to typed and raw catalogued requests, and sensitive input is withheld on existing cards.

Managed calls require the OAuth client identity matching their connection environment. Existing generic API requests retain their prior connection behavior.

Fault detection follows the pinned Deel successful-response schemas: failed amendment deletion, onboarding delay or document upload (success: false), job-scope validation errors, and time-off items with review errors. Ordinary errors use HTTP error statuses, as described in Deel’s error handling. A QuickBooks Fault field is not treated as a Deel error envelope.

Resume after a restart

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Rules for SDK functions

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations <provider>. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged.

A raw call can share an endpoint with several SDK functions. It matches all of those function IDs: a deny or approval rule naming any one of them applies. A function name never grants permission or bypasses existing restrictions; Alter’s policy rules only narrow access and do not accept an allow effect. The portal’s operation picker lists searchable SDK names grouped by product, alongside the existing catalog operations. alter providers operations list shows the functions covered by each catalog operation.

For example, this rule requires approval for deel.adjustments_createcontractadjustment:

{
  "effect": "require_approval",
  "when": { "operation": "deel.adjustments_createcontractadjustment" },
  "approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.