nhance/nonebapidocs.md

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

1. Call this endpoint with the selected client's MD5 and branch ID
2. Populate a dropdown with the returned policies — display policy_no + policy_type_name to the user
3. 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.