Claims API Reference

This section provides comprehensive documentation for the Claims API, enabling external systems and clients to interact with the faizanGeek Claim Processing System for managing claims. The API allows for submitting new claims, retrieving existing claim details, updating claim information, and managing claim statuses.

Introduction

The Claims API serves as the primary interface for all claim-related operations. It is designed to be a RESTful API, offering predictable resource-oriented URLs, and using HTTP response codes to indicate API errors. All API responses are in JSON format.

Authentication

All endpoints in the Claims API require authentication. The faizanGeek Claim Processing System uses OAuth2 for authorization, typically with JWT (JSON Web Tokens) as bearer tokens. To access these endpoints, you must include a valid JWT in the Authorization header of your requests.

Example Request Header:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Refer to the Authentication Guide for details on obtaining an access token.

Claims Endpoints

The following are the available endpoints for managing claims:

1. Submit a New Claim

Submits a new claim to the system. The system will assign a unique claimId and set the initial claimStatus to "Submitted".

URL: /api/claims
Method: POST
Description: Creates a new claim entry.
Request Body: application/json

| Field | Type | Description | Required | | :---------- | :------ | :------------------------------------------------ | :------- | | userId | Long | The ID of the user submitting the claim. | Yes | | claimAmount | Double | The monetary amount of the claim. | Yes | | claimType | String | The type or category of the claim (e.g., "Medical", "Travel"). | Yes |

Example Request Body:
```
{
  "userId": 101,
  "claimAmount": 1500.75,
  "claimType": "Medical"
}
```

Responses:

201 Created: The claim was successfully submitted and created.
400 Bad Request: Invalid input provided.

Example Success Response (201 Created):

{
  "claimId": 1,
  "userId": 101,
  "claimDate": "2023-10-27T10:00:00.000+00:00",
  "claimAmount": 1500.75,
  "claimType": "Medical",
  "claimStatus": "Submitted",
  "lastUpdated": "2023-10-27T10:00:00.000+00:00"
}

2. Get All Claims for a User

Retrieves a list of all claims associated with a specific user.

URL: /api/claims/user/{userId}
Method: GET
Description: Fetches all claims for the specified userId.
Path Parameters:

| Parameter | Type | Description | | :-------- | :----- | :---------------------- | | userId | Long | The ID of the user. |

Responses:

200 OK: Returns a list of ClaimDTO objects.
404 Not Found: No claims found for the specified user ID.

Example Success Response (200 OK):

[
  {
    "claimId": 1,
    "userId": 101,
    "claimDate": "2023-10-27T10:00:00.000+00:00",
    "claimAmount": 1500.75,
    "claimType": "Medical",
    "claimStatus": "Submitted",
    "lastUpdated": "2023-10-27T10:00:00.000+00:00"
  },
  {
    "claimId": 2,
    "userId": 101,
    "claimDate": "2023-10-26T14:30:00.000+00:00",
    "claimAmount": 500.00,
    "claimType": "Travel",
    "claimStatus": "Approved",
    "lastUpdated": "2023-10-27T09:15:00.000+00:00"
  }
]

3. Get Claim by ID

Retrieves details for a specific claim using its unique ID.

URL: /api/claims/{claimId}
Method: GET
Description: Fetches a single claim by its ID.
Path Parameters:

| Parameter | Type | Description | | :-------- | :----- | :-------------------- | | claimId | Long | The unique ID of the claim. |

Responses:

200 OK: Returns the ClaimDTO object.
404 Not Found: Claim with the specified ID does not exist.

Example Success Response (200 OK):

{
  "claimId": 1,
  "userId": 101,
  "claimDate": "2023-10-27T10:00:00.000+00:00",
  "claimAmount": 1500.75,
  "claimType": "Medical",
  "claimStatus": "Submitted",
  "lastUpdated": "2023-10-27T10:00:00.000+00:00"
}

4. Update an Existing Claim

Updates the details of an existing claim.

URL: /api/claims/{claimId}
Method: PUT
Description: Modifies an existing claim identified by claimId.
Path Parameters:

| Parameter | Type | Description | | :-------- | :----- | :-------------------- | | claimId | Long | The unique ID of the claim to update. |
Request Body: application/json

| Field | Type | Description | Required | | :---------- | :------ | :------------------------------------------------ | :------- | | claimAmount | Double | The updated monetary amount of the claim. | Yes | | claimType | String | The updated type or category of the claim. | Yes | | claimStatus | String | The updated status of the claim. (Use with caution; prefer PATCH /claims/{claimId}/status for status-only updates) | Yes | | userId | Long | (Optional) The ID of the user (typically not changed here). | No |

Example Request Body:
```
{
  "userId": 101,
  "claimAmount": 1600.00,
  "claimType": "Medical Reimbursement",
  "claimStatus": "Submitted"
}
```

Responses:

200 OK: The claim was successfully updated.
400 Bad Request: Invalid input provided.
404 Not Found: Claim with the specified ID does not exist.

Example Success Response (200 OK):

{
  "claimId": 1,
  "userId": 101,
  "claimDate": "2023-10-27T10:00:00.000+00:00",
  "claimAmount": 1600.00,
  "claimType": "Medical Reimbursement",
  "claimStatus": "Submitted",
  "lastUpdated": "2023-10-27T11:30:00.000+00:00"
}

5. Update Claim Status

Updates only the status of a specific claim. This is often used for workflow transitions.

URL: /api/claims/{claimId}/status
Method: PATCH
Description: Updates the status of the claim identified by claimId.
Path Parameters:

| Parameter | Type | Description | | :-------- | :----- | :-------------------- | | claimId | Long | The unique ID of the claim. |
Request Body: application/json

| Field | Type | Description | Required | | :---------- | :------ | :------------------------------------------------ | :------- | | newStatus | String | The new status to assign to the claim (e.g., "Approved", "Denied", "Processed"). | Yes |

Example Request Body:
```
{
  "newStatus": "Approved"
}
```
Responses:
- 200 OK: The claim status was successfully updated.
- 400 Bad Request: Invalid status provided or other validation error.
- 404 Not Found: Claim with the specified ID does not exist.
Example Success Response (200 OK): (Typically, a full ClaimDTO or just a confirmation message would be returned)
```
{
  "message": "Claim status updated successfully.",
  "claimId": 1,
  "status": "Approved"
}
```

6. Get Claim Status

Retrieves only the current status of a specific claim.

URL: /api/claims/{claimId}/status
Method: GET
Description: Fetches the current status of a claim by its ID.
Path Parameters:

| Parameter | Type | Description | | :-------- | :----- | :-------------------- | | claimId | Long | The unique ID of the claim. |
Responses:
- 200 OK: Returns the current status as a string.
- 404 Not Found: Claim with the specified ID does not exist.
Example Success Response (200 OK):
```
{
  "claimId": 1,
  "status": "Approved"
}
```

7. Delete a Claim

Deletes an existing claim from the system.

URL: /api/claims/{claimId}
Method: DELETE
Description: Removes the claim identified by claimId.
Path Parameters:

| Parameter | Type | Description | | :-------- | :----- | :-------------------- | | claimId | Long | The unique ID of the claim to delete. |
Responses:
- 204 No Content: The claim was successfully deleted.
- 404 Not Found: Claim with the specified ID does not exist.
Example Success Response (204 No Content): (No response body for a 204 status code)