> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://docs.deel.wtf/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.deel.wtf/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Create an immigration case for a contract

POST https://api.letsdeel.com/rest/immigration/cases
Content-Type: application/json

Opens an eligibility check or a right to work check for the worker of one of your contracts, so Deel starts the immigration assessment without anyone using the Deel app. Use it once the contract is no longer a draft. Sending the same idempotency-key header again within 24 hours returns the first response instead of opening a second case.

 **Token scopes**: `immigration:write`

 **Beta**: this version requires the `X-Beta: true` request header and its contract may change before it is promoted to stable. It is scheduled to become stable on 2027-02-04.

Reference: https://docs.deel.wtf/api/reference/endpoints/immigration/create-case-v-2026-11-04

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.deel.training/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Headers

- `X-Beta` (enum, required, default: true) — Opts in to the beta version of this endpoint. Must be `true`.
  - Allowed values: `true`

### Body (application/json)

This endpoint expects an object.

- `data` (ImmigrationCasesPostRequestBodyContentApplicationJsonSchemaData, required) — The case to open, chosen by work_type.

## Response

### 201

The case was opened.

- `data` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaData, required)

## Errors

### 400 Bad Request Error

The case cannot be opened.

- `errors` (list of ImmigrationCasesPostResponsesContentApplicationJsonSchemaErrorsItems, optional)

### 401 Unauthorized Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 403 Forbidden Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 404 Not Found Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 500 Internal Server Error

Unexpected server error.

- `errors` (list of ImmigrationCasesPostResponsesContentApplicationJsonSchemaErrorsItems, optional)

## Types

### ImmigrationCasesPostRequestBodyContentApplicationJsonSchemaData

The case to open, chosen by work_type.

- `work_type`: `ELIGIBILITY_CHECK` (ELIGIBILITY_CHECK)
  - `contract_id` (string, required) — The contract of the worker the case is for.
  - `country` (string, required) — ISO 3166-1 alpha-2 code of the destination country.
  - `visa_category` (enum, required) — The visa category to check eligibility for.
    - Allowed values: `BUSINESS_VISA`, `WORK_PERMIT_VISA`
  - `business_trip` (ImmigrationCasesPostRequestBodyContentApplicationJsonSchemaDataOneOf0BusinessTrip, optional) — The trip to check. Required for BUSINESS_VISA, not allowed otherwise.
- `work_type`: `RIGHT_TO_WORK` (RIGHT_TO_WORK)
  - `contract_id` (string, required) — The contract of the worker the case is for.
  - `country` (string, required) — ISO 3166-1 alpha-2 code of the destination country.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaData

- `id` (string, required) — The unique identifier of the case.
- `status` (enum, required) — Current status of the case.
  - Allowed values: `OPEN`, `CLOSED`, `ON_HOLD`
- `closure` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataClosure, required, nullable) — Why the case was closed. Null while the case is not closed.
- `applicant` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataApplicant, required, nullable) — The worker the case is for.
- `case_type` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataCaseType, required) — The case type the case was opened with.
- `closed_at` (string, required, nullable) — UTC timestamp when the case was closed. Null while the case is not closed.
- `visa_type` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataVisaType, required, nullable) — The visa type of the case. Null while none is chosen.
- `work_type` (string, required) — The kind of immigration work the case covers.
- `created_at` (string, required) — UTC timestamp when the case was created.
- `updated_at` (string, required) — UTC timestamp when the case was last updated.
- `contract_id` (string, required, nullable) — The contract the case was opened for.
- `filing_type` (enum, required, nullable) — Whether the case is an initial filing, a renewal or another filing.
  - Allowed values: `INITIAL`, `RENEWAL`, `CHANGE_OF_EMPLOYER`, `REFILING`
- `full_status` (enum, required) — Status of the case including how a closed case ended.
  - Allowed values: `OPEN`, `ON_HOLD`, `CLOSED_POSITIVELY`, `CLOSED_NEGATIVELY`, `CLOSED_NEUTRALLY`
