> 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://developer.deel.com/api/stable/llms.txt

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

# Get the worker onboarding case

GET https://api.letsdeel.com/rest/immigration/workers/cases/onboarding

Retrieves the newest onboarding immigration case of the worker behind the token. Use it to find the case that must be completed before the worker can start.

 **Token scopes**: `worker:read`

 **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-10.

Reference: https://developer.deel.com/api/reference/endpoints/immigration/get-worker-onboarding-case-v-2026-11-10

## 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.letsdeel.com/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

### Query parameters

- `contract_id` (string, optional) — Only the onboarding case of this contract.

### Headers

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

## Response

### 200

Successful response with the onboarding case, or an empty object.

- `data` (ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaData, required) — The onboarding case, or an empty object when the worker has none.

## Errors

### 400 Bad Request Error

Operation failed.

- `errors` (list of ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaErrorsItems, 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

Operation failed.

- `errors` (list of ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaErrorsItems, optional)

## Types

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaData

The onboarding case, or an empty object when the worker has none.

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

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaErrorsItems

- `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

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaDataClosure

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.

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaDataApplicant

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.

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaDataCaseType

The case type the case was opened with.

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

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaDataVisaType

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

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

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaDataBusinessTrip

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.

### ImmigrationWorkersCasesOnboardingGetResponsesContentApplicationJsonSchemaDataVisaManagementFee

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

**Response**

```json
{
  "data": {
    "id": "8e4a849f-10e0-4052-8b58-ca75d9fc0e88",
    "status": "OPEN",
    "closure": {
      "note": "The worker no longer relocates.",
      "reason": "CONTRACT_CANCELLED"
    },
    "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/workers/cases/onboarding"

querystring = {"contract_id":"m3k9x2p"}

headers = {
    "X-Beta": "true",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/immigration/workers/cases/onboarding?contract_id=m3k9x2p';
const options = {method: 'GET', headers: {'X-Beta': 'true', Authorization: 'Bearer <token>'}};

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"
	"net/http"
	"io"
)

func main() {

	url := "https://api.letsdeel.com/rest/immigration/workers/cases/onboarding?contract_id=m3k9x2p"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Beta", "true")
	req.Header.Add("Authorization", "Bearer <token>")

	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/workers/cases/onboarding?contract_id=m3k9x2p")

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

request = Net::HTTP::Get.new(url)
request["X-Beta"] = 'true'
request["Authorization"] = 'Bearer <token>'

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.get("https://api.letsdeel.com/rest/immigration/workers/cases/onboarding?contract_id=m3k9x2p")
  .header("X-Beta", "true")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.letsdeel.com/rest/immigration/workers/cases/onboarding?contract_id=m3k9x2p', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Beta' => 'true',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/immigration/workers/cases/onboarding?contract_id=m3k9x2p");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Beta", "true");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Beta": "true",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/immigration/workers/cases/onboarding?contract_id=m3k9x2p")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```