Hrm Employees

Function-calling namespace: hrmEmployees

Base URL: https://api.aivida.in
Engine endpoint: POST /api
Auth: private API; Stack access token is required.
Send token in header: x-stack-access-token: <access_token> (or Authorization: Bearer <access_token>).
Allowed roles: platform_admin, hr.
Missing or invalid token returns 401; authenticated users without an allowed role return 403.

`create`

Source: backend/endpoints/hrm-employees/create

Input Fields

Field	Type	Required	Constraints
`organizationId`	`string`	Yes	-
`organizationBranchIds`	`array<string>`	No	optional; maps the created employee user to these organization branches
`employeeCode`	`string`	Yes	-
`employeeName`	`string`	Yes	-
`email`	`string`	Yes	-
`phoneNumber`	`string`	Yes	-
`gender`	`string`	No	-
`departmentId`	`string`	Yes	-
`designationId`	`string`	Yes	-
`joiningDate`	`string`	Yes	format: YYYY-MM-DD
`dateOfBirth`	`string`	No	-
`bloodGroup`	`string`	No	-
`address`	`string`	No	-
`city`	`string`	No	-
`state`	`string`	No	-
`country`	`string`	No	-
`pincode`	`string`	No	-
`religion`	`string`	No	-
`nationality`	`string`	No	-
`qualification`	`string`	No	-
`experienceYears`	`number`	No	-
`employeeType`	`string`	Yes	-
`status`	`string`	Yes	-
`aadharNumber`	`string`	No	-
`panNumber`	`string`	No	-
`profileImageUrl`	`string`	No	-
`signatureImageUrl`	`string`	No	-
`officialEmail`	`string`	No	-
`personalEmail`	`string`	No	-
`emergencyContactName`	`string`	No	-
`emergencyContactNumber`	`string`	No	-
`reportingManagerId`	`string`	No	-
`workLocation`	`string`	No	-
`probationEndDate`	`string`	No	format: YYYY-MM-DD
`confirmationDate`	`string`	No	format: YYYY-MM-DD
`lastWorkingDate`	`string`	No	format: YYYY-MM-DD
`uanNumber`	`string`	No	-
`esiNumber`	`string`	No	-
`documents`	`array<object>`	No	-
`bankDetails`	`object`	No	nullable
`salary`	`object`	No	nullable
`statutoryDeductions`	`object`	No	nullable

Nested Field Structures

`documents` item

Field	Type	Required	Constraints
`documentName`	`string`	No	-
`documentType`	`string`	No	-
`documentUrl`	`string`	No	-
`remarks`	`string`	No	-

`bankDetails`

Field	Type	Required	Constraints
`accountHolderName`	`string`	No	-
`bankName`	`string`	No	-
`branchName`	`string`	No	-
`accountNumber`	`string`	No	-
`ifscCode`	`string`	No	-
`upiId`	`string`	No	-
`isPrimary`	`boolean`	No	nullable

`salary`

Field	Type	Required	Constraints
`baseSalary`	`number`	No	-
`hra`	`number`	No	-
`dearnessAllowance`	`number`	No	-
`conveyanceAllowance`	`number`	No	-
`medicalAllowance`	`number`	No	-
`specialAllowance`	`number`	No	-

`statutoryDeductions`

Field	Type	Required	Constraints
`pfEnabled`	`boolean`	No	-
`pfType`	`string`	No	-
`pfPercentage`	`number`	No	-
`esiEnabled`	`boolean`	No	-
`esiType`	`string`	No	-
`esiPercentage`	`number`	No	-
`tdsEnabled`	`boolean`	No	-
`tdsPercentage`	`number`	No	-
`professionalTaxEnabled`	`boolean`	No	-
`professionalTaxAmount`	`number`	No	-

Branch Mapping Notes

organizationBranchIds is optional.
When organizationBranchIds is provided, the created employee user is mapped to those branches in user_organization_branches.
Branch IDs are validated against the same organizationId; invalid branch IDs are rejected.
The response returns organizationBranchIds and organizationBranchNames from the saved branch mapping.

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token>" \
  -d '{
  "namespace": "hrmEmployees",
  "apiName": "create",
  "data": {
    "organizationId": "org_123",
    "organizationBranchIds": [
      "branch_123"
    ],
    "employeeCode": "EMP-001",
    "employeeName": "Anitha Kumar",
    "email": "anitha.kumar@example.com",
    "phoneNumber": "+911234567890",
    "departmentId": "department_123",
    "designationId": "designation_123",
    "joiningDate": "2026-03-12",
    "employeeType": "full_time",
    "status": "active"
  }
}'

Example Response