- `sponsorship` (enum, required, nullable) — Who sponsors the visa. Null when unknown or not applicable.
  - Allowed values: `DEEL`, `CLIENT`, `NO_SPONSORSHIP`
- `citizenships` (list of string, required) — ISO 3166-1 alpha-2 codes of the worker citizenships known to the case.
- `country_code` (string, required) — ISO 3166-1 alpha-2 code of the destination country.
- `reference_id` (string, required, nullable) — Human-readable reference of the case. Null for cases opened before references existed.
- `business_trip` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataBusinessTrip, required, nullable) — The business trip of a business visa case. Null for other cases.
- `contract_type` (string, required, nullable) — Type of contract behind the case, for example EOR, COR, CONTRACTOR, DIRECT_EMPLOYEE, PWAC. New values may be added.
- `is_onboarding` (boolean, required) — Whether the case is part of the worker onboarding.
- `visa_category` (enum, required, nullable) — Visa category of the case. Null when the case is not about a visa.
  - Allowed values: `BUSINESS_VISA`, `WORK_PERMIT_VISA`
- `parent_case_id` (string, required, nullable) — The case of the main applicant when this is a dependent case.
- `visa_management_fee` (ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataVisaManagementFee, required, nullable) — The 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.
- `converted_to_case_id` (string, required, nullable) — The case this case was converted into, when it was.
- `sponsoring_entity_id` (string, required, nullable) — Legal entity sponsoring the visa when the client sponsors it.
- `estimated_completion_date` (string, required, nullable) — Date the case is expected to be completed.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, optional) — The error code.
- `message` (string, optional) — Human-readable explanation of the error.

### ApiErrorRequest

- `method` (string, optional) — The HTTP method of the failed request
- `url` (string, optional) — The relative URL of the failed request
- `status` (double, optional) — The status code of the response
- `api_req_id` (string, optional) — The request ID of the failed request
- `docs` (string, optional) — A link to the official documentation for the requested endpoint resource
- `source` (string, optional) — The source handler which produced the returned error
- `code` (double, optional) — The code of the source handler which produced the returned error

### ApiError

- `message` (string, optional) — A description of the returned error
- `path` (string, optional) — The JSON path where input validation failed

### ImmigrationCasesPostRequestBodyContentApplicationJsonSchemaDataOneOf0BusinessTrip

The trip to check. Required for BUSINESS_VISA, not allowed otherwise.

- `reason` (string, required) — Why the worker travels.
- `end_date` (string, required) — Last day of the trip, not before start_date.
- `start_date` (string, required) — First day of the trip, today or later.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataClosure

Why the case was closed. Null while the case is not closed.

- `note` (string, required, nullable) — Additional details about the closure.
- `reason` (string, required, nullable) — Reason the case was closed or rejected.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataApplicant

The worker the case is for.

- `name` (string, required, nullable) — Full name of the worker.
- `worker_id` (string, required) — The unique identifier of the worker.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataCaseType

The case type the case was opened with.

- `id` (string, required) — The unique identifier.
- `name` (string, required) — The display name.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataVisaType

The visa type of the case. Null while none is chosen.

- `id` (string, required) — The unique identifier.
- `name` (string, required) — The display name.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataBusinessTrip

The business trip of a business visa case. Null for other cases.

- `reason` (string, required, nullable) — Why the worker travels.
- `end_date` (string, required, nullable) — Last day of the trip.
- `start_date` (string, required, nullable) — First day of the trip.

### ImmigrationCasesPostResponsesContentApplicationJsonSchemaDataVisaManagementFee

