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"
}
]
}