Immigration API

Immigration cases in Deel represent the suite of visa and immigration support services offered to clients and workers through the platform. These cases help businesses manage compliance, workforce mobility, and hiring in global markets.

Deel's Immigration API allows you to create, manage, and track these cases programmatically, whether during onboarding or as a standalone process. This guide explains the business logic and requirements behind each case type so you can confidently use the Create Case API endpoint.

What Deel immigration cases cover

Deel supports a variety of immigration-related workflows for both sponsored and self-sponsored scenarios. These include:

Visa applications

• EOR Visa Applications: Sponsored by Deel, for employees hired under the Employer of Record model.
• Client-Sponsored Visas: Where the client or their entity sponsors the employee's visa.
• Self-Sponsored Visas: Supported with documentation and eligibility validation.

Work permit requests

• Standalone work permit processing for non-EOR customers.
• Support for temporary work authorization where applicable.

Global mobility support

• Relocation assistance and immigration guidance for employees moving across countries.
• Cross-border hiring compliance support in over 50 countries.

Document management

• Collection, validation, and storage of immigration documents.
• Ongoing document tracking for expiration and compliance needs.

Case management

• Tracking and monitoring of each immigration case through defined steps.
• Communication handling with clients and applicants.
• Deadline reminders and document submission workflows.

Compliance assurance

• Ensuring all immigration actions meet local legal requirements.
• Verifying work authorization before employment begins.

Business expansion support

• Facilitating hiring in new or complex international markets.
• Streamlining visa processes to enable faster onboarding.

Before you begin

Prepare the following information before calling the Immigration API:

• A valid token to authenticate your requests
• The country code from the Get countries endpoint. This code is used to specify the country

The Immigration API helps manage your workforce's immigration processes by providing endpoints for creating and managing immigration cases. The endpoint allows you to:

• Manage immigration cases
• Track case status updates using webhooks
• Manage documents

Manage immigration cases

Create a new immigration case

Use the Create immigration case endpoint to initiate a new immigration case for your workforce. There is a subtle difference of parameters between the different types of cases, so make sure to check the table below for the required parameters

The following types of immigration cases can be created:

• Right to work: A visa application where Deel's immigration team reviews an employee's legal eligibility to work in a specific country. This ensures legal compliance.
• EOR (Employer of Record) visa application: A visa application where Deel sponsors the visa. The applicant is employed by Deel, and Deel is responsible for documentation and compliance.
• Sponsored visa application: A visa application where the client’s entity sponsors the visa. Deel facilitates the Visa application process using the client's entity.
• Business visa application: A visa application for short-term business travel, where Deel supports obtaining authorization for activities such as meetings or conferences, ensuring compliance with local immigration rules.

Creating a case for different case types

All immigration case types are created using the same API endpoint:
Create Immigration Case API

When calling this API, the case_type you choose will determine which fields are required and how the system processes the request.

Before using the API:

• Confirm that the contract type and contract status are compatible with the selected case_type
• Review the individual case type sections below for:
  • Business rules
  • Prerequisites
  • Supported workflows
• Refer to the API Reference for:
  • Field-level documentation
  • Sample request payloads

When calling this API, the case_type you choose will determine which fields are required and how the system processes the request.

Case type: EOR_VISA

This case type is used for visa cases for Deel EOR (Employer of Record) contracts.

Summary

Created when onboarding a new EOR employee or supporting existing ones. The case includes following processes:

• Eligibility check
• Visa application
• Document review and validation

Prerequisites

• An EOR contract must exist. Create Contract
• Visa type should be provided from one of the supported visas of the hiring country. (Optional) Get Visa Types

Case creation constraints:
If the employee has not completed onboarding on the Deel platform, only one immigration case can be created at a time.
If the employee has completed onboarding, multiple immigration cases can be created as needed.

Contract compatibility

Case type: RIGHT_TO_WORK

This case type is used for compliance-driven validation of an individual’s legal right to work in a specific country.

Summary

This case type is created during employee onboarding or when an existing work authorization document is expiring. It is particularly applicable when the employee's contract country differs from their nationality, and they already possess a visa.
The purpose of this case is to:

• Review provided visa or documentation
• Validate legal work eligibility based on destination country compliance standards

Prerequisites

• A contract must exist (direct/contractor/EOR). Create Contract

Contract compatibility

Case type: SPONSORED_VISA

This case type is used for visa cases sponsored by the employer or client via their own entity (not Deel).

Summary

This case type supports scenarios where Deel is not the visa sponsor. Instead, the client's internal entity handles sponsorship. The case includes following processes:

• Eligibility check
• Visa application
• Document review and validation

Prerequisites

• A contract must exist and be of type contractor or direct.
• A valid entity must exist.
• Visa type should be provided from one of the supported visas of the hiring country. (Optional) Get Visa Types

Contract compatibility

Case type: BUSINESS_VISA

This case type is used to obtain authorization for short-term business travel in a foreign country.

Summary

This case type is typically created after completing a business visa assessment. The assessment determines eligibility and requirements based on the destination country and the intended business purpose of travel. You can run this assessment using the Get business visa eligibility and requirements endpoint.

Once the assessment is complete, create the case using the returned visa_type_id.

Prerequisites

• Either a contract or a team must exist. If you don't have a contract, you can still create the business visa case by providing team_id and employee_details.
  • Use the Create Contract endpoint to create a contract if needed.
  • Use the Get Team endpoint to retrieve an existing team.
• You must provide
  • visa_type_id
  • travel_information
  • team_id only if contract_id is not included
  • employee_details
    • citizenships: always required
    • residence: always required
    • first_name: only if contract_id is not included
    • last_name: only if contract_id is not included
    • email: only if contract_id is not included

Contract Compatibility

Retrieve an immigration case

You can use the Get immigration case endpoint to return immigration case information.
The endpoint supports several types of cases.

To retrieve an immigration case, make a GET request to the endpoint.

Retrieving an immigration case

All immigration case types can be retrieved using this API endpoint:
Get Immigration Case API

Track case status updates using webhooks

The Immigration API provides a dedicated webhook event to receive updates on the status of immigration cases.

Event: immigration.case.process.status.update

This event notifies your system when an immigration case or a process within a case has been updated.

For more details on webhook setup and security, visit the Webhooks Guide.

The immigration.case.process.status.update event returns a payload with the following information:

{
  "id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
  "status": "Open",
  "case_type": "Right To Work",
  "visa_type": "B-1",
  "country_code": "US",
  "process": {
    "id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
    "name": "Work Authorization Verification",
    "status": "In Review"
  },
  "applicant": {
    "id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
    "external_id": "123123"
  }
}

Where:

Manage documents

This section explains how to manage documents using the endpoints provided by the Immigration API.

Get documents by ID

Retrieve document information for a specific document ID, including its status, type, and download link if available.

API reference

Get documents by ID

Get visa/document types by country

Fetch the list of supported visa or document types required for immigration cases, based on the specified country.

API reference

Get documents by ID