velz b81ed82511 FIX_HRAPI_IR_DOCS_UPLOAD

2026-04-01 14:37:31 +05:30

16 KiB

Raw Permalink Blame History

Non-EB Claims API — Developer Reference

Version: v1 Base URL: {{base_url}}/api/v1/non-eb-claim Content-Type: application/json (except file upload endpoints — see individual notes) All responses are JSON.

Authentication

Every request must include a valid JWT token in the Authorization header.

Authorization: Bearer <your_jwt_token>

The token is issued at login and identifies the current user.
The API reads the user's name, mobile, and email from the token automatically — you do not need to send contact details separately.
If the token is missing or expired, all endpoints return 401.

Response Envelope

All responses follow this consistent shape:

Success:

{
  "status": true,
  "code": 200,
  ...
}

Error:

{
  "status": false,
  "code": 400,
  "message": "Human-readable error message",
  "errors": { "field": "Specific field error" }
}

errors is only present on 400 validation failures.

Date Format

Input: always send dates as DD-MM-YYYY (e.g. "25-03-2026")
Output: dates in list/history responses are returned as DD-MM-YYYY
Timestamps in history are returned as DD-MM-YYYY hh:mm AM/PM

Endpoints

#	Method	URL	Description
1	`POST`	`/api/v1/non-eb-claim/create`	Raise a new Non-EB claim
2	`POST`	`/api/v1/non-eb-claim/list`	List / search claims
3	`GET`	`/api/v1/non-eb-claim/history/{claim_id}`	Status timeline of a claim
4	`POST`	`/api/v1/non-eb-claim/upload-required-doc`	Upload required IR documents for a claim
5	`GET`	`/api/v1/non-eb-claim/statuses`	List Non-EB claim statuses
6	`POST`	`/api/v1/non-eb-claim/policies`	List Non-EB policies by client (MD5) + branch

1. Create Claim

POST /api/v1/non-eb-claim/create

How it works

The user has already selected a client policy on the previous screen. You send only that policy ID plus the loss details. The server derives everything else (client, branch, insurer, policy number, account manager, initial status) automatically from the policy.

The logged-in user's name, mobile, and email are pulled from their JWT token and stored as the insured contact — you do not send them.

Request

Content-Type: application/json If you are also uploading an asset file, switch to multipart/form-data and include all fields as form fields.

Field	Required	Type	Validation	Notes
`client_policy_id`	Yes	integer	Must exist and be active	Selected policy from the previous screen
`nature_of_loss`	Yes	string	min 3 chars	What happened
`loss_location`	Yes	string	non-empty	Where it happened
`loss_date`	Yes	string	`DD-MM-YYYY`	When it happened
`loss_description`	No	string	—	Required only if `asset_file` is included
`loss_estimate`	No	numeric	—	Approximate value of loss
`claim_number`	No	string	`[a-zA-Z0-9/_-]` only	If already assigned by insurer
`asset_file`	No	file	xlsx/xls/csv/pdf	Asset register file
`asset_id_code[]`	No	array	—	Asset ID codes (one per row)
`serial_no[]`	No	array	—	Serial numbers (parallel to asset_id_code[])
`vehicle_no[]`	No	array	—	Vehicle numbers
`asset_description[]`	No	array	—	Asset descriptions

Do not send: client_id, branch_id, insurer_id, policy_no, acm_id, claim_status_id, insured_contact_name, insured_contact_number, insured_contact_email — these are all derived server-side.

Example Request (JSON)

{
  "client_policy_id": 42,
  "nature_of_loss": "Fire damage to warehouse",
  "loss_location": "Chennai",
  "loss_date": "22-03-2026",
  "loss_description": "Warehouse section B caught fire due to electrical fault",
  "loss_estimate": 500000
}

Example Request (multipart — with asset file)

POST /api/v1/non-eb-claim/create
Content-Type: multipart/form-data