{ "status": "ok", "data": {} }

`delete`

Source: backend/endpoints/hrm-employees/delete

Input Fields

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token>" \
  -d '{
  "namespace": "hrmEmployees",
  "apiName": "delete",
  "data": {
    "organizationId": "org_123",
    "id": "id_123"
  }
}'

Example Response

{ "status": "ok", "data": {} }

`getById`

Source: backend/endpoints/hrm-employees/get-by-id

Input Fields

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token>" \
  -d '{
  "namespace": "hrmEmployees",
  "apiName": "getById",
  "data": {
    "organizationId": "org_123",
    "id": "id_123"
  }
}'

Example Response

{ "status": "ok", "data": {} }

`list`

Source: backend/endpoints/hrm-employees/list

Input Fields

Field	Type	Required	Constraints
`organizationId`	`string`	No	-
`branchId`	`string`	No	-
`departmentId`	`string`	No	-
`designationId`	`string`	No	-
`status`	`string`	No	-
`search`	`string`	No	-
`page`	`integer`	No	-
`pageSize`	`integer`	No	-

Response Notes

branchId is optional and filters records assigned to that organization branch.
Each returned item includes organizationBranchIds and organizationBranchNames from the saved user branch mapping.
The response merges hrm_employees records with organization users records that do not already have an HRM employee entry.
Merged user-only records also include organizationBranchIds and organizationBranchNames when the user has branch mappings.
User-only records are returned in the same employee item shape, using the user ID as both id and userId.
When departmentId or designationId is provided, user-only records are skipped because those filters are HRM-employee fields.

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token>" \
  -d '{
  "namespace": "hrmEmployees",
  "apiName": "list",
  "data": {
    "organizationId": "org_123",
    "status": "scheduled"
  }
}'

Response Data Format

Field	Type	Required	Constraints
`items`	`array<object>`	No	-
`total`	`integer`	No	-
`page`	`integer`	No	-
`pageSize`	`integer`	No	-
`totalPages`	`integer`	No	-

Response Data Format Nested Structures

`items[]` item

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-
`userId`	`string`	No	-
`organizationBranchIds`	`array<string>`	No	-
`organizationBranchNames`	`array<string>`	No	-
`employeeCode`	`string`	No	-
`employeeName`	`string`	No	-
`email`	`string`	No	-
`phoneNumber`	`string`	No	-
`gender`	`string`	No	-
`departmentId`	`string`	No	-
`departmentName`	`string`	No	-
`designationId`	`string`	No	-
`designationName`	`string`	No	-
`joiningDate`	`string`	No	format: YYYY-MM-DD
`dateOfBirth`	`string`	No	-
`bloodGroup`	`string`	No	-
`address`	`string`	No	-
`city`	`string`	No	-
`state`	`string`	No	-
`country`	`string`	No	-
`pincode`	`string`	No	-
`religion`	`string`	No	-
`nationality`	`string`	No	-
`qualification`	`string`	No	-
`experienceYears`	`number`	No	-
`employeeType`	`string`	No	-
`status`	`string`	No	-
`aadharNumber`	`string`	No	-
`panNumber`	`string`	No	-
`profileImageUrl`	`string`	No	-
`signatureImageUrl`	`string`	No	-
`officialEmail`	`string`	No	-
`personalEmail`	`string`	No	-
`emergencyContactName`	`string`	No	-
`emergencyContactNumber`	`string`	No	-
`reportingManagerId`	`string`	No	-
`workLocation`	`string`	No	-
`probationEndDate`	`string`	No	format: YYYY-MM-DD
`confirmationDate`	`string`	No	format: YYYY-MM-DD
`lastWorkingDate`	`string`	No	format: YYYY-MM-DD
`uanNumber`	`string`	No	-
`esiNumber`	`string`	No	-
`isActive`	`boolean`	No	-
`isDeleted`	`boolean`	No	-
`deletedAt`	`integer`	No	unix-ms timestamp; nullable
`createdAt`	`integer`	No	unix-ms timestamp
`updatedAt`	`integer`	No	unix-ms timestamp
`documents`	`array<object>`	No	-
`bankDetails`	`object`	No	nullable
`salary`	`object`	No	nullable
`statutoryDeductions`	`object`	No	nullable

`items[].documents[]` item

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-
`employeeId`	`string`	No	-
`documentName`	`string`	No	-
`documentType`	`string`	No	-
`documentUrl`	`string`	No	-
`remarks`	`string`	No	-
`isDeleted`	`boolean`	No	-
`deletedAt`	`integer`	No	unix-ms timestamp; nullable
`createdAt`	`integer`	No	unix-ms timestamp
`updatedAt`	`integer`	No	unix-ms timestamp

