# 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:**
```json
{
  "status": true,
  "code": 200,
  ...
}
```

**Error:**
```json
{
  "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)

```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`

```json
{
  "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

```json
{
  "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

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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

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

### Success Response `200`

```json
{
  "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`.