client_policy_id = 42
nature_of_loss   = Fire damage to warehouse
loss_location    = Chennai
loss_date        = 22-03-2026
loss_description = Warehouse section B caught fire
asset_file       = <file>
asset_id_code[]  = AST-001
serial_no[]      = SN-12345
asset_description[] = Industrial generator

Success Response `200`

{
  "status": true,
  "code": 200,
  "claim_id": 123,
  "message": "Non-EB Claim created successfully"
}

Save claim_id — you'll need it for history and document upload.

Error Responses

Code	Scenario	Sample Message
`400`	Validation failed	`"Input validation failed"` + `errors` object
`400`	Asset file sent without `loss_description`	`"Loss Description is required when uploading an asset file."`
`401`	Missing / expired token	`"Unauthorized"`
`404`	`client_policy_id` not found or inactive	`"Client policy not found or inactive"`
`409`	Duplicate claim (same client + loss date + policy no)	`"Duplicate claim found for Client + Loss Date + Policy No combination"`
`422`	Policy type is EB (not Non-EB / Marine)	`"Only Non-EB or Marine policy types are allowed"`
`422`	No claim status configured for policy type	`"No claim status configured for this policy type"`
`500`	DB insert failed	`"Failed to create claim"`

400 Validation Error Example

{
  "status": false,
  "code": 400,
  "message": "Input validation failed",
  "errors": {
    "nature_of_loss": "Nature of Loss is required",
    "loss_date": "Loss Date is required"
  }
}

2. List Claims

POST /api/v1/non-eb-claim/list

How it works

Send a JSON body with optional filters and pagination params. By default, closed/settled/rejected/withdrawn claims are excluded. Pass "show_closed": true to include them.

Results are sorted newest first.

Request

Content-Type: application/json

Field	Required	Type	Default	Notes
`page`	No	integer	`1`	Page number
`per_page`	No	integer	`20`	Max `100`
`client_id`	No	integer	—	Filter by client
`insurer_id`	No	integer	—	Filter by insurer
`policy_type_id`	No	integer	—	Filter by policy type
`claim_status_id`	No	integer	—	Filter by exact status
`claim_number`	No	string	—	Partial match (LIKE)
`nhance_claim_ref_no`	No	string	—	Partial match (LIKE)
`date_type`	No	string	—	`"created_date"` or `"updated_date"`
`start_date`	No	string	—	`DD-MM-YYYY` — used with `date_type`
`end_date`	No	string	—	`DD-MM-YYYY` — used with `date_type`
`show_closed`	No	boolean	`false`	`true` to include settled/closed/rejected/withdrawn

Example Request

{
  "page": 1,
  "per_page": 20,
  "client_id": 5,
  "date_type": "created_date",
  "start_date": "01-03-2026",
  "end_date": "31-03-2026"
}

Success Response `200`

{
  "status": true,
  "code": 200,
  "total": 87,
  "page": 1,
  "per_page": 20,
  "data": [
    {
      "id": 123,
      "claim_number": "CLM/2026/001",
      "nhance_claim_ref_no": "NEB/2026/00123",
      "policy_no": "POL/1234/2026",
      "policy_type_id": 10,
      "claim_status_id": 3,
      "status": "Claim Intimation - Insured",
      "status_display": "Claim Intimation - Insured",
      "policy_type_name": "All Risk",
      "client_name": "ABC Corp",
      "insurer_name": "New India Assurance",
      "loss_date": "2026-03-22",
      "loss_location": "Chennai",
      "nature_of_loss": "Fire damage to warehouse",
      "loss_estimate": "500000",
      "insured_contact_name": "Ravi Kumar",
      "insured_contact_number": "9876543210",
      "acm_name": "Anand",
      "created_date": "22-03-2026",
      "updated_date": "25-03-2026"
    }
  ]
}

When no results match, total is 0 and data is []. The response is still 200.

Error Responses

Code	Scenario
`401`	Missing / expired token

3. Claim History

GET /api/v1/non-eb-claim/history/{claim_id}

How it works

Returns the status progression timeline of a claim — oldest stage first. Only statuses that are configured as user-visible are included. Internal/intermediate statuses used by staff are automatically filtered out.