`items[].bankDetails`

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-
`employeeId`	`string`	No	-
`accountHolderName`	`string`	No	-
`bankName`	`string`	No	-
`branchName`	`string`	No	-
`accountNumber`	`string`	No	-
`ifscCode`	`string`	No	-
`upiId`	`string`	No	-
`isPrimary`	`boolean`	No	-
`createdAt`	`integer`	No	unix-ms timestamp
`updatedAt`	`integer`	No	unix-ms timestamp

`items[].salary`

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-
`employeeId`	`string`	No	-
`baseSalary`	`number`	No	-
`hra`	`number`	No	-
`dearnessAllowance`	`number`	No	-
`conveyanceAllowance`	`number`	No	-
`medicalAllowance`	`number`	No	-
`specialAllowance`	`number`	No	-
`grossSalary`	`number`	No	-
`annualCtc`	`number`	No	-
`createdAt`	`integer`	No	unix-ms timestamp
`updatedAt`	`integer`	No	unix-ms timestamp

`items[].statutoryDeductions`

Field	Type	Required	Constraints
`id`	`string`	No	-
`organizationId`	`string`	No	-
`employeeId`	`string`	No	-
`pfEnabled`	`boolean`	No	-
`pfType`	`string`	No	-
`pfPercentage`	`number`	No	-
`esiEnabled`	`boolean`	No	-
`esiType`	`string`	No	-
`esiPercentage`	`number`	No	-
`tdsEnabled`	`boolean`	No	-
`tdsPercentage`	`number`	No	-
`professionalTaxEnabled`	`boolean`	No	-
`professionalTaxAmount`	`number`	No	-
`createdAt`	`integer`	No	unix-ms timestamp
`updatedAt`	`integer`	No	unix-ms timestamp

Response Data Format Example

