Case API

Create a New Case

POST    /v2/case

 https://immigo.cibtapis.com/v2/case

Creates a new immigration case with applicant and case details.

Endpoint

Request Body

Content-Type: application/json

Parameters

Usage notes

• All company fields hostCompany, sendingCompany, billingCompany must reference valid company records.
• The applicant object can include dependents and passport information for the primary applicant.
• The metadata object supports custom key-value pairs for tracking additional information.
• Returns the created case record with its assigned caseId.

Body (raw json)

{
    "caseType": "NewHire",
    "hostCompany": "Test company",
    "sendingCompany": "Test company",
    "billingCompany": "Test company",
    "hostCountry": "GB",
    "hostCity": "London",
    "homeCountry": "US",
    "assignmentId": "AB-12-XYZ",
    "processName": "Unspecified process",
    "payrollLocation": "S",
    "salary": "",
    "newJobTitle": "Widget Supervisor",
    "placeOfWork": "Test company",
    "authorizingPerson": "John Smith",
    "costCenter": "Manufacturing",
    "department": "Widgets",
    "billingReference": "ABC123",
    "applicant": {
        "employeeNumber": "1234",
        "firstName": "first name",
        "lastName": "last name",
        "middleName": "middle name",
        "countryOfResidence": "US",
        "countryOfBirth": "US",
        "placeOfBirth": "Washington, DC",
        "dateOfBirth": "1955-03-04",
        "gender": "M",
        "Vip": false,
        "maritalStatus": "M",
        "emailAddress": "[email protected]",
        "telephoneNumber": "555-555-1212",
        "hireDate": "",
        "currentJobTitle": "Widget Curator",
        "addressStreet1": "123 Main St.",
        "addressStreet2": "test value",
        "addressCity": "Anytown",
        "addressState": "VA",
        "addressPostalCode": "22000",
        "addressCountry": "US",
        "passports": [
            {
                "country": "US",
                "passportNumber": "123456",
                "expirationDate": "2025-01-01",
                "issueDate": "2015-01-01",
                "issuingAuthority": "Ntl Ppt Ctr",
                "Nationality": "US"
            }
        ],
        "dependents": [
            {
                "firstName": "spousefirstname",
                "lastName": "spuselastname",
                "relationship": "Spouse",
                "nationality": "US",
                "dateOfBirth": "1950-05-01",
                "gender": "F"
            }
        ]
    },
    "metadata": [
        {
            "tagName": "Additional Instructions",
            "value": "test value"
        }
    ]
}
 

List Cases

GET    /v2/cases/applicants/steps

https://immigo.cibtapis.com/v2/cases/applicants/steps?startDate=2023-01-01&endDate=2025-01-01&maxRecords=100&offset=1

Retrieves case steps for applicants within a specified date range, with pagination support.

Endpoint

Query Parameters

Response

 Returns a paginated array of case step records within the specified date range, including step names, statuses, dates, and associated case/applicant references.

Usage Notes

• Use offset and maxRecords for pagination through large result sets.
• This endpoint returns steps across all cases within the date range – for steps on a specific case, use /case/{caseId}/steps instead.
• Steps represent individual stages in the immigration process.
• If you send an empty offset value, pagination will be based on Cursors.
• When nextCursor or prevCursor values are returned in a response, pass them in subsequent requests to navigate pages. Cursor-based pagination is preferred over offset for large or frequently updated datasets.

Get Case By ID

GET    /v2/case/{caseId}

https://immigo.cibtapis.com/v2/case/e7KVLfQeupCyttuedvmYtYQ03U-L8AoXwzBQBa9MLfo=

Retrieves detailed information for a specific case by its unique encoded case ID.

Endpoint

Path Parameters

Response

Returns the full case record including case type, status, host/home country details, company information, applicant details, steps, and metadata.

Usage Notes

• The caseId is a Base64-encoded unique
• Returns comprehensive case details in a single
• For listing multiple cases, use the List Cases endpoint with date range filters

Get Cases for an Applicant

GET /v2/cases/applicant/id/{applicantId}

https://immigo.cibtapis.com/v2/cases/applicant/id/e7KVLfQeupCyttuedvmYtVwl76AEZb-yq7SFodTh224=

Retrieves all cases associated with an applicant identified by their unique encoded applicant ID.