Each entry shows the status name and when it was reached. Who changed it is not exposed.

URL Parameter

Param	Type	Required	Description
`claim_id`	integer	Yes	The `id` returned from the create endpoint

Example Request

GET /api/v1/non-eb-claim/history/123
Authorization: Bearer <token>

Success Response `200`

{
  "status": true,
  "code": 200,
  "claim_id": 123,
  "history": [
    {
      "status": "Claim Intimation - Insured",
      "changed_at": "22-03-2026 10:15 AM"
    },
    {
      "status": "Under Process",
      "changed_at": "24-03-2026 02:30 PM"
    },
    {
      "status": "Claim Settled",
      "changed_at": "28-03-2026 04:45 PM"
    }
  ]
}

If no history exists yet, history is an empty array [].

Error Responses

Code	Scenario
`401`	Missing / expired token
`404`	Claim not found or inactive

4. Upload Required IR Documents

POST /api/v1/non-eb-claim/upload-required-doc

How it works

Uploads one or more IR documents for a claim. Each file is stored in claim_files with docs_for_ir = 1. The full updated required_docs JSON (checklist) sent by the client is written directly to non_eb_ticket_master.required_docs — the caller is responsible for reflecting any document_received flag changes in the JSON before sending.

Request

Content-Type: multipart/form-data (always — this is a file upload)

Field	Required	Type	Notes
`ticket_id`	Yes	integer	The non-EB claim (ticket) ID
`claim_docs[]`	Yes	file(s)	One or more files; use the same field name for multiple
`claim_doc_names[]`	Yes	string[]	Document name for each uploaded file — index-matched to `claim_docs[]`
`required_docs`	Yes	string (JSON)	Full checklist JSON to persist (e.g. `{"is_action_freeze":false,"docs":[...]}`)

Example Request

POST /api/v1/non-eb-claim/upload-required-doc
Content-Type: multipart/form-data
Authorization: Bearer <token>

ticket_id              = 3
claim_docs[]           = <file1>
claim_docs[]           = <file2>
claim_doc_names[]      = ecard
claim_doc_names[]      = Sample Doc 1
required_docs          = {"is_action_freeze":false,"docs":[{"document_name":"Sample Doc 1","document_received":true},{"document_name":"Sample Doc 2","document_received":false}]}

Success Response `200`

{
  "status": true,
  "code": 200,
  "message": "Files uploaded successfully"
}

Error Responses

Code	Scenario	Message
`400`	No valid files uploaded or `ticket_id` missing	`"Failed to upload the file"`
`401`	Missing / expired token	`"Unauthorized"`

5. List Claim Statuses

GET /api/v1/non-eb-claim/statuses

How it works

Returns all Non-EB claim statuses. Use this to populate status dropdowns in the UI or filter screens. Statuses are ordered by id ASC.

Ticket type is hardcoded to 50 (Non-EB) on the server — you do not need to send it.

Request

No body required. Only the Authorization header is needed.

GET /api/v1/non-eb-claim/statuses
Authorization: Bearer <token>

Success Response `200`

{
  "status": true,
  "code": 200,
  "data": [
    { "id": 1, "claim_status": "Claim Intimation", "display_name": "Claim Intimation" },
    { "id": 2, "claim_status": "Under Process",    "display_name": "Under Process" },
    { "id": 3, "claim_status": "Claim Settled",    "display_name": "Claim Settled" }
  ]
}

display_name is the user-facing label. claim_status is the internal name. Use id when sending claim_status_id as a filter in the list endpoint.

Error Responses

Code	Scenario
`401`	Missing / expired token

6. List Policies by Client + Branch

POST /api/v1/non-eb-claim/policies

How it works

Returns Non-EB and Marine policies for a specific client branch. Use this to populate the policy dropdown before raising a new claim.

The client is identified by an MD5 hash of their numeric ID — the raw integer ID is never exposed to the API consumer.

Request

Content-Type: application/json

