Download Inception API

Base path: /employeeRest

Generates an Excel (.xlsx) export of enrolled employees for the selected client, branch, and policy. The API returns a download URL; the file is fetched in a second request.

Authentication: JWT + app signature (same filters as other employeeRest routes)

HTTP status: Responses use HTTP 200 (or 500 on unhandled exceptions). Check JSON status and code for success or failure.

Endpoints

Route	Method	Description
`/employeeRest/download_inception`	`POST`	Generate Excel export
`/employeeRest/download_file?file={filename}`	`GET`	Download generated file

1. Generate inception export


Method	`POST`
URL	`/employeeRest/download_inception`
Content-Type	`application/json` or `application/x-www-form-urlencoded`

Request body

Field	Required	Type	Description
`client`	No	integer / string	Client ID (or MD5 client hash)
`branch`	No	integer	Client branch ID
`policies`	No	integer	Client policy ID
`status`	No	array / string	Accepted in payload; export currently uses enrolled status only
`empCode`	No	string	Filter by employee code
`empName`	No	string	Filter by employee name (partial match)

Sample request (JSON)

POST /employeeRest/download_inception
Content-Type: application/json
Authorization: Bearer {token}

{
  "client": 12,
  "branch": 1,
  "policies": 12,
  "status": ["enrolled"],
  "empCode": "",
  "empName": ""
}

Sample request (form)

POST /employeeRest/download_inception
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {token}

client=12&branch=1&policies=12&empCode=&empName=

Success response

{
  "status": true,
  "code": 200,
  "message": "Inception export generated successfully.",
  "data": {
    "downloadUrl": "https://example.com/employeeRest/download_file?file=inception_export_20260625_121435.xlsx",
    "filename": "inception_export_20260625_121435.xlsx",
    "rowCount": 9
  }
}

Error responses

Invalid JSON

{
  "status": false,
  "code": 400,
  "message": "Invalid JSON request body.",
  "data": []
}

No data

{
  "status": false,
  "code": 404,
  "message": "No data found for given filters.",
  "data": []
}

Export / server error

{
  "status": false,
  "code": 500,
  "message": "Failed to generate inception export.",
  "data": []
}

2. Download file

After a successful export, download the file using data.downloadUrl.

GET /employeeRest/download_file?file=inception_export_20260625_121435.xlsx
Authorization: Bearer {token}

Query param	Required	Description
`file`	Yes	Filename from the generate response (`data.filename`)

Returns the .xlsx file as a download. Only the basename is allowed (path traversal is blocked).

Excel columns

Each row includes (with S.NO as the first column):

Column	Source
S.NO	Row index
Emp ID	Employee code
Name of Emp/Dep	Employee / dependent name
DOB	Date of birth
Gender	Gender
Relationship	Relationship
Basic cover SI	Sum insured
Date of Coverage	Coverage date
DOJ	Date of joining
Basic Pay	Basic pay
Band/Grade	Band / grade
Designation	Designation
Phone	Mobile
Email	Corporate email
PRE EXISTING AILMENTS	Pre-existing flag
change_event	Change event
date_of_exit	Exit date
reason_for_exit	Exit reason
unit	Unit

Only active employees with enrolled policy status are included.

Flow

sequenceDiagram
    participant Client
    participant API as employeeRest/download_inception
    participant Storage as writable/exports

    Client->>API: POST filters (client, branch, policies, ...)
    API->>Storage: Save inception_export_*.xlsx
    API-->>Client: JSON with downloadUrl + filename
    Client->>API: GET employeeRest/download_file?file=...
    API-->>Client: Excel file download

Notes

Files are stored under writable/exports/ and named inception_export_{Ymd_His}.xlsx.
Use the returned downloadUrl promptly; files may be removed by other processes.

4.3 KiB Raw Blame History