{
  "items": [
    {
      "id": "id_123",
      "organizationId": "org_123",
      "userId": "user_123",
      "organizationBranchIds": [
        "value"
      ],
      "organizationBranchNames": [
        "value"
      ],
      "employeeCode": "value",
      "employeeName": "value",
      "email": "user@example.com",
      "phoneNumber": "+911234567890",
      "gender": "value",
      "departmentId": "department_123",
      "departmentName": "value",
      "designationId": "designation_123",
      "designationName": "value",
      "joiningDate": "2026-03-12",
      "dateOfBirth": "2026-03-12",
      "bloodGroup": "value",
      "address": "221B Baker Street",
      "city": "Bengaluru",
      "state": "Karnataka",
      "country": "India",
      "pincode": "value",
      "religion": "value",
      "nationality": "value",
      "qualification": "value",
      "experienceYears": 1,
      "employeeType": "general",
      "status": "scheduled",
      "aadharNumber": "value",
      "panNumber": "value",
      "profileImageUrl": "value",
      "signatureImageUrl": "value",
      "officialEmail": "user@example.com",
      "personalEmail": "user@example.com",
      "emergencyContactName": "value",
      "emergencyContactNumber": "value",
      "reportingManagerId": "reportingmanager_123",
      "workLocation": "value",
      "probationEndDate": "2026-03-12",
      "confirmationDate": "2026-03-12",
      "lastWorkingDate": "2026-03-12",
      "uanNumber": "value",
      "esiNumber": "value",
      "isActive": true,
      "isDeleted": false,
      "deletedAt": 1710201600000,
      "createdAt": 1710201600000,
      "updatedAt": 1710201600000,
      "documents": [
        {
          "id": "id_123",
          "organizationId": "org_123",
          "employeeId": "employee_123",
          "documentName": "value",
          "documentType": "general",
          "documentUrl": "value",
          "remarks": "value",
          "isDeleted": false,
          "deletedAt": 1710201600000,
          "createdAt": 1710201600000,
          "updatedAt": 1710201600000
        }
      ],
      "bankDetails": {
        "id": "id_123",
        "organizationId": "org_123",
        "employeeId": "employee_123",
        "accountHolderName": "value",
        "bankName": "value",
        "branchName": "value",
        "accountNumber": "value",
        "ifscCode": "value",
        "upiId": "upi_123",
        "isPrimary": true,
        "createdAt": 1710201600000,
        "updatedAt": 1710201600000
      },
      "salary": {
        "id": "id_123",
        "organizationId": "org_123",
        "employeeId": "employee_123",
        "baseSalary": 1,
        "hra": 1,
        "dearnessAllowance": 1,
        "conveyanceAllowance": 1,
        "medicalAllowance": 1,
        "specialAllowance": 1,
        "grossSalary": 1,
        "annualCtc": 1,
        "createdAt": 1710201600000,
        "updatedAt": 1710201600000
      },
      "statutoryDeductions": {
        "id": "id_123",
        "organizationId": "org_123",
        "employeeId": "employee_123",
        "pfEnabled": true,
        "pfType": "general",
        "pfPercentage": 1,
        "esiEnabled": true,
        "esiType": "general",
        "esiPercentage": 1,
        "tdsEnabled": true,
        "tdsPercentage": 1,
        "professionalTaxEnabled": true,
        "professionalTaxAmount": 1,
        "createdAt": 1710201600000,
        "updatedAt": 1710201600000
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example Response

{
  "status": "ok",
  "data": {
    "items": [
      {
        "id": "id_123",
        "organizationId": "org_123",
        "userId": "user_123",
        "organizationBranchIds": [
          "value"
        ],
        "organizationBranchNames": [
          "value"
        ],
        "employeeCode": "value",
        "employeeName": "value",
        "email": "user@example.com",
        "phoneNumber": "+911234567890",
        "gender": "value",
        "departmentId": "department_123",
        "departmentName": "value",
        "designationId": "designation_123",
        "designationName": "value",
        "joiningDate": "2026-03-12",
        "dateOfBirth": "2026-03-12",
        "bloodGroup": "value",
        "address": "221B Baker Street",
        "city": "Bengaluru",
        "state": "Karnataka",
        "country": "India",
        "pincode": "value",
        "religion": "value",
        "nationality": "value",
        "qualification": "value",
        "experienceYears": 1,
        "employeeType": "general",
        "status": "scheduled",
        "aadharNumber": "value",
        "panNumber": "value",
        "profileImageUrl": "value",
        "signatureImageUrl": "value",
        "officialEmail": "user@example.com",
        "personalEmail": "user@example.com",
        "emergencyContactName": "value",
        "emergencyContactNumber": "value",
        "reportingManagerId": "reportingmanager_123",
        "workLocation": "value",
        "probationEndDate": "2026-03-12",
        "confirmationDate": "2026-03-12",
        "lastWorkingDate": "2026-03-12",
        "uanNumber": "value",
        "esiNumber": "value",
        "isActive": true,
        "isDeleted": false,
        "deletedAt": 1710201600000,
        "createdAt": 1710201600000,
        "updatedAt": 1710201600000,
        "documents": [
          {
            "id": "id_123",
            "organizationId": "org_123",
            "employeeId": "employee_123",
            "documentName": "value",
            "documentType": "general",
            "documentUrl": "value",
            "remarks": "value",
            "isDeleted": false,
            "deletedAt": 1710201600000,
            "createdAt": 1710201600000,
            "updatedAt": 1710201600000
          }
        ],
        "bankDetails": {
          "id": "id_123",
          "organizationId": "org_123",
          "employeeId": "employee_123",
          "accountHolderName": "value",
          "bankName": "value",
          "branchName": "value",
          "accountNumber": "value",
          "ifscCode": "value",
          "upiId": "upi_123",
          "isPrimary": true,
          "createdAt": 1710201600000,
          "updatedAt": 1710201600000
        },
        "salary": {
          "id": "id_123",
          "organizationId": "org_123",
          "employeeId": "employee_123",
          "baseSalary": 1,
          "hra": 1,
          "dearnessAllowance": 1,
          "conveyanceAllowance": 1,
          "medicalAllowance": 1,
          "specialAllowance": 1,
          "grossSalary": 1,
          "annualCtc": 1,
          "createdAt": 1710201600000,
          "updatedAt": 1710201600000
        },
        "statutoryDeductions": {
          "id": "id_123",
          "organizationId": "org_123",
          "employeeId": "employee_123",
          "pfEnabled": true,
          "pfType": "general",
          "pfPercentage": 1,
          "esiEnabled": true,
          "esiType": "general",
          "esiPercentage": 1,
          "tdsEnabled": true,
          "tdsPercentage": 1,
          "professionalTaxEnabled": true,
          "professionalTaxAmount": 1,
          "createdAt": 1710201600000,
          "updatedAt": 1710201600000
        }
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 1,
    "totalPages": 1
  }
}

`update`

Source: backend/endpoints/hrm-employees/update

Input Fields

Field	Type	Required	Constraints
`id`	`string`	Yes	-
`organizationId`	`string`	Yes	-
`organizationBranchIds`	`array<string>`	No	optional; replaces branch mappings when provided; send [] to clear mappings; nullable
`employeeCode`	`string`	No	nullable
`employeeName`	`string`	No	nullable
`email`	`string`	No	nullable
`phoneNumber`	`string`	No	nullable
`gender`	`string`	No	nullable
`departmentId`	`string`	No	nullable
`designationId`	`string`	No	nullable
`joiningDate`	`string`	No	format: YYYY-MM-DD; nullable
`dateOfBirth`	`string`	No	nullable
`bloodGroup`	`string`	No	nullable
`address`	`string`	No	nullable
`city`	`string`	No	nullable
`state`	`string`	No	nullable
`country`	`string`	No	nullable
`pincode`	`string`	No	nullable
`religion`	`string`	No	nullable
`nationality`	`string`	No	nullable
`qualification`	`string`	No	nullable
`experienceYears`	`number`	No	nullable
`employeeType`	`string`	No	nullable
`status`	`string`	No	nullable
`aadharNumber`	`string`	No	nullable
`panNumber`	`string`	No	nullable
`profileImageUrl`	`string`	No	nullable
`signatureImageUrl`	`string`	No	nullable
`officialEmail`	`string`	No	nullable
`personalEmail`	`string`	No	nullable
`emergencyContactName`	`string`	No	nullable
`emergencyContactNumber`	`string`	No	nullable
`reportingManagerId`	`string`	No	nullable
`workLocation`	`string`	No	nullable
`probationEndDate`	`string`	No	format: YYYY-MM-DD; nullable
`confirmationDate`	`string`	No	format: YYYY-MM-DD; nullable
`lastWorkingDate`	`string`	No	format: YYYY-MM-DD; nullable
`uanNumber`	`string`	No	nullable
`esiNumber`	`string`	No	nullable
`isActive`	`boolean`	No	nullable
`bankDetails`	`object`	No	nullable
`salary`	`object`	No	nullable
`statutoryDeductions`	`object`	No	nullable

Nested Field Structures

`bankDetails`

Field	Type	Required	Constraints
`accountHolderName`	`string`	No	-
`bankName`	`string`	No	-
`branchName`	`string`	No	-
`accountNumber`	`string`	No	-
`ifscCode`	`string`	No	-
`upiId`	`string`	No	-
`isPrimary`	`boolean`	No	nullable

`salary`

Field	Type	Required	Constraints
`baseSalary`	`number`	No	-
`hra`	`number`	No	-
`dearnessAllowance`	`number`	No	-
`conveyanceAllowance`	`number`	No	-
`medicalAllowance`	`number`	No	-
`specialAllowance`	`number`	No	-

`statutoryDeductions`

Field	Type	Required	Constraints
`pfEnabled`	`boolean`	No	-
`pfType`	`string`	No	-
`pfPercentage`	`number`	No	-
`esiEnabled`	`boolean`	No	-
`esiType`	`string`	No	-
`esiPercentage`	`number`	No	-
`tdsEnabled`	`boolean`	No	-
`tdsPercentage`	`number`	No	-
`professionalTaxEnabled`	`boolean`	No	-
`professionalTaxAmount`	`number`	No	-

Branch Mapping Notes

organizationBranchIds is optional.
When organizationBranchIds is provided, it replaces the employee user branch mapping in user_organization_branches.
Send an empty array to clear all branch mappings for that employee user.
If organizationBranchIds is omitted, existing branch mappings are not changed.
Branch IDs are validated against the same organizationId; invalid branch IDs are rejected.

Example Request

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token>" \
  -d '{
  "namespace": "hrmEmployees",
  "apiName": "update",
  "data": {
    "id": "employee_123",
    "organizationId": "org_123",
    "organizationBranchIds": [
      "branch_123"
    ]
  }
}'

Example Response

{ "status": "ok", "data": {} }

Hrm Employee Documents Hrm Employee Salary

Hrm Employees

create

Input Fields

Nested Field Structures

documents item

bankDetails

salary

statutoryDeductions

Branch Mapping Notes

Example Request

Example Response

delete

Input Fields

Example Request

Example Response

getById

Input Fields

Example Request

Example Response

list

Input Fields

Response Notes

Example Request

Response Data Format

Response Data Format Nested Structures

items[] item

items[].documents[] item

items[].bankDetails

items[].salary

items[].statutoryDeductions

Response Data Format Example

Example Response

update

Input Fields

Nested Field Structures

bankDetails

salary

statutoryDeductions

Branch Mapping Notes

Example Request

Example Response

`create`

`documents` item

`bankDetails`

`salary`

`statutoryDeductions`

`delete`

`getById`

`list`

`items[]` item

`items[].documents[]` item

`items[].bankDetails`

`items[].salary`

`items[].statutoryDeductions`

`update`

`bankDetails`

`salary`

`statutoryDeductions`