> 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. # List immigration cases GET https://api.letsdeel.com/rest/immigration/cases Lists the immigration cases the token can see, newest first. Use it to track the progress of your workers' cases or to find a case before reading its timeline or documents. **Token scopes**: `immigration:read`, `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/list-cases-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 - `work_types` (list of enum, optional) — Only cases of these work types. - Allowed values: `ELIGIBILITY_CHECK`, `VISA_APPLICATION`, `RIGHT_TO_WORK`, `IMMIGRATION_SERVICE` - `statuses` (list of enum, optional) — Only cases in these statuses. - Allowed values: `OPEN`, `CLOSED`, `ON_HOLD` - `countries` (list of string, optional) — Only cases in these destination countries (ISO 3166-1 alpha-2). - `search` (string, optional) — Matches the worker name, a contract id or a case reference. - `cursor` (string, optional) — Opaque pagination cursor returned as next_cursor from a previous response. Omit to fetch the first page. - `limit` (integer, optional, default: 20) — Maximum number of cases to return. Capped at 100. ### 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 cases. - `data` (list of ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItems, required) - `has_more` (boolean, required) — Whether more items are available beyond this page. - `next_cursor` (string, required, nullable) — Cursor to pass as cursor to fetch the next page. Null when there is no next page. - `total_count` (integer, required, nullable) — Number of matching cases, capped at 1000. Only on the first page; null when a cursor is sent. ## Errors ### 400 Bad Request Error Operation failed. - `errors` (list of ImmigrationCasesGetResponsesContentApplicationJsonSchemaErrorsItems, 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 ImmigrationCasesGetResponsesContentApplicationJsonSchemaErrorsItems, optional) ## Types ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItems - `id` (string, required) — The unique identifier of the case. - `status` (enum, required) — Current status of the case. - Allowed values: `OPEN`, `CLOSED`, `ON_HOLD` - `closure` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsClosure, required, nullable) — Why the case was closed. Null while the case is not closed. - `timeline` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimeline, required) — The processes, steps and client or employee actions of the case, as the Get case timeline endpoint returns them. - `applicant` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsApplicant, required, nullable) — The worker the case is for. - `case_type` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsCaseType, 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` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsVisaType, 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` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsBusinessTrip, 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` (ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsVisaManagementFee, 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. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaErrorsItems - `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 ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsClosure 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. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimeline The processes, steps and client or employee actions of the case, as the Get case timeline endpoint returns them. - `processes` (list of ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimelineProcessesItems, required) — Processes of the case in order. - `ongoing_actions` (integer, required) — Number of actions currently waiting on the client or the employee. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsApplicant 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. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsCaseType The case type the case was opened with. - `id` (string, required) — The unique identifier. - `name` (string, required) — The display name. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsVisaType The visa type of the case. Null while none is chosen. - `id` (string, required) — The unique identifier. - `name` (string, required) — The display name. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsBusinessTrip 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. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsVisaManagementFee 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. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimelineProcessesItems - `id` (string, required) — The unique identifier of the process. - `name` (string, required) — Display name of the process. - `state` (enum, required) — Whether the process is not started, active or completed. - Allowed values: `ACTIVE`, `COMPLETED`, `NOT_STARTED` - `steps` (list of ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimelineProcessesItemsStepsItems, required) — Steps of the process in order. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimelineProcessesItemsStepsItems - `id` (string, required) — The unique identifier of the step. - `name` (string, required) — Display name of the step. - `state` (enum, required) — Whether the step is not started, active or completed. - Allowed values: `ACTIVE`, `COMPLETED`, `NOT_STARTED` - `actions` (list of ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimelineProcessesItemsStepsItemsActionsItems, required) — Actions attached to the step, earliest due first. - `activated_at` (string, required, nullable) — UTC timestamp when the step became active. Null while the step has not started. - `completed_at` (string, required, nullable) — UTC timestamp when the step was completed. Null while the step is open. ### ImmigrationCasesGetResponsesContentApplicationJsonSchemaDataItemsTimelineProcessesItemsStepsItemsActionsItems - `id` (string, required, nullable) — The unique identifier of the action. - `name` (string, required, nullable) — Short title of the action. - `type` (enum, required) — The kind of action expected from the assigned party. - Allowed values: `FILL_FORM`, `REVIEW_REOPENED_FORM`, `DOWNLOAD_BUSINESS_LETTER`, `AGENT_REVIEW_BUSINESS_LETTER`, `CLIENT_REVIEW_BUSINESS_LETTER`, `GENERATE_BUSINESS_VISA_LETTER`, `AGENT_REVIEW`, `CLIENT_REVIEW_DOCUMENT`, `AGENT_STATUS_UPDATE`, `QUOTE_CREATE`, `QUOTE_DRAFT`, `QUOTE_APPROVAL`, `QUOTE_PAYMENT_REQUEST`, `QUOTE_REJECTED`, `QUOTE_APPROVAL_EMPLOYEE`, `UPLOAD_DOCUMENT`, `UPLOAD_ADDITIONAL_DOCUMENT`, `FILL_ADDITIONAL_FORM`, `AGENT_ADD_SALESFORCE_URL`, `AGENT_STATUS_UPDATE_SLA_BREACH`, `FILL_REQUIRED_ROLES`, `REVIEW_SUBMITTED_FORM`, `REVIEW_FORM`, `REVIEW_UPLOADED_DOCUMENT`, `REVIEW_ZENDESK_COMMENT`, `SIGNATURE_PENDING`, `PETITION_AI_REVIEW`, `AMENDMENT_DETAIL_REVIEW`, `REVIEW_GOOGLE_DOCUMENT`, `PAY_INVOICE_ACTION`, `ESTIMATED_COMPLETION`, `REVIEW_VENDOR_ASSIGNMENT`, `UPDATE_VISA_TYPE`, `CUSTOM_TASK`, `AGENT_ADD_USCIS_RECEIPT_NUMBER`, `AGENT_ADD_SHIPPING_NUMBER`, `IDENTITY_VERIFICATION`, `IDENTITY_VERIFICATION_VERIFF`, `IDENTITY_VERIFICATION_REVIEW`, `SEND_VISA_APPLICATION_QUOTE`, `REVIEW_VISA_APPLICATION_QUOTE`, `COMPLIANCE_VERIFF`, `RTW_VERIFICATION_DOCUMENT_REVIEW`, `UPLOAD_REQUIRED_DOCUMENT`, `REVIEW_REQUIRED_DOCUMENT`, `ADD_BUSINESS_VISA_DETAILS`, `ADD_UK_SHARECODE`, `RUN_AI_AGENT`, `REVIEW_VISA_AUTOMATION_PAYLOAD`, `PRE_HIRE_DOCUMENT_REVIEW`, `ACKNOWLEDGE_CONTENT`, `PETITION_AUTONOMOUS_BUILD`, `PAY_MILESTONE_INVOICE`, `AGENT_ADD_RFE_DEADLINE` - `status` (enum, required, nullable) — Progress of the action. - Allowed values: `TODO`, `ONGOING`, `COMPLETED`, `ARCHIVED` - `due_date` (string, required, nullable) — UTC timestamp by which the action is expected to be completed. - `user_type` (enum, required) — The party expected to complete the action: the client organization or the employee. - Allowed values: `CLIENT`, `APPLICANT` - `description` (string, required) — What the assigned party has to do. - `completed_at` (string, required, nullable) — UTC timestamp when the action was completed. Null while the action is open. ## Examples **Response** ```json { "data": [ { "id": "8e4a849f-10e0-4052-8b58-ca75d9fc0e88", "status": "OPEN", "closure": { "note": "The worker no longer relocates.", "reason": "CONTRACT_CANCELLED" }, "timeline": { "processes": [ { "id": "c7b8c9d0-e1f2-4b3c-8d4e-5f6a7b8c9d0a", "name": "Eligibility Check", "state": "ACTIVE", "steps": [ { "id": "023ceb91-30ab-40d7-bd34-c7b9d96cfd14", "name": "In Review", "state": "ACTIVE", "actions": [ { "id": "9b33c0a2-e85e-4977-b57f-4b2afd291eed", "name": "Upload additional documents", "type": "UPLOAD_ADDITIONAL_DOCUMENT", "status": "ONGOING", "due_date": "2026-10-14T12:42:31Z", "user_type": "CLIENT", "description": "Upload the additional supporting documents to proceed with your case.", "completed_at": "2026-10-15T09:10:00Z" } ], "activated_at": "2026-10-13T12:42:31Z", "completed_at": "2026-10-15T09:10:00Z" } ] } ], "ongoing_actions": 2 }, "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" } ], "has_more": false, "next_cursor": "eyJvZmZzZXQiOjIwfQ", "total_count": 2 } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/immigration/cases" querystring = {"countries":"[\"DE\"]","cursor":"eyJvZmZzZXQiOjIwfQ","limit":"20","search":"Jane Doe","statuses":"[\"OPEN\"]","work_types":"[\"RIGHT_TO_WORK\"]"} headers = { "X-Beta": "true", "Authorization": "Bearer " } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.letsdeel.com/rest/immigration/cases?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D'; const options = {method: 'GET', headers: {'X-Beta': 'true', Authorization: 'Bearer '}}; 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/cases?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Beta", "true") req.Header.Add("Authorization", "Bearer ") 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?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D") 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 ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.letsdeel.com/rest/immigration/cases?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D") .header("X-Beta", "true") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.letsdeel.com/rest/immigration/cases?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D', [ 'headers' => [ 'Authorization' => 'Bearer ', 'X-Beta' => 'true', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/immigration/cases?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D"); var request = new RestRequest(Method.GET); request.AddHeader("X-Beta", "true"); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Beta": "true", "Authorization": "Bearer " ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/immigration/cases?countries=%5B%22DE%22%5D&cursor=eyJvZmZzZXQiOjIwfQ&limit=20&search=Jane+Doe&statuses=%5B%22OPEN%22%5D&work_types=%5B%22RIGHT_TO_WORK%22%5D")! 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() ```