Skip to content

Deel: Create an immigration case for a contract

Deel immigration.createCase: arguments, response, policy and SDK examples.

← Immigration operations · Get started

Operation deel.immigration_createcase_v2026_11_04

Provider route: POST /immigration/cases. Alter supplies the connection’s credentials and routing.

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["immigration"]["createCase"]>[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.immigration.createCase(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from 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.immigration.create_case(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
headersobjectRequired within parentAdditional keys: not allowed
headers.X-BetastringRequired within parentDefault: true
One of: true
bodyobjectOptional
body.dataModelRequired within parentExpand Create an immigration case for a contract — request body — body data
The case to open, chosen by work_type.

Referenced models: Create an immigration case for a contract — request body — body data

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Create an immigration case for a contract — 201 response body

Referenced models: Create an immigration case for a contract — 201 response body

1 more schema is linked from the tables above, on the schema pages.

Create an immigration case for a contract — request body — body data
FieldTypePresenceDescription and constraints
$JSONRootThe case to open, chosen by work_type.
discriminator: {"propertyName": "work_type"}
$ (oneOf 1)objectAlternativeOpens an eligibility check for a work permit or a business visa.
$ (oneOf 1).business_tripModelOptionalExpand Create an immigration case for a contract — request body — body / data / visa_category: BUSINESS VISA, WORK PERMIT VISA, work type: ELIGIBILITY CHECK business trip
The trip to check. Required for BUSINESS_VISA, not allowed otherwise.
$ (oneOf 1).contract_idstringRequired within parentThe contract of the worker the case is for.
Maximum length: 50
Pattern: ^[A-Za-z0-9_-]+$
$ (oneOf 1).countrystringRequired within parentISO 3166-1 alpha-2 code of the destination country.
Maximum length: 2
$ (oneOf 1).visa_categorystringRequired within parentThe visa category to check eligibility for.
One of: BUSINESS_VISA, WORK_PERMIT_VISA
$ (oneOf 1).work_typestringRequired within parentDiscriminator value: ELIGIBILITY_CHECK
One of: ELIGIBILITY_CHECK
$ (oneOf 2)objectAlternativeOpens a right to work check with the worker's nationality from the contract.
$ (oneOf 2).contract_idstringRequired within parentThe contract of the worker the case is for.
Maximum length: 50
Pattern: ^[A-Za-z0-9_-]+$
$ (oneOf 2).countrystringRequired within parentISO 3166-1 alpha-2 code of the destination country.
Maximum length: 2
$ (oneOf 2).work_typestringRequired within parentDiscriminator value: RIGHT_TO_WORK
One of: RIGHT_TO_WORK

Referenced models: Create an immigration case for a contract — request body — body / data / visa_category: BUSINESS VISA, WORK PERMIT VISA, work type: ELIGIBILITY CHECK business trip

Create an immigration case for a contract — 201 response body
FieldTypePresenceDescription and constraints
$objectRoot
dataModelRequired within parentExpand Create an immigration case for a contract — 201 response body — data

Referenced models: Create an immigration case for a contract — 201 response body — data

Create an immigration case for a contract — request body — body / data / visa_category: BUSINESS VISA, WORK PERMIT VISA, work type: ELIGIBILITY CHECK business trip
FieldTypePresenceDescription and constraints
$objectRootThe trip to check. Required for BUSINESS_VISA, not allowed otherwise.
end_datestringRequired within parentLast day of the trip, not before start_date.
Format: date
reasonstringRequired within parentWhy the worker travels.
Maximum length: 250
Minimum length: 1
start_datestringRequired within parentFirst day of the trip, today or later.
Format: date
Create an immigration case for a contract — 201 response body — data case type
FieldTypePresenceDescription and constraints
$objectRootThe case type the case was opened with.
idstringRequired within parentThe unique identifier.
namestringRequired within parentThe display name.
Create an immigration case for a contract — 201 response body — data visa type id, name
FieldTypePresenceDescription and constraints
$objectRootThe visa type of the case. Null while none is chosen.
idstringRequired within parentThe unique identifier.
namestringRequired within parentThe display name.
Create an immigration case for a contract — 201 response body — data applicant The worker the case is for
FieldTypePresenceDescription and constraints
$objectRootThe worker the case is for.
nameJSONRequired within parent
name (anyOf 1)stringAlternativeFull name of the worker.
name (anyOf 2)nullAlternativeFull name of the worker.
worker_idstringRequired within parentThe unique identifier of the worker.
Create an immigration case for a contract — 201 response body — data business trip end date, reason, start date
FieldTypePresenceDescription and constraints
$objectRootThe business trip of a business visa case. Null for other cases.
end_dateJSONRequired within parent
end_date (anyOf 1)stringAlternativeLast day of the trip.
Format: date
end_date (anyOf 2)nullAlternativeLast day of the trip.
Format: date
reasonJSONRequired within parent
reason (anyOf 1)stringAlternativeWhy the worker travels.
reason (anyOf 2)nullAlternativeWhy the worker travels.
start_dateJSONRequired within parent
start_date (anyOf 1)stringAlternativeFirst day of the trip.
Format: date
start_date (anyOf 2)nullAlternativeFirst day of the trip.
Format: date
Create an immigration case for a contract — 201 response body — data closure note, reason
FieldTypePresenceDescription and constraints
$objectRootWhy the case was closed. Null while the case is not closed.
noteJSONRequired within parent
note (anyOf 1)stringAlternativeAdditional details about the closure.
note (anyOf 2)nullAlternativeAdditional details about the closure.
reasonJSONRequired within parent
reason (anyOf 1)stringAlternativeReason the case was closed or rejected.
reason (anyOf 2)nullAlternativeReason the case was closed or rejected.
Create an immigration case for a contract — 201 response body — data / visa_management_fee / fee_type: FULL IMMIGRATION MANAGEMENT FEE
FieldTypePresenceDescription and constraints
$objectRootThe monthly visa management fee that applies to the case after it is completed. Null when no fee applies to the case or it could not be determined.
fee_typestringRequired within parentThe kind of visa management fee.
Known values: FULL_IMMIGRATION_MANAGEMENT_FEE
projected_amountJSONRequired within parent
projected_amount (anyOf 1)JSONAlternative
projected_amount (anyOf 1) (anyOf 1)numberAlternativeThe projected monthly fee in USD from the organization pricing. Null when the case does not carry a monthly fee or the organization has no pricing for it.
Format: double
projected_amount (anyOf 1) (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
projected_amount (anyOf 2)nullAlternativeThe projected monthly fee in USD from the organization pricing. Null when the case does not carry a monthly fee or the organization has no pricing for it.
Format: double

SDK function policy ID: deel.immigration_createcase_v2026_11_04. Catalog operation: immigration_createcase_v2026_11_04. 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: ["immigration:write"]

Pinned headers: {"X-Version": "2026-11-04"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.