The 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_type` (enum, required) — The kind of visa management fee.
  - Allowed values: `FULL_IMMIGRATION_MANAGEMENT_FEE`
- `projected_amount` (double, required, nullable) — The 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.

## Examples

**Request**

```json
{
  "data": {
    "work_type": "ELIGIBILITY_CHECK",
    "contract_id": "m3k9x2p",
    "country": "DE",
    "visa_category": "WORK_PERMIT_VISA"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "8e4a849f-10e0-4052-8b58-ca75d9fc0e88",
    "status": "OPEN",
    "closure": {
      "note": "The worker no longer relocates.",
      "reason": "CLIENT_REQUEST"
    },
    "applicant": {
      "name": "Jane Doe",
      "worker_id": "a7b8c9d0-e1f2-4b3c-8d4e-5f6a7b8c9d0e"
    },
    "case_type": {
      "id": "0f3b6c8e-1d2a-4b5c-9e7f-8a9b0c1d2e3f",
      "name": "Eligibility Check"
    },
    "closed_at": "2026-10-15T09:10:00Z",
    "visa_type": {
      "id": "3c5d7e9f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "name": "EU Blue Card"
    },
    "work_type": "ELIGIBILITY_CHECK",
    "created_at": "2026-10-13T12:42:31Z",
    "updated_at": "2026-10-14T08:00:00Z",
    "contract_id": "m3k9x2p",
    "filing_type": "INITIAL",
    "full_status": "OPEN",
    "sponsorship": "DEEL",
    "citizenships": [
      "BR"
    ],
    "country_code": "DE",
    "reference_id": "IMM-000123",
    "business_trip": {
      "reason": "Quarterly planning with the Berlin team.",
      "end_date": "2026-12-10",
      "start_date": "2026-12-01"
    },
    "contract_type": "EOR",
    "is_onboarding": false,
    "visa_category": "WORK_PERMIT_VISA",
    "parent_case_id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e",
    "visa_management_fee": {
      "fee_type": "FULL_IMMIGRATION_MANAGEMENT_FEE",
      "projected_amount": 199
    },
    "converted_to_case_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "sponsoring_entity_id": "e5f6a7b8-c9d0-4e1f-aa3b-4c5d6e7f8a9b",
    "estimated_completion_date": "2027-01-15"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/immigration/cases"

payload = { "data": {
        "work_type": "ELIGIBILITY_CHECK",
        "contract_id": "m3k9x2p",
        "country": "DE",
        "visa_category": "WORK_PERMIT_VISA"
    } }
headers = {
    "X-Beta": "true",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/immigration/cases';
const options = {
  method: 'POST',
  headers: {
    'X-Beta': 'true',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"data":{"work_type":"ELIGIBILITY_CHECK","contract_id":"m3k9x2p","country":"DE","visa_category":"WORK_PERMIT_VISA"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.letsdeel.com/rest/immigration/cases"

	payload := strings.NewReader("{\n  \"data\": {\n    \"work_type\": \"ELIGIBILITY_CHECK\",\n    \"contract_id\": \"m3k9x2p\",\n    \"country\": \"DE\",\n    \"visa_category\": \"WORK_PERMIT_VISA\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Beta", "true")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.letsdeel.com/rest/immigration/cases")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Beta"] = 'true'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"work_type\": \"ELIGIBILITY_CHECK\",\n    \"contract_id\": \"m3k9x2p\",\n    \"country\": \"DE\",\n    \"visa_category\": \"WORK_PERMIT_VISA\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.letsdeel.com/rest/immigration/cases")
  .header("X-Beta", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"work_type\": \"ELIGIBILITY_CHECK\",\n    \"contract_id\": \"m3k9x2p\",\n    \"country\": \"DE\",\n    \"visa_category\": \"WORK_PERMIT_VISA\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.letsdeel.com/rest/immigration/cases', [
  'body' => '{
  "data": {
    "work_type": "ELIGIBILITY_CHECK",
    "contract_id": "m3k9x2p",
    "country": "DE",
    "visa_category": "WORK_PERMIT_VISA"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Beta' => 'true',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/immigration/cases");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Beta", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"data\": {\n    \"work_type\": \"ELIGIBILITY_CHECK\",\n    \"contract_id\": \"m3k9x2p\",\n    \"country\": \"DE\",\n    \"visa_category\": \"WORK_PERMIT_VISA\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Beta": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["data": [
    "work_type": "ELIGIBILITY_CHECK",
    "contract_id": "m3k9x2p",
    "country": "DE",
    "visa_category": "WORK_PERMIT_VISA"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/immigration/cases")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```