Field	Required	Type	Notes
`client_id`	Yes	string	MD5 hash (32-char hex) of the client's numeric ID
`client_branch_id`	Yes	integer	The client branch to filter by

Example Request

{
  "client_id": "d41d8cd98f00b204e9800998ecf8427e",
  "client_branch_id": 3
}

Success Response `200`

{
  "status": true,
  "code": 200,
  "total": 2,
  "data": [
    {
      "id": 10,
      "policy_no": "POL/2026/001",
      "policy_type_id": 50,
      "policy_type_name": "Fire",
      "insurer_id": 7,
      "insurer_name": "New India Assurance",
      "insurer_short_name": "NIA",
      "policy_start_date": "01-04-2025",
      "policy_end_date": "31-03-2026"
    },
    {
      "id": 11,
      "policy_no": "POL/2026/002",
      "policy_type_name": "Marine Cargo",
      "insurer_name": "HDFC Ergo",
      "insurer_short_name": "HDFC",
      "policy_start_date": "01-01-2026",
      "policy_end_date": "31-12-2026"
    }
  ]
}

Only Non-EB and Marine policy types are returned. EB policies are excluded automatically. When no policies exist for the given client + branch, total is 0 and data is [].

How to use in create claim flow

Call this endpoint with the selected client's MD5 and branch ID
Populate a dropdown with the returned policies — display policy_no + policy_type_name to the user
When the user picks a policy, send its id as client_policy_id in the Create Claim request

Error Responses

Code	Scenario	Message
`400`	`client_id` not sent	`"client_id is required"`
`400`	`client_id` is not a valid MD5 hash	`"client_id must be a valid MD5 hash"`
`400`	`client_branch_id` not sent or zero	`"client_branch_id is required"`
`401`	Missing / expired token	`"Unauthorized"`

Common Error Reference

HTTP Code	Meaning	When it happens
`200`	OK	Request succeeded
`400`	Bad Request	Validation failed — check `errors` object
`401`	Unauthorized	Token missing, invalid, or expired
`404`	Not Found	Resource doesn't exist or is inactive
`409`	Conflict	Duplicate claim detected
`415`	Unsupported Media Type	File type not allowed
`422`	Unprocessable	Valid request but business rule blocks it
`423`	Locked	Checklist is frozen — no uploads allowed
`500`	Server Error	Something failed on the backend

Tips for Integration

Checking status field: Always check response.status === true before proceeding — do not rely solely on the HTTP status code.

Pagination: Use total, page, and per_page from the list response to build pagination controls. Total number of pages = Math.ceil(total / per_page).

Asset rows (create claim): Send parallel arrays. Row 0 of asset_id_code[], serial_no[], vehicle_no[], asset_description[] form one asset entry. Leave a value empty string if not applicable for that row.

Document name matching (upload): Always populate the document_name field from the checklist data returned by the server — never let users type it freehand. The match is case-sensitive exact.

Re-upload: Uploading a document that already has document_received: true is allowed. The new file is saved alongside the previous one and document_received stays true.

16 KiB Raw Permalink Blame History

Non-EB Claims API — Developer Reference

Authentication

Response Envelope

Date Format

Endpoints

1. Create Claim

How it works

Request

Example Request (JSON)

Example Request (multipart — with asset file)

Success Response 200

Error Responses

400 Validation Error Example

2. List Claims

How it works

Request

Example Request

Success Response 200

Error Responses

3. Claim History

How it works

URL Parameter

Example Request

Success Response 200

Error Responses

4. Upload Required IR Documents

How it works

Request

Example Request

Success Response 200

Error Responses

5. List Claim Statuses

How it works

Request

Success Response 200

Error Responses

6. List Policies by Client + Branch

How it works

Request

Example Request

Success Response 200

How to use in create claim flow

Error Responses

Common Error Reference

Tips for Integration

16 KiB

Raw Permalink Blame History

Success Response `200`

Success Response `200`

Success Response `200`

Success Response `200`

Success Response `200`

Success Response `200`