Endpoint

Path Parameters

Response

Returns an array of case records associated with the specified applicant, including case details, status, and related metadata.

Usage Notes 

• Use this endpoint when you have the internal applicant
• For employee number-based case lookups, use /cases/applicant/employeenumber/{employeeNumber}

Get Cases for an Employee Number

GET    /v2/cases/applicant/employeenumber/{employeeNumber}

 https://immigo.cibtapis.com/v2/cases/applicant/employeenumber/1234

Retrieves all cases associated with an applicant identified by their employee number.

Endpoint

 Path Parameters

 Response

Returns an array of case records associated with the specified applicant, including case type, status, host/home country details, and related metadata.

Usage Notes

• Use this endpoint when you have the employee number rather than the internal applicant
• For applicant ID-based case lookups, use cases/applicant/id/{applicantId} instead.
• Returns all cases regardless of status (open, closed, pending).

Get Case Steps

GET    /v2/case/{caseId}/steps

https://immigo.cibtapis.com/v2/case/e7KVLfQeupCyttuedvmYtRawEYLMcnDpOxmXR9UG884=/steps

Retrieves all process steps for a specific case by its unique encoded case ID.

Endpoint

Path Parameters

Response

Returns an array of step records for the specified case, including step names, statuses, dates, and any associated metadata.

Usage Notes

• For bulk step retrieval across multiple cases, use cases/applicants/steps with date range filters.
• Steps represent the individual stages in the immigration process
• Each step typically includes a name, status, start date, and completion

Get Case Notes

GET /v2/cases/applicants/notes

https://immigo.cibtapis.com/v2/cases/applicants/notes?startDate=2025-01-01&endDate=2026-01-22&maxRecords=100&offset=0

Retrieves case notes for applicants within a specified date range, with pagination support.

Endpoint

Params example

Query Parameters

Response

 Returns a paginated array of case note records within the specified date range, including note content, author, timestamps, and associated case references.

Usage Notes

• Use offset and maxRecords for pagination through large result sets.
• The type parameter determines which date field is used for filtering.
• For notes on a specific case, use /case/{caseId}/notes instead.
• Notes are returned in chronological order.
• If you send an empty offset value, pagination will be based on Cursors.
• When nextCursor or prevCursor values are returned in a response, pass them in subsequent requests to navigate pages. Cursor-based pagination is preferred over offset for large or frequently updated datasets.

Get Notes for a Case

GET     /v2/case/{caseId}/notes

https://immigo.cibtapis.com/v2/case/e7KVLfQeupCyttuedvmYtU33PPDyc-7VHKFMzL_R5OI=/notes

Retrieves all notes for a specific case by its unique encoded case ID.

Endpoint

Path Parameters

Response

Returns an array of note records for the specified case, including note content, author, timestamps, and any associated metadata.

Usage Notes

• Returns all notes associated with a single case.
• For bulk note retrieval across multiple cases within a date range, use GetCaseNotes instead.
• Notes are typically returned in chronological order.

List Case Steps

GET    /v2/cases/applicants/steps

https://immigo.cibtapis.com/v2/cases/applicants/steps?startDate=2023-01-01&endDate=2025-01-01&maxRecords=100&offset=1

Retrieves case steps for applicants within a specified date range, with pagination support.

Endpoint

Query Parameters

Response

 Returns a paginated array of case step records within the specified date range, including step names, statuses, dates, and associated case/applicant references.

Usage Notes

• Use offset and maxRecords for pagination through large result sets.
• This endpoint returns steps across all cases within the date range – for steps on a specific case, use /case/{caseId}/steps instead.
• Steps represent individual stages in the immigration process.
• If you send an empty offset value, pagination will be based on Cursors.
• When nextCursor or prevCursor values are returned in a response, pass them in subsequent requests to navigate pages. Cursor-based pagination is preferred over offset for large or frequently updated datasets.

Get Health Check

GET /v2/case/health

https://immigo.cibtapis.com/v2/case/health

Performs a health check on the Case API service. Returns the current health status to verify the service is running and responsive.

Endpoint

Parameters

No path parameters, query parameters, or request body required.

Response

 Returns the health status of the Case API service, typically including service availability and uptime information.

Usage Notes

• Use this endpoint for monitoring and alerting.
• A successful response indicates the Case API service is running.