Deel: Create a new contract
Deel contracts.createIccontract: arguments, response, policy and SDK examples.
← Contracts operations · Get started
Operation deel.contracts_createiccontract
Provider route: POST /contracts. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/deel with npm, or alter-sdk-deel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { DeelIntegration } from "@alter-ai/deel";
async function execute(input: Parameters<DeelIntegration["contracts"]["createIccontract"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new DeelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.contracts.createIccontract(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_deel import DeelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = DeelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.contracts.create_iccontract(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | object | Optional | |
body.data | Model | Required within parent | Expand Create a new contract — request body — body data |
Referenced models: Create a new contract — request body — body data
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Create a new contract — 201 response body |
Referenced models: Create a new contract — 201 response body
Schemas
Section titled “Schemas”29 more schemas are linked from the tables above, on the schema pages.
Create a new contract — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a new contract — request body — body / data / platform_payment_type: STANDARD, OFF PLATFORM, type: pay as you go time based, who reports: both, client, contractor |
$ (oneOf 2) | Model | Alternative | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor |
$ (oneOf 3) | Model | Alternative | Expand Create a new contract — request body — body / data / type: payg milestones, who reports: both, client, contractor |
$ (oneOf 4) | Model | Alternative | Expand Create a new contract — request body — body / data / type: ongoing time based, who reports: both, client, contractor |
Referenced models: Create a new contract — request body — body / data / platform_payment_type: STANDARD, OFF PLATFORM, type: pay as you go time based, who reports: both, client, contractor, Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor, Create a new contract — request body — body / data / type: payg milestones, who reports: both, client, contractor, Create a new contract — request body — body / data / type: ongoing time based, who reports: both, client, contractor
Create a new contract — 201 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Create a new contract — 201 response body — data |
Referenced models: Create a new contract — 201 response body — data
Create a new contract — request body — body / data / platform_payment_type: STANDARD, OFF PLATFORM, type: pay as you go time based, who reports: both, client, contractor
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Details of contract to create |
citizenship | string or null | Optional | ISO 3166-1 alpha-2 country code of the worker's citizenship. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
client | Model | Required within parent | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client Client details for the contract, including the legal entity and team. |
compensation_details | Model | Required within parent | Expand Create a new contract — request body — body / data / type: ongoing time based, who reports: both, client, contractor compensation details Compensation and invoicing configuration for the contract. |
contract_template_id | string or null | Optional | Contract Template Id. |
country_code | string | Optional | Country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
external_id | string or null | Optional | External Id. |
job_title | Model | Optional | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title Worker's job title. You can enter a custom job title or use a pre-defined job title using the Id retrieved in job-titles endpoint. |
meta | Model | Required within parent | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor meta Additional custom info about a contract |
notice_period | number | Optional | Days before to notice the termination of contract for either party. Default: 10 Format: double Minimum: 0 |
platform_payment_type | string | Optional | Whether the contract is paid through Deel (`STANDARD`) or outside Deel (`OFF_PLATFORM`). Applies to IC contracts only. One of: STANDARD, OFF_PLATFORM |
scope_of_work | string or null | Optional | Describe the work to be performed. |
scope_of_work_id | string or null | Optional | Existing scope of work public id Format: uuid |
seniority | JSON | Optional | Job seniority level. Please use the seniority levels endpoint to retrieve the list of seniority levels. |
seniority (oneOf 1) | Model | Alternative | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor seniority id |
seniority (oneOf 2) | null | Alternative | |
special_clause | string or null | Optional | Enter any special clause you may have. |
start_date | string | Required within parent | Short date in format ISO-8601 (YYYY-MM-DD). For example: 2022-12-31. Format: date Pattern: ^\d{4}-\d{2}-\d{2}$ |
state_code | string or null | Optional | The state or province code. Use country lookup endpoint to retrieve state codes. |
termination_date | string or null | Optional | Short date in format ISO-8601 (YYYY-MM-DD). For example: 2022-12-31. Format: date Pattern: ^\d{4}-\d{2}-\d{2}$ |
title | string | Required within parent | The title of the contract. |
type | string | Required within parent | Type of contract One of: pay_as_you_go_time_based |
who_reports | string | Optional | Flag to indicate who is supposed to provide regular reports One of: both, client, contractor |
worker | JSON | Optional | Worker properties |
worker (oneOf 1) | Model | Alternative | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor worker Worker properties |
worker (oneOf 2) | null | Alternative |
Referenced models: Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client, Create a new contract — request body — body / data / type: ongoing time based, who reports: both, client, contractor compensation details, Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title, Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor meta, Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor seniority id, Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor worker Worker properties
Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Client details for the contract, including the legal entity and team. |
legal_entity | Model | Required within parent | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client legal entity Choose the Deel legal entity for this contract. Use legal entity endpoint to retrieve a list of legal entities in your organization. |
team | Model | Required within parent | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client team Choose the Deel team for this contract. Use teams endpoint to retrieve a list of teams in your organization. |
Referenced models: Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client legal entity, Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor client team
Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Worker's job title. You can enter a custom job title or use a pre-defined job title using the Id retrieved in job-titles endpoint. |
id | Model | Optional | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title id Unique identifier of this resource. |
name | string or null | Optional | Job title. Please leave it blank when entering an Id. Maximum length: 255 |
Referenced models: Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title id
Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor meta
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional custom info about a contract |
documents_required | boolean | Required within parent | Require the contractor to upload necessary compliance documents as per their country’s labor laws. |
is_main_income | boolean | Optional | Flag to indicate if the contract is the main income for the contractor. |
Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor seniority id
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Job seniority level. Please use the seniority levels endpoint to retrieve the list of seniority levels. |
id | Model | Optional | Expand Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title id Unique identifier of this resource. |
Referenced models: Create a new contract — request body — body / data / type: payg tasks, who reports: both, client, contractor job title id
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: deel.contracts_createiccontract. Catalog operation: contracts/create. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["contracts:write"]
Pinned headers: {"X-Version": "2026-01-01"}