nhance/docs/dependent-approval-apis.md

Dependent Approval APIs

Base path: /employeeRest/

Auth: JWT + App-Signature (authJWT, appSignature)

---

1. Get Employee Policy (Dependent Add UI)

Method	GET
URL	/employeeRest/getEmployeePolicy
Handler	EmployeeRestController::getEmployeeByPolicyv2

Note: Route currently maps to getEmployeePolicyv2 (method missing). Intended handler is getEmployeeByPolicyv2.

Query Params

Param	Required	Description
id	Yes	Self employee id
emp_code	Yes	Employee code
client_id	Yes	Client id
client_branch_id	Yes	Branch id
client_policy_id	Yes	GMC client policy id

Success Response

{
  "status": "success",
  "code": 200,
  "message": "Employee policy and dependent details fetched successfully",
  "data": {
    "...": "policy details, mapped_family_floaters, allowed_relationships"
  },
  "EmployeePolicy": [],
  "add_button_show": true
}

Error Responses

code	message
400	Required parameters missing
400	Only GMC policy is supported for dependent add
404	Employee policy not found
500	Something went wrong while fetching employee policy details

---

2. Add / Update Dependent (Pending Approval)

Method	POST
URL	/employeeRest/addEmployeeAndDependence
Handler	EmployeeRestController::addEmployeeAndDependencev2
Content-Type	application/json

Request Body

JSON array of dependent objects:

[
  {
    "emp_code": "E001",
    "client_id": 10,
    "client_branch_id": 5,
    "client_policy_id": 100,
    "name": "John Doe",
    "relationship": "Spouse",
    "dob": "01/01/1990",
    "basic_cover_si": 500000,
    "dependent_effective_date": "01/08/2026",
    "hr_id": 12
  }
]

Fields

Field	Required	Notes
emp_code	Yes	Parent employee code
client_id	Yes	Client id
client_branch_id	Yes	Used for premium update
client_policy_id	Yes	Client policy id
name	Yes	Dependent name
relationship	Yes	e.g. Spouse / Son / Daughter
dob	Yes	Converted to Y-m-d
basic_cover_si	Yes	Sum insured
dependent_effective_date	Yes (new)	Coverage start date
hr_id	No	If set → created by HR; else USER
id	No	If set → update existing dependent

Behavior

• Creates/updates dependent with emp_status = pending_approval
• Creates employee policy with status = pending_approval
• Recalculates premium for the family

Success Response

{
  "status": "success",
  "code": 200,
  "data": []
}

Error Responses

code	data
404	Requested parameters are required
404	No Matches
500	Exception message

---

3. Delete Dependent

Method	GET
URL	/employeeRest/deleteDependence
Handler	EmployeeRestController::deleteDependencev2

Query Params

Param	Required	Description
id	Yes	Dependent employee id

Behavior

Soft-deletes employee and policy:

• emp_status / status → truncated
• is_active → 0

Success Response

{
  "status": "success",
  "code": 200,
  "data": []
}

Error Responses

code	data
404	[] (missing id)
500	Exception message

---

4. List Pending Approval Dependents

Method	GET
URL	/employeeRest/getPendingApprovalDependents
Handler	EmployeeRestController::getPendingApprovalDependents

Query Params

Param	Required	Description
client_id	No	Client filter
client_branch_id / branch_id	No	Branch filter
client_policy_id / policy_id	No	Policy filter
search	No	Name / emp_code search

Success Response

{
  "status": "success",
  "code": 200,
  "message": "Pending approval dependents fetched successfully",
  "data": []
}

Error Responses

code	message
404	No pending approval dependents found
500	Exception message

---

5. Approve / Reject Dependent

Method	POST
URL	/employeeRest/processDependentAdd
Handler	EmployeeRestController::processDependentAdd
Content-Type	application/json

Request Body

{
  "employee_id": 123,
  "client_policy_id": 100,
  "status": "approved",
  "hr_id": 12
}

Fields

Field	Required	Notes
employee_id	Yes	Dependent employee id
client_policy_id	Yes	Policy id
status	Yes	approved or rejected (default: approved)
hr_id	No	If set → approved by HR; else ACM

Behavior

status	Employee	Policy
approved	emp_status = active	status = active
rejected	emp_status = rejected, is_active = 0	status = rejected, is_active = 0

Success Response

{
  "status": "success",
  "code": 200,
  "data": []
}

Error Responses

code	data
400	Request body is required
400	employee_id is required
400	client_policy_id is required
400	status is invalid
400	Dependent is already approved
400	Dependent is not pending approval
404	Employee not found or inactive
404	Employee policy not found or inactive
500	Failed to update employee/policy status

---

Typical Flow

1. getEmployeePolicy
      → show family slots / add buttons

2. addEmployeeAndDependence
      → submit dependent → pending_approval

3. getPendingApprovalDependents
      → HR / ACM review list

4. processDependentAdd
      → approve or reject

5. deleteDependence
      → soft-delete if needed