GuidesAPI ReferenceChangelog
Guides

Immigration API

Learn how to use the immigration API to manage your workforce's immigration processes

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

Create a new immigration case

You can use the Create immigration case endpoint to initiate a new immigration process for your workforce. The endpoint supports several types of cases including right-to-work verifications, visa applications, and pre-hire assessments. When you create a case, the system will automatically set up the required workflow based on the case type.

To create an immigration case, make a POST request to the endpoint.

curl --request POST \
     --url https://api.letsdeel.com/rest/v2/immigration/cases \
     --header 'Content-Type: application/json' \
     --header 'authorization: Bearer {token}' \
     --data '{
       "data": {
         "country_code": "US",
         "case_type": "EOR_VISA",
         "contract_id": "d3m0d3m",
         "visa_type_id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
         "team_id":"c7928dd8-3ed8-433c-b0ca-02665c182c85"
       }
     }'

In the request body:

NameRequiredTypeFormatDescriptionExample
country_codetruestring-ISO 3166-1 alpha-2 country code where the immigration case needs to be processed. This determines which country's immigration rules will apply.US
case_typetruestringenumThe type of immigration case to be created. Each type follows a different workflow and documentation requirements. For more info on available case types, see Create case.SPONSORED_VISA
contract_idtruestring-Links the immigration case to a specific employment contract. Required only for document reviews and visa applications, optional for other case types.12345
visa_type_idtruestring-The id of visa type being applied for..d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
team_idtruestringUUIDTeam that will handle the immigration case process. Required only for EOR visa applications, optional for other case types.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0

A successful response (200) returns the created immigration case details. For example:

{
  "data": {
    "status": "Open",
    "process": {
      "id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
      "process_name": "Right to Work Verification",
      "status_name": "Document Review"
    },
    "created_at": "2024-12-10T14:30:00Z",
    "updated_at": "2024-12-10T15:45:00Z",
    "closure_note": "All requirements met and visa approved",
    "closure_reason": "Completed Successfully"
  }
}

Where:

NameRequiredTypeFormatDescriptionExample
statustruestringenumThe current status of the immigration case.OPEN
process.idtruestring-A unique identifier assigned to this immigration process. Used for tracking and referencing the case.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
process.process_nametruestring-The name of the specific immigration process being followed. Indicates the type of immigration service.Right to Work Verification
process.status_nametruestring-A human-readable description of the current process stage. Indicates what step the case is in.Document Review
created_attruestringdate-timeThe timestamp when this immigration case was first created in the system.2024-12-10T14:30:00Z
updated_attruestringdate-timeThe timestamp when this immigration case was last modified.2024-12-10T15:45:00Z
closure_notefalsestring-An optional note explaining why the case was closed. Limited to 400 characters. Only present for closed cases.All requirements met and visa approved
closure_reasonfalsestring-A standardized reason code indicating why the case was closed. Only present for closed cases.Completed Successfully

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.

curl --request GET \
     --url https://api.letsdeel.com/rest/v2/immigration/cases/{case_id} \
     --header 'Authorization: Bearer {token}' \
     --header 'Accept: application/json'

In the query:

NameRequiredTypeFormatDescriptionExample
case_idtruestringUUIDThe unique identifier for the immigration case to be retrieved. Each case_id corresponds to a specific immigration process.223e4567-e89b-12d3-a456-426614174000

A successful response (200) returns the immigration case details. For example:

{
  id: "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
  status: "Open",
  case_type: "Right to Work",
  visa_type_id: "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
  country_code: "US",
  process: {
    id: "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
    name: "Awaiting Information",
    status: "In Review",
  },
  applicant: {
    id: "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
    external_id: "123123"
  },
  estimated_completion_date: "2025-01-30",
  case_created_at: "2025-01-01T12:00:00Z",
  last_update_at: "2025-01-10T15:30:00Z",
  documents: [
    {
       id: "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
       expiration_date: "2025-12-31",
       document_type: "EU Blue card", 
       status: "Approved"
    }
  ]
}

Where:

NameTypeDescriptionExample
idstringUnique identifier for the case.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
statusstringThe status of the immigration caseOpen
case_typestringThe current type of the case.Right to Work
visa_type_iduuidThe type of visa id for the case.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
country_codestringISO 3166-1 alpha-2 country code where the immigration case is being processed.US
process.idUUIDUnique identifier for the process associated with the case.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
process.namestringName of the process associated with the case.Awaiting Information
process.statusstringStatus of the process associated with the case.In Review
applicant.idUUIDUnique identifier for the applicant associated with the case.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
applicant.external_idnumberID of the applicant provided by the organization when creating a contract. Used to map the immigration case to a third-party system.123123
estimated_completion_datestringEstimated date for the case to be completed.2025-01-30
case_created_atstringTimestamp of when the case was created.2025-01-01T12:00:00Z
last_update_atstringTimestamp of the last update made to the case2025-01-10T15:30:00Z
documentsarrayArray of documents associated with the case.-
documents[].idUUIDUnique identifier for the document.d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
documents[].expiration_datestringExpiration date of the document2025-12-31
documents[].document_typestringType of the visa documentEU Blue card
documents[].statusstringStatus of the documentValid

Track case status updates using webhooks

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

For more info, visit Webhooks.

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:

NameTypeDescriptionExample
idstringUnique identifier for the id associated with the cased3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
statusstringThe status of immigration caseON HOLD
case_typestringThe current type of the case.Right to work
visa_typestringThe type of the visa for the case.Australia citizen
country_codestringCountry code associated with the caseUK
process.idUUIDUnique identifier for the process of the cased3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
process.namestringName for the process of the caseWORK_AUTHORIZATION_VERIFICATION
process.statusstringStatus for the process of the caseIn Review
applicant.idUUIDUnique identifier for applicant associated with cased3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0
applicant.external_idnumberID of the applicant provided by the organization when creating a contract. Used to map the immigration case to a third-party system.123123

Manage documents

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

Get documents by ID

The Get documents by ID endpoint retrieves document information for a specific document ID. This endpoint is useful for accessing details about a document, including its status, type, and a download link if available.

curl --request GET \
     --url https://api.letsdeel.com/rest/v2/immigration/documents/{id} \
     --header 'Authorization: Bearer {token}' \
     --header 'Accept: application/json'

In the path:

NameRequiredTypeDescriptionExample
idtruestringThe unique identifier for the document to fetchd3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0

A successful response (200) returns the document details:

{
  "id": "d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
  "expiration_date": "2025-12-31",
  "document_type": "Eu Blue card",
  "status": "Approved",
  "download_link": ["https://example.com/documents/doc_12345/download"]
}

Where:

NameTypeDescriptionExample
idstringUnique identifier for the documentdoc_12345
expiration_datestringExpiration date of the document in YYYY-MM-DD format2025-12-31
document_typestringType of the visa documentEU Blue card
statusstringStatus of the documentAPPROVED
download_linkarrayURLs to download the document if applicablehttps://example.com/documents/doc_12345/download

Get document types by country code

The Get document types by country code endpoint returns visa types list for a country.

To retrieve the document types for a specific country, make a GET request to the endpoint.

curl --request GET \
     --url https://api.letsdeel.com/rest/v2/immigration/document-types/{countryCode} \
     --header 'Authorization: Bearer {token}' \
     --header 'Accept: application/json'

In the path:

NameRequiredTypeDescriptionExample
countryCodetruestringThe country code for which the visa types are to retrievedUS

A successful response (200) returns the visa types list for the country. For example:

{
  "data": [
    {
      "type": "H1B",
      "description": "Specialty Occupation Visa"
    },
    {
      "type": "L1",
      "description": "Intracompany Transfer Visa"
    }
  ]
}

Where:

NameTypeDescriptionExample
typestringVisa typeH1B
descriptionstringDescription of the visa typeSpecialty Occupation Visa