Immigration API

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

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:

Name	Required	Type	Format	Description	Example
`country_code`	true	string	-	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_type`	true	string	enum	The 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_id	true	string	-	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_id`	true	string	-	The id of visa type being applied for..	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`team_id`	true	string	UUID	Team 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:

Name	Required	Type	Format	Description	Example
`status`	true	string	enum	The current status of the immigration case.	`OPEN`
`process.id`	true	string	-	A unique identifier assigned to this immigration process. Used for tracking and referencing the case.	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`process.process_name`	true	string	-	The name of the specific immigration process being followed. Indicates the type of immigration service.	`Right to Work Verification`
`process.status_name`	true	string	-	A human-readable description of the current process stage. Indicates what step the case is in.	`Document Review`
`created_at`	true	string	date-time	The timestamp when this immigration case was first created in the system.	`2024-12-10T14:30:00Z`
`updated_at`	true	string	date-time	The timestamp when this immigration case was last modified.	`2024-12-10T15:45:00Z`
`closure_note`	false	string	-	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_reason`	false	string	-	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:

Name	Required	Type	Format	Description	Example
`case_id`	true	string	UUID	The 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:

Name	Type	Description	Example
`id`	string	Unique identifier for the case.	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`status`	string	The status of the immigration case	`Open`
`case_type`	string	The current type of the case.	Right to Work
`visa_type_id`	uuid	The type of visa id for the case.	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`country_code`	string	ISO 3166-1 alpha-2 country code where the immigration case is being processed.	`US`
`process.id`	UUID	Unique identifier for the process associated with the case.	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`process.name`	string	Name of the process associated with the case.	`Awaiting Information`
`process.status`	string	Status of the process associated with the case.	`In Review`
`applicant.id`	UUID	Unique identifier for the applicant associated with the case.	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`applicant.external_id`	number	ID 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_date`	string	Estimated date for the case to be completed.	`2025-01-30`
`case_created_at`	string	Timestamp of when the case was created.	`2025-01-01T12:00:00Z`
`last_update_at`	string	Timestamp of the last update made to the case	`2025-01-10T15:30:00Z`
`documents`	array	Array of documents associated with the case.	-
`documents[].id`	UUID	Unique identifier for the document.	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`documents[].expiration_date`	string	Expiration date of the document	`2025-12-31`
`documents[].document_type`	string	Type of the visa document	`EU Blue card`
`documents[].status`	string	Status of the document	`Valid`

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:

Name	Type	Description	Example
`id`	string	Unique identifier for the id associated with the case	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`status`	string	The status of immigration case	`ON HOLD`
`case_type`	string	The current type of the case.	`Right to work`
`visa_type`	string	The type of the visa for the case.	`Australia citizen`
`country_code`	string	Country code associated with the case	`UK`
`process.id`	UUID	Unique identifier for the process of the case	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`process.name`	string	Name for the process of the case	`WORK_AUTHORIZATION_VERIFICATION`
`process.status`	string	Status for the process of the case	`In Review`
`applicant.id`	UUID	Unique identifier for applicant associated with case	`d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0`
`applicant.external_id`	number	ID 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:

Name	Required	Type	Description	Example
`id`	true	string	The unique identifier for the document to fetch	`d3m0d3m0-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:

Name	Type	Description	Example
`id`	string	Unique identifier for the document	`doc_12345`
`expiration_date`	string	Expiration date of the document in `YYYY-MM-DD` format	`2025-12-31`
`document_type`	string	Type of the visa document	`EU Blue card`
`status`	string	Status of the document	`APPROVED`
`download_link`	array	URLs to download the document if applicable	`https://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:

Name	Required	Type	Description	Example
`countryCode`	true	string	The country code for which the visa types are to retrieved	`US`

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:

Name	Type	Description	Example
`type`	string	Visa type	`H1B`
`description`	string	Description of the visa type	`Specialty Occupation Visa`