Developer Guide

Applicant API

Applicant

Endpoints for managing applicant records in the Immigo platform. Includes operations for creating, retrieving, updating, and merging primary applicants and their dependents by employee number or applicant ID.

Auth

Authenticated Applicant API endpoints. All requests in this folder require proper authorization. Covers CRUD operations on applicants and dependents, employee number management, and health checks.

AUTHORIZATION Bearer Token

API Endpoints

Get Applicant by ID

GET /v2/applicant/{applicantId}

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

Retrieves a primary applicant record by their unique applicant ID (encoded identifier).

Endpoint

GET /v2/applicant/{applicantId}

Path Parameters

Parameter	Type	Required	Description
applicantId	string	Yes	The unique encoded identifier (Base64) of the applicant.

Response

Returns the primary applicant object including personal information, metadata, passport details, and document references.

Usage Notes

The applicantId is a Base64-encoded unique identifier, different from the employee number.
Use this endpoint when you have the internal applicant ID rather than the employee
For employee number-based lookups, use GetApplicantByEmployeeNumber instead.

Get Dependents

GET /v2/applicant/{applicantId}/dependents

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

Retrieves all dependents associated with a primary applicant, identified by the primary applicant’s unique encoded ID.

Endpoint

GET /v2/applicant/{applicantId}/dependents

Path Parameters

Parameter	Type	Required	Description
applicantId	string	Yes	The unique encoded identifier (Base64) of the primary applicant.

Response

Returns an array of dependent records associated with the specified primary applicant, each containing personal information, metadata, passport details, and document references.

Usage Notes

Use this endpoint when you have the internal applicant ID rather than the employee
For employee number-based dependent lookups, use GetDependentsByEmployeeNumber.
Returns an empty array if no dependents exist for the given applicant.

Get Dependent by ID

GET /v2/applicant/{applicantId}/dependent/{dependentId}

https://immigo.cibtapis.com/v2/applicant/e7KVLfQeupCyttuedvmYtVwl76AEZb-yq7SFodTh224=/dependent/e7KVLfQeupCyttuedvmYta8pGMDO-E645LrkPD9TZ4=

Retrieves a specific dependent record by both the primary applicant’s ID and the dependent’s unique ID.

Endpoint

GET /v2/applicant/{applicantId}/dependent/{dependentId}

Path Parameters

Parameter	Type	Required	Description
applicantId	string	Yes	The unique encoded identifier (Base64) of the primary applicant.
dependentId	string	Yes	The unique encoded identifier (Base64) of the dependent.

Response

Returns a single dependent record including personal information, metadata, passport details, and document references.

Usage Notes

Both the primary applicant ID and the dependent ID are required to uniquely identify the
Use this for retrieving a single specific dependent rather than listing all
IDs are Base64-encoded.

Save Applicant

POST /v2/applicant

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

Creates a new primary applicant record with optional dependents.

Endpoint

POST /v2/applicant

Parameters

No path or query parameters required.

Request Body

Content-Type: application/json

Field	Type	Description
primaryApplicant	object	Complete applicant data including employeeNumber , personal info ( firstName , lastName , dateOfBirth , gender , nationality , countryOfBirth , cityOfBirth ,maritalStatus ), metaData , passports , documents , and previousNames .
dependents	array	Array of dependent objects to create alongside the primary applicant. Each dependent follows the same schema as the primary applicant.

Usage Notes

Use this endpoint to create a brand-new applicant
The employeeNumber must be unique across the system.
Dependents can be included in the same request for atomic
For updating existing applicants, use the PUT or PATCH endpoints

Body (raw json)


{
    "primaryApplicant": {
        "employeeNumber": "23456",
        "status": "A",
        "email": "[email protected]",
        "alternateEmail": "[email protected]",
        "firstName": "Deb",
        "lastName": "Konan",
        "middleName": "vincent",
        "gender": "M",
        "maritalStatus": "M",
        "sendingCompany": "Test Company",
        "dateOfBirth": "1983-12-12T00:00:00",
        "countryOfBirth": "US",
        "cityOfBirth": "Los Angles",
        "addressLine1": "Fedrick TownHall",
        "addressLine2": "Bangkong",
        "addressCity": "California",
        "addressState": "Washington",
        "addressPostalCode": "525001",
        "addressCountry": "US",
        "telephone": "9123456789",
        "alternateTelephone": "5432167890",
        "jobTitle": "CEO",
        "relationship": "",
        "hireDate": "1985-01-01T00:00:00",
        "metaData": [
            {
                "tagName": "Manager",
                "value": "CEO"
            }
        ],
        "passports": [
            {
                "passportNumber": "67890",
                "issueDate": "2023-03-01T00:00:00",
                "expiryDate": "2099-12-31T00:00:00",
                "nationality": "US",
                "country": "US",
                "issuedBy": "US"
            }
        ],
        "documents": [
            {
                "name": "Tourist Visa",
                "description": "Tourist visa.",
                "issueDate": "2023-04-01T00:00:00",
                "expiryDate": "2024-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            }
        ],
        "previousNames": [
            {
                "lastName": "Park",
                "firstName": "Peter",
                "middleName": "Swiss"
            }
        ]
    },
    "dependents": [
        {
            "employeeNumber" : "77777",
            "status": "A",
            "email": "[email protected]",
            "alternateEmail": "[email protected]",
            "firstName": "Ringu",
            "lastName": "Zingu",
            "middleName": "Pangu",
            "gender": "F",
            "maritalStatus": "M",
            "sendingCompany": "Test Company",
            "dateOfBirth": "1972-01-31T00:00:00",
            "countryOfBirth": "US",
            "cityOfBirth": "Washington",
            "addressLine1": "California",
            "addressLine2": "Florida",
            "addressCity": "US",
            "addressState": "US",
            "addressPostalCode": "154346",
            "addressCountry": "US",
            "telephone": "123",
            "alternateTelephone": "456",
            "jobTitle": "NewTitle",
            "relationship": "Spouse",
            "hireDate": "2000-01-01",
            "metaData": [
                {
                    "tagName": "PID Number",
                    "value": "4009-797"
                }
            ],
            "passports": [
                {
                    "passportNumber": "56789",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2039-12-31T00:00:00",
                    "nationality": "US",
                    "country": "US",
                    "issuedBy": "US"
                }
            ],
            "documents": [
                {
                    "name": "Marriage Visa",
                    "description": "Marriage visa.",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                }
            ],
            "previousNames": [
                {
                    "lastName": "Silk",
                    "firstName": "Cotton",
                    "middleName": "Farb"
                }
            ]
        }
    ]
}

Update Applicant

PUT /v2/applicant/{applicantId}

https://immigo.cibtapis.com/v2/applicant/e7KVLfQeupCyttuedvmYtRpUCcmP98c_mXiIte8zOzM=

Creates or fully replaces a primary applicant record identified by the applicant’s unique encoded ID.

Endpoint

PUT /v2/applicant/{applicantId}

Path Parameters

Parameter	Type	Required	Description
applicantId	string	Yes	The unique encoded identifier (Base64) of the primary applicant to create or replace.

Request Body

Content-Type: application/json

Field	Type	Description
primaryApplicant	object	Complete applicant data including employeeNumber , personal info ( firstName , lastName , dateOfBirth , gender , nationality , etc.), metaData , passports , documents , and previousNames .
dependents	array	Array of dependent objects (can be empty).

Usage Notes

This is a full replacement (PUT) — all fields must be Omitted fields will be cleared.
Use this when you have the internal applicant ID rather than the employee
For partial updates, use the PATCH merge endpoints
For employee number-based updates, use SavePrimaryByEmployeeNumber.

Body (raw json)


{
    "primaryApplicant": {
        "applicantId": "e7KVLfQeupCyttuedvmYtde9-AGpDyEFaDj3gCORnUs=",
        "employeeNumber": "33669900243-44-22-111",
        "status": "A",
        "email": "[email protected]",
        "alternateEmail": "[email protected]",
        "firstName": "Kulab",
        "lastName": "Baga",
        "middleName": "Vali",
        "gender": "F",
        "maritalStatus": "M",
        "sendingCompany": "Test Company",
        "dateOfBirth": "1972-01-31T00:00:00",
        "countryOfBirth": "US",
        "cityOfBirth": "Washington",
        "addressLine1": "California",
        "addressLine2": "Florida",
        "addressCity": "US",
        "addressState": "US",
        "addressPostalCode": "154346",
        "addressCountry": "US",
        "telephone": "123",
        "alternateTelephone": "456",
        "jobTitle": "NewTitle",
        "relationship": "Spouse",
        "hireDate": "2000-01-01T00:00:00",
        "metaData": [
            {
                "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "tagName": "Contract Expiry Date",
                "value": "2022-08-31"
            },
            {
                "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "tagName": "PID Number",
                "value": "4009-797"
            }
        ],
        "passports": [
            {
                "passportId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "passportNumber": "",
                "issueDate": "2023-04-01T00:00:00",
                "expiryDate": "2039-12-31T00:00:00",
                "nationality": "US",
                "country": "US",
                "issuedBy": "US"
            }
        ],
        "documents": [
            {
                "documentId": "e7KVLfQeupCyttuedvmYta2nP353j5Q6kNzqwClOoS4=",
                "name": "Holiday Visa",
                "description": "Holiday Visa",
                "issueDate": null,
                "expiryDate": "2024-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            },
            {
                "documentId": "e7KVLfQeupCyttuedvmYtXHKKOcKGvBVUqkVYwcIrwc=",
                "name": "Marriage Visa",
                "description": "Marriage visa.",
                "issueDate": "2023-04-01T00:00:00",
                "expiryDate": "2024-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            }
        ],
        "previousNames": [
            {
                "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "lastName": "Silk",
                "firstName": "Cotton",
                "middleName": "Farb"
            }
        ]
    }
}

Merge Applicant

PATCH /v2/applicant/{applicantId}

https://immigo.cibtapis.com/applicant/e7KVLfQeupCyttuedvmYtTxqq5Dr4sk1M0pAh9xbKLU=

Merges a primary applicant record using the applicant’s unique encoded ID. Used to consolidate duplicate applicant entries by patching the target record.

Endpoint

PATCH /v2/applicant/{applicantId}

Path Parameters

Parameter	Type	Required	Description
applicantId	string	Yes	The unique encoded identifier (Base64) of the primary applicant to merge.

Request Body

Content-Type: application/json

Field

Type

Description

primaryApplicant

object

The applicant data to merge, including employeeNumber , status , personal info, metaData , passports , documents , and previousNames .

dependents

array

Array of dependent objects to associate with the merged

applicant.

Usage Notes

This is a merge/patch operation — only provided fields are updated; existing fields not in the request body remain
Use this when you have the internal applicant ID rather than the employee
For employee number-based merges, use MergePrimaryApplicantByEmployeeNumber instead.

Body (raw json)


{
    "primaryApplicant": {
        "applicantId": "e7KVLfQeupCyttuedvmYta5-YVoiFx1TluMOnmpriHQ=",
        "employeeNumber": "3366990036",
        "status": "A",
        "email": "[email protected]",
        "alternateEmail": "[email protected]",
        "firstName": "first name",
        "lastName": "last name",
        "middleName": "middle name",
        "gender": "M",
        "maritalStatus": "M",
        "sendingCompany": "Test company",
        "dateOfBirth": "1983-12-12T00:00:00",
        "countryOfBirth": "US",
        "cityOfBirth": "Los Angles",
        "addressLine1": "Fedrick TownHall",
        "addressLine2": "Bangkong",
        "addressCity": "California",
        "addressState": "Washington",
        "addressPostalCode": "525001",
        "addressCountry": "US",
        "telephone": "9123456789",
        "alternateTelephone": "5432167890",
        "jobTitle": "CEO",
        "relationship": "",
        "hireDate": "1985-01-01T00:00:00",
        "metaData": [
            {
                "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "tagName": "Position Name",
                "value": "Manager"
            },
            {
                "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "tagName": "Type Subgroup",
                "value": "data"
            }
        ],
        "passports": [
            {
                "passportId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "passportNumber": "",
                "issueDate": "2023-03-01T00:00:00",
                "expiryDate": "2099-12-31T00:00:00",
                "nationality": "US",
                "country": "US",
                "issuedBy": "US"
            }
        ],
        "documents": [
            {
                "documentId": "e7KVLfQeupCyttuedvmYtdE8ZpN2BY1qdcQIfILDHYY=",
                "name": "Student Visa",
                "description": "Student Visa",
                "issueDate": null,
                "expiryDate": "2124-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            },
            {
                "documentId": "e7KVLfQeupCyttuedvmYtZrIcM3Sh6-sl9bRLs6zeco=",
                "name": "Tourist Visa",
                "description": "Tourist visa.",
                "issueDate": "2023-04-01T00:00:00",
                "expiryDate": "2024-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            }
        ],
        "previousNames": [
            {
               "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "lastName": "prevLastname",
                "firstName": "prevFirstname",
                "middleName": "prevMiddlename"
            },
            {
                "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "lastName": "prev+1Lastname",
                "firstName": "prev+1Firstname",
                "middleName": "prev+1Middlename"
            }
        ]
    },
    "dependents": [
        {
            "applicantId": "e7KVLfQeupCyttuedvmYtSJDWiB4DP22PE5h3ZLgtkE=",
            "employeeNumber": "3366990036-6-66-666",
            "status": "A",
            "email": "[email protected]",
            "alternateEmail": "[email protected]",
            "firstName": "dependent first name",
            "lastName": "dependent last name",
            "middleName": "dependent last name",
            "gender": "F",
            "maritalStatus": "M",
            "sendingCompany": "Test Company",
            "dateOfBirth": "1972-01-31T00:00:00",
            "countryOfBirth": "US",
            "cityOfBirth": "Washington",
            "addressLine1": "California",
            "addressLine2": "Florida",
            "addressCity": "US",
            "addressState": "US",
            "addressPostalCode": "154346",
            "addressCountry": "US",
            "telephone": "123",
            "alternateTelephone": "456",
            "jobTitle": "NewTitle",
            "relationship": "Spouse",
            "hireDate": "2000-01-01T00:00:00",
            "metaData": [
                {
                    "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "tagName": "PID Number",
                    "value": "4009-797"
                },
                {
                    "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "tagName": "Contract Expiry Date",
                    "value": "2022-08-31"
                }
            ],
            "passports": [
                {
                    "passportId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "passportNumber": "",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2039-12-31T00:00:00",
                    "nationality": "US",
                    "country": "US",
                    "issuedBy": "US"
                }
            ],
            "documents": [
                {
                    "documentId": "e7KVLfQeupCyttuedvmYteI8qEnDL4-zbUjelEZ7XgI=",
                    "name": "Holiday Visa",
                    "description": "Holiday Visa",
                    "issueDate": null,
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                },
                {
                    "documentId": "e7KVLfQeupCyttuedvmYtTzD9Z5IsfsHd0oLOP9vhBA=",
                    "name": "Marriage Visa",
                    "description": "Marriage visa.",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                }
            ],
            "previousNames": [
                {
                    "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "lastName": "Shree",
                    "firstName": "Sri",
                    "middleName": "sheba"
                }
            ]
        }
    ]
}

Save Dependent

POST /v2/applicant/{applicantId}/dependent

https://immigo.cibtapis.com/v2/applicant/e7KVLfQeupCyttuedvmYtdgMtAW3l-NCYnQ46HXHG18=/dependent

Creates a new dependent record under a primary applicant, identified by the primary applicant’s unique encoded ID.

Endpoint

POST /v2/applicant/{applicantId}/dependent

Path Parameters

Parameter	Type	Required	Description
applicantId	string	Yes	The unique encoded identifier (Base64) of the primary applicant.

Request Body

Content-Type: application/json

Field	Type	Description
employeeNumber	string	The dependent’s employee number.
Personal fields	various	firstName , lastName , middleName , dateOfBirth , gender , nationality , countryOfBirth , cityOfBirth , maritalStatus , relationship .
metaData	object	Custom metadata key-value pairs.
passports	array	Array of passport objects.
documents	array	Array of document objects.
previousNames	array	Array of previous name records.

Usage Notes

Creates a new dependent associated with the specified primary
The applicantId in the path must reference an existing primary applicant.
The request body uses a template format with placeholder values—replace “string” placeholders with actual data.

Body (raw json)


{
    "employeeNumber": "33669900266-66-6-666",
    "status": "A",
    "email": "[email protected]",
    "alternateEmail": "[email protected]",
    "firstName": "Pandi",
    "lastName": "Anbu",
    "middleName": "Kathir",
    "gender": "F",
    "maritalStatus": "M",
    "sendingCompany": "Test Company",
    "dateOfBirth": "1972-01-31T00:00:00",
    "countryOfBirth": "US",
    "cityOfBirth": "Washington",
    "addressLine1": "California",
    "addressLine2": "Florida",
    "addressCity": "US",
    "addressState": "US",
    "addressPostalCode": "154346",
    "addressCountry": "US",
    "telephone": "123",
    "alternateTelephone": "456",
    "jobTitle": "NewTitle",
    "relationship": "Spouse",
    "hireDate": "2000-01-01T00:00:00",
    "metaData": [
        {
            "tagName": "Contract Expiry Date",
            "value": "2022-08-31"
        }
    ],
    "passports": [
        {
            "passportNumber": "",
            "issueDate": "2023-04-01T00:00:00",
            "expiryDate": "2039-12-31T00:00:00",
            "nationality": "US",
            "country": "US",
            "issuedBy": "US"
        }
    ],
    "documents": [
        {
            "name": "Holiday Visa",
            "description": "Holiday Visa",
            "issueDate": null,
            "expiryDate": "2024-12-31T00:00:00",
            "referenceNumber": "123456",
            "country": "US",
            "remindAboutRenewal": false,
            "expiryReminder": 0
        }
    ],
    "previousNames": [
        {
            "lastName": "wifi",
            "firstName": "hifi",
            "middleName": "nifi"
        }
    ]
}

Get Applicant by Employee Number

GET /v2/applicant/employeenumber/{employeenumber}

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

Retrieves a primary applicant record by their employee number.

Endpoint

GET /v2/applicant/employeenumber/{employeeNumber}

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The unique employee number identifying the applicant.

Response

Returns the primary applicant object including personal information, metadata, passport details, and document references.

Usage Notes

Employee numbers are unique identifiers assigned to primary
This endpoint returns only the primary applicant record; use GetDependentsByEmployeeNumber to retrieve associated dependents.

Get Dependents by Employee Number

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

https://immigo.cibtapis.com/v2/applicant/employeenumber/77777/dependents

Retrieves all dependents associated with a primary applicant, identified by the primary applicant’s employee number.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The employee number of the primary applicant whose dependents are being retrieved.

Response

Returns an array of dependent records, each containing personal information, metadata, passport details, and document references.

Usage Notes

Only returns dependent records, not the primary applicant.
If no dependents exist for the given employee number, an empty array is returned.

Get Dependent by Employee Number

GET /v2/applicant/employeenumber/{employeeNumber}/dependents/{dependentEmployeeNumber}

https://immigo.cibtapis.com/v2/employeenumber/77777/dependents/345

Retrieves the dependent associated with a primary applicant, identified by the primary applicant’s employee number and dependent employee number.

Endpoint

GET /v2/applicant/employeenumber/{employeeNumber}/dependents/{dependentEmployeeNumber

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The employee number of the primary applicant whose dependent is being retrieved.
dependentEmployeeNumber	string	Yes	The dependent’s employee number.

Response

Returns the dependent record, containing personal information, metadata, passport details, and document references.

Usage Notes

Only returns dependent record, not the primary applicant.
If no dependents exist for the given employee number, a not found error is returned.

Save Applicant by Employee Number

PUT /v2/applicant/employeenumber/{employeeNumberInput}

https://immigo.cibtapis.com/v2/applicant/employeenumber/77777

Creates or fully updates a primary applicant record identified by employee number. This is an upsert operation — if the applicant exists, it is replaced; if not, it is created.

Endpoint

PUT /v2/applicant/employeenumber/{employeeNumber}

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The employee number for the applicant record to create or update.

Request Body

Content-Type: application/json

Field	Type	Description
primaryApplicant	object	Complete applicant data including employeeNumber, personal info (firstName, lastName, dateOfBirth, gender, nationality, etc.), metaData, passports, documents, and previousNames.
dependents	array	Array of dependent objects to associate with this applicant.

Usage Notes

This is a full replacement (PUT) — all fields must be provided. Omitted fields will be cleared.
Use PATCH endpoints for partial updates/merges instead.
The passports array should include all current and historical passport records.

Body (raw json)


{
    "primaryApplicant": {
        "employeeNumber": "3366990036",
        "status": "A",
        "email": "[email protected]",
        "alternateEmail": "[email protected]",
        "firstName": "first name",
        "lastName": "last name",
        "middleName": "middle name",
        "gender": "M",
        "maritalStatus": "M",
        "sendingCompany": "Test company",
        "dateOfBirth": "1983-12-12T00:00:00",
        "countryOfBirth": "US",
        "cityOfBirth": "Los Angles",
        "addressLine1": "Fedrick TownHall",
        "addressLine2": "Bangkong",
        "addressCity": "California",
        "addressState": "Washington",
        "addressPostalCode": "525001",
        "addressCountry": "US",
        "telephone": "9123456789",
        "alternateTelephone": "5432167890",
        "jobTitle": "CEO",
        "relationship": "",
        "hireDate": "1985-01-01T00:00:00",
        "metaData": [
            {
                "tagName": "Position Name",
                "value": "Manager"
            },
            {
                "tagName": "Type Subgroup",
                "value": "data"
            }
        ],
        "passports": [
            {
                "passportNumber": "",
                "issueDate": "2023-03-01T00:00:00",
                "expiryDate": "2099-12-31T00:00:00",
                "nationality": "US",
                "country": "US",
                "issuedBy": "US"
            }
        ],
        "documents": [
            {
                "name": "Student Visa",
                "description": "Student Visa",
                "issueDate": null,
                "expiryDate": "2124-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            },
            {
                "name": "Tourist Visa",
                "description": "Tourist visa.",
                "issueDate": "2023-04-01T00:00:00",
                "expiryDate": "2024-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            }
        ],
        "previousNames": [
            {
                "lastName": "prevLastname",
                "firstName": "prevFirstname",
                "middleName": "prevMiddlename"
            },
            {
                "lastName": "prev+1Lastname",
                "firstName": "prev+1Firstname",
                "middleName": "prev+1Middlename"
            }
        ]
    },
    "dependents": [
        {
            "employeeNumber": "3366990036-6-66-666",
            "status": "A",
            "email": "[email protected]",
            "alternateEmail": "[email protected]",
            "firstName": "dependent first name",
            "lastName": "dependent last name",
            "middleName": "dependent last name",
            "gender": "F",
            "maritalStatus": "M",
            "sendingCompany": "Test Company",
            "dateOfBirth": "1972-01-31T00:00:00",
            "countryOfBirth": "US",
            "cityOfBirth": "Washington",
            "addressLine1": "California",
            "addressLine2": "Florida",
            "addressCity": "US",
            "addressState": "US",
            "addressPostalCode": "154346",
            "addressCountry": "US",
            "telephone": "123",
            "alternateTelephone": "456",
            "jobTitle": "NewTitle",
            "relationship": "Spouse",
            "hireDate": "2000-01-01T00:00:00",
            "metaData": [
                {
                    "tagName": "PID Number",
                    "value": "4009-797"
                },
                {
                    "tagName": "Contract Expiry Date",
                    "value": "2022-08-31"
                }
            ],
            "passports": [
                {
                    "passportNumber": "",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2039-12-31T00:00:00",
                    "nationality": "US",
                    "country": "US",
                    "issuedBy": "US"
                }
            ],
            "documents": [
                {
                    "name": "Holiday Visa",
                    "description": "Holiday Visa",
                    "issueDate": null,
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                },
                {
                    "name": "Marriage Visa",
                    "description": "Marriage visa.",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                }
            ],
            "previousNames": [
                {
                    "lastName": "Shree",
                    "firstName": "Sri",
                    "middleName": "sheba"
                }
            ]
        }
    ]
}

Save Dependent by Employee Number

PUT /v2/applicant/employeenumber/{employeeNumberInput}/dependents/{dependentId}

https://immigo.cibtapis.com/v2/applicant/employeenumber/77777/dependents/345

Creates or fully updates a dependent record identified by the primary applicant’s employee number and the dependent’s identifier.

Endpoint

PUT /v2/applicant/employeenumber/{employeeNumber}/dependents/{dependentId}

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The employee number of the primary applicant.
dependentId	string	Yes	The unique identifier of the dependent to create or update.

Request Body

Content-Type: application/json

Field	Type	Description
employeeNumber	string	The dependent’s own employee number.
Personal fields	various	firstName, lastName, middleName, dateOfBirth, gender, nationality, countryOfBirth, cityOfBirth, maritalStatus, relationship.
metaData	object	Custom metadata key-value pairs.
passports	array	Array of passport objects.
documents	array	Array of document objects.
previousNames	array	Array of previous name records.

Usage Notes

This is a full replacement (PUT) — all fields must be provided.
Both the primary applicant’s employee number and the dependent’s ID are required.

Body (raw json)


{
    "employeeNumber": "33669900266-66-6-666",
    "status": "A",
    "email": "[email protected]",
    "alternateEmail": "[email protected]",
    "firstName": "Pandi",
    "lastName": "Anbu",
    "middleName": "Kathir",
    "gender": "F",
    "maritalStatus": "M",
    "sendingCompany": "Test Company",
    "dateOfBirth": "1972-01-31T00:00:00",
    "countryOfBirth": "US",
    "cityOfBirth": "Washington",
    "addressLine1": "California",
    "addressLine2": "Florida",
    "addressCity": "US",
    "addressState": "US",
    "addressPostalCode": "154346",
    "addressCountry": "US",
    "telephone": "123",
    "alternateTelephone": "456",
    "jobTitle": "NewTitle",
    "relationship": "Spouse",
    "hireDate": "2000-01-01T00:00:00",
    "metaData": [
        {
            "tagName": "Contract Expiry Date",
            "value": "2022-08-31"
        }
    ],
    "passports": [
        {
            "passportNumber": "",
            "issueDate": "2023-04-01T00:00:00",
            "expiryDate": "2039-12-31T00:00:00",
            "nationality": "US",
            "country": "US",
            "issuedBy": "US"
        }
    ],
    "documents": [
        {
            "name": "Holiday Visa",
            "description": "Holiday Visa",
            "issueDate": null,
            "expiryDate": "2024-12-31T00:00:00",
            "referenceNumber": "123456",
            "country": "US",
            "remindAboutRenewal": false,
            "expiryReminder": 0
        }
    ],
    "previousNames": [
        {
            "lastName": "wifi",
            "firstName": "hifi",
            "middleName": "nifi"
        }
    ]
}

Change Employee Number

POST /v2/applicant/employeenumber/{oldEmployeeNumber}/{newEmployeeNumber}

https://immigo.cibtapis.com/v2/applicant/employeenumber/77777/88888

Changes a primary applicant’s employee number from one value to another. The applicant is verified using personal details provided in the request body.

Endpoint

POST /v2/applicant/employeenumber/{oldEmployeeNumber}/{newEmployeeNumber}

Authentication

Requires a valid API key and authorization token (inherited from folder/collection auth settings).

Path Parameters

Parameter	Type	Required	Description
oldEmployeeNumber	string	Yes	The current employee number to be changed.
newEmployeeNumber	string	Yes	The new employee number to assign.

Request Body

Content-Type: application/json

Field	Type	Required	Description
firstName	string	Yes	The applicant’s first name (used for verification).
lastName	string	Yes	The applicant’s last name (used for verification).
dateOfBirth	string	Yes	The applicant’s date of birth in ISO format (used for verification).

Usage Notes

The request body fields are used to verify the identity of the applicant before changing the employee number.
This operation is irreversible — ensure the new employee number is correct before submitting.
All associated cases and documents will be updated to reference the new employee number.

Body (raw json)

{
   "firstName": "Frank",
   "lastName": "Jon",
   "dateOfBirth": "1960-03-04T00:00:00"
}

Change Dependent Employee Number

POST /v2/applicant/employeenumber/{primaryEmployeeNumber}

/dependents/{currentDependentEmployeeNumber}

https://immigo.cibtapis.com/v2/applicant/employeenumber/77777/dependents/345

Changes a dependent’s employee number under a primary applicant. The dependent is verified using personal details provided in the request body.

Endpoint

POST /v2/applicant/employeenumber/{primaryEmployeeNumber}/dependents/{currentDependentEmployeeNumber}

Path Parameters

Parameter	Type	Required	Description
primaryEmployeeNumber	string	Yes	The employee number of the primary applicant.
currentDependentEmployeeNumber	string	Yes	The current employee number of the dependent to be changed.

Request Body

Content-Type: application/json

Field	Type	Required	Description
firstName	string	Yes	The dependent’s first name (used for verification).
dateOfBirth	string	Yes	The dependent’s date of birth in ISO format (used for verification).

Usage Notes

The request body fields are used to verify the identity of the dependent before changing the employee number.
This operation updates the dependent’s employee number while maintaining the association with the primary applicant.

Body (raw json)

{
      "firstName": "Carla",
      "dateOfBirth": "1972-01-31"
}

Merge Primary Applicant by Employee Number

PATCH /v2/applicant/employeenumber/{employeeNumber}

https://immigo.cibtapis.com/v2/applicant/employeenumber/77777

Merges a primary applicant record using the employee number. Used to consolidate duplicate applicant entries by patching the target record with updated data.

Endpoint

PATCH /v2/applicant/employeenumber/{employeeNumber}

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The employee number of the primary applicant to merge.

Request Body

Content-Type: application/json

Field	Type	Description
primaryApplicant	object	The applicant data to merge, including employeeNumber, status, personal info (firstName, lastName, dateOfBirth, etc.), metaData, passports, documents, and previousNames.
dependents	array	Array of dependent objects to associate with the merged applicant.

Usage Notes

This is a merge operation — existing fields not included in the request body will remain unchanged.
Use this to consolidate duplicate applicant records into a single canonical record.
The metaData object can include custom key-value pairs for tracking merge history.

Body (raw json)

{
    "primaryApplicant": {
        "applicantId": "e7KVLfQeupCyttuedvmYta5-YVoiFx1TluMOnmpriHQ=",
        "employeeNumber": "3366990036",
        "status": "A",
        "email": "[email protected]",
        "alternateEmail": "[email protected]",
        "firstName": "first name",
        "lastName": "last name",
        "middleName": "middle name",
        "gender": "M",
        "maritalStatus": "M",
        "sendingCompany": "Test company",
        "dateOfBirth": "1983-12-12T00:00:00",
        "countryOfBirth": "US",
        "cityOfBirth": "Los Angles",
        "addressLine1": "Fedrick TownHall",
        "addressLine2": "Bangkong",
        "addressCity": "California",
        "addressState": "Washington",
        "addressPostalCode": "525001",
        "addressCountry": "US",
        "telephone": "9123456789",
        "alternateTelephone": "5432167890",
        "jobTitle": "CEO",
        "relationship": "",
        "hireDate": "1985-01-01T00:00:00",
        "metaData": [
            {
                "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "tagName": "Position Name",
                "value": "Manager"
            },
            {
                "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "tagName": "Type Subgroup",
                "value": "data"
            }
        ],
        "passports": [
            {
                "passportId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "passportNumber": "",
                "issueDate": "2023-03-01T00:00:00",
                "expiryDate": "2099-12-31T00:00:00",
                "nationality": "US",
                "country": "US",
                "issuedBy": "US"
            }
        ],
        "documents": [
            {
                "documentId": "e7KVLfQeupCyttuedvmYtdE8ZpN2BY1qdcQIfILDHYY=",
                "name": "Student Visa",
                "description": "Student Visa",
                "issueDate": null,
                "expiryDate": "2124-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            },
            {
                "documentId": "e7KVLfQeupCyttuedvmYtZrIcM3Sh6-sl9bRLs6zeco=",
                "name": "Tourist Visa",
                "description": "Tourist visa.",
                "issueDate": "2023-04-01T00:00:00",
                "expiryDate": "2024-12-31T00:00:00",
                "referenceNumber": "123456",
                "country": "US",
                "remindAboutRenewal": false,
                "expiryReminder": 0
            }
        ],
        "previousNames": [
            {
               "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "lastName": "prevLastname",
                "firstName": "prevFirstname",
                "middleName": "prevMiddlename"
            },
            {
                "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                "lastName": "prev+1Lastname",
                "firstName": "prev+1Firstname",
                "middleName": "prev+1Middlename"
            }
        ]
    },
    "dependents": [
        {
            "applicantId": "e7KVLfQeupCyttuedvmYtSJDWiB4DP22PE5h3ZLgtkE=",
            "employeeNumber": "3366990036-6-66-666",
            "status": "A",
            "email": "[email protected]",
            "alternateEmail": "[email protected]",
            "firstName": "dependent first name",
            "lastName": "dependent last name",
            "middleName": "dependent last name",
            "gender": "F",
            "maritalStatus": "M",
            "sendingCompany": "Test Company",
            "dateOfBirth": "1972-01-31T00:00:00",
            "countryOfBirth": "US",
            "cityOfBirth": "Washington",
            "addressLine1": "California",
            "addressLine2": "Florida",
            "addressCity": "US",
            "addressState": "US",
            "addressPostalCode": "154346",
            "addressCountry": "US",
            "telephone": "123",
            "alternateTelephone": "456",
            "jobTitle": "NewTitle",
            "relationship": "Spouse",
            "hireDate": "2000-01-01T00:00:00",
            "metaData": [
                {
                    "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "tagName": "PID Number",
                    "value": "4009-797"
                },
                {
                    "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "tagName": "Contract Expiry Date",
                    "value": "2022-08-31"
                }
            ],
            "passports": [
                {
                    "passportId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "passportNumber": "",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2039-12-31T00:00:00",
                    "nationality": "US",
                    "country": "US",
                    "issuedBy": "US"
                }
            ],
            "documents": [
                {
                    "documentId": "e7KVLfQeupCyttuedvmYteI8qEnDL4-zbUjelEZ7XgI=",
                    "name": "Holiday Visa",
                    "description": "Holiday Visa",
                    "issueDate": null,
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                },
                {
                    "documentId": "e7KVLfQeupCyttuedvmYtTzD9Z5IsfsHd0oLOP9vhBA=",
                    "name": "Marriage Visa",
                    "description": "Marriage visa.",
                    "issueDate": "2023-04-01T00:00:00",
                    "expiryDate": "2024-12-31T00:00:00",
                    "referenceNumber": "123456",
                    "country": "US",
                    "remindAboutRenewal": false,
                    "expiryReminder": 0
                }
            ],
            "previousNames": [
                {
                    "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
                    "lastName": "Shree",
                    "firstName": "Sri",
                    "middleName": "sheba"
                }
            ]
        }
    ]
}

Merge Dependent by Employee Number

PATCH /v2/applicant/employeenumber/{employeeNumber}/dependents/{dependentId}

https://immigo.cibtapis.com/v2/applicant/employeenumber/7777/dependents/3456

Merges a dependent record under a primary applicant using both the primary employee number and the dependent identifier. Used to consolidate duplicate dependent entries.

Endpoint

PATCH /v2/applicant/employeenumber/{employeeNumber}/dependents/{dependentId}

Path Parameters

Parameter	Type	Required	Description
employeeNumber	string	Yes	The employee number of the primary applicant.
dependentId	string	Yes	The unique identifier of the dependent to merge.

Request Body

Content-Type: application/json

Field	Type	Description
applicantId	string	The applicant ID of the dependent.
employeeNumber	string	The dependent’s employee number.
Personal fields	various	firstName, lastName, middleName, dateOfBirth, gender, nationality, countryOfBirth, cityOfBirth, maritalStatus, relationship.
metaData	object	Custom metadata key-value pairs.
passports	array	Array of passport objects.
documents	array	Array of document objects.
previousNames	array	Array of previous name records.

Usage Notes

This is a merge operation for dependent records specifically.
Both the primary applicant’s employee number and the dependent’s ID are required to identify the correct record.

Body (raw json)

{
    "applicantId": "e7KVLfQeupCyttuedvmYtde9-AGpDyEFaDj3gCORnUs=",
    "employeeNumber": "33669900243-44-22-111",
    "status": "A",
    "email": "[email protected]",
    "alternateEmail": "[email protected]",
    "firstName": "Kulab",
    "lastName": "Baga",
    "middleName": "Vali",
    "gender": "F",
    "maritalStatus": "M",
    "sendingCompany": "Test Company",
    "dateOfBirth": "1972-01-31T00:00:00",
    "countryOfBirth": "US",
    "cityOfBirth": "Washington",
    "addressLine1": "California",
    "addressLine2": "Florida",
    "addressCity": "US",
    "addressState": "US",
    "addressPostalCode": "154346",
    "addressCountry": "US",
    "telephone": "123",
    "alternateTelephone": "456",
    "jobTitle": "NewTitle",
    "relationship": "Spouse",
    "hireDate": "2000-01-01T00:00:00",
    "metaData": [
        {
            "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
            "tagName": "Contract Expiry Date",
            "value": "2022-08-31"
        },
        {
            "noteId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
            "tagName": "PID Number",
            "value": "4009-797"
        }
    ],
    "passports": [
        {
            "passportId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
            "passportNumber": "",
            "issueDate": "2023-04-01T00:00:00",
            "expiryDate": "2039-12-31T00:00:00",
            "nationality": "US",
            "country": "US",
            "issuedBy": "US"
        }
    ],
    "documents": [
        {
            "documentId": "e7KVLfQeupCyttuedvmYta2nP353j5Q6kNzqwClOoS4=",
            "name": "Holiday Visa",
            "description": "Holiday Visa",
            "issueDate": null,
            "expiryDate": "2024-12-31T00:00:00",
            "referenceNumber": "123456",
            "country": "US",
            "remindAboutRenewal": false,
            "expiryReminder": 0
        },
        {
            "documentId": "e7KVLfQeupCyttuedvmYtXHKKOcKGvBVUqkVYwcIrwc=",
            "name": "Marriage Visa",
            "description": "Marriage visa.",
            "issueDate": "2023-04-01T00:00:00",
            "expiryDate": "2024-12-31T00:00:00",
            "referenceNumber": "123456",
            "country": "US",
            "remindAboutRenewal": false,
            "expiryReminder": 0
        }
    ],
    "previousNames": [
        {
            "previousNameId": "e7KVLfQeupCyttuedvmYtVHYJLdTDxp5aTDuU1sCtfY=",
            "lastName": "Silk",
            "firstName": "Cotton",
            "middleName": "Farb"
        }
    ]
}