{"info":{"_postman_id":"037fae41-910c-433a-bbd8-744c576529a3","name":"Zorvyn_Assignment","description":"

Zorvyn Finance Dashboard API Collection.

This API powers a secure, role-based financial dashboard system designed to manage users, process financial records, and generate analytics. The system follows a clean and structured approach, with endpoints grouped into logical modules for better usability and scalability.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"34605710","collectionId":"037fae41-910c-433a-bbd8-744c576529a3","publishedId":"2sBXiqDo8e","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-04-04T19:06:51.000Z"},"item":[{"name":"Authentication","item":[{"name":"login","id":"4bfa7d5f-bfbf-4a8c-915a-dfe9efcb2e66","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\" : \"gugulothsammaiah5@gmail.com\",\n \"password\" : \"Sammaiah@004\"\n}\n\n// {\n// \"email\" : \"sammaiahguguloth3@gmail.com\",\n// \"password\" : \"2q0rmqym\"\n// }\n\n// {\n// \"email\" : \"sammaiahguguloth3@gmail.com\",\n// \"password\" : \"2q0rmqym\"\n// }\n\n// {\n// \"email\" : \"sammaiahguguloth.connect@gmail.com\",\n// \"password\" : \"7dcgwzez\"\n// }\n\n\n\n","options":{"raw":{"language":"json"}}},"url":"http://localhost:5000/api/v1/auth/login","description":"

Endpoint Description

This endpoint is used to authenticate a user into the Finance Dashboard system and securely issue an HTTP-only JWT session cookie. Access is public, but the user's account status in the database must be 'active' for successful authentication.

Request

Method: POST
\n
Endpoint: http://localhost:5000/api/v1/auth/login
\n

Request Body

The request body must be in JSON format and should contain the following parameters:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description
email	string	The user's registered email address (required).
password	string	The user's password (required).

Example Request Body:

{\n  \"email\": \"user@example.com\",\n  \"password\": \"your_password\"\n}\n\n

Response

Upon a successful login, the server responds with a status code of 200 OK and attaches a jwt cookie (HTTP-only) directly to the response headers. The JSON response body will contain the following structure:

status (string): Indicates the status of the request, typically 'success'.
\n
data (object): Contains the user's profile information:
\n
- name (string): The name of the user.
  \n
- email (string): The email address of the user.
  \n
- role (string): The role of the user within the application.
  \n
- isPasswordReset (boolean): Indicates if the user has reset their password.
  \n
\n

Example Response:

{\n  \"status\": \"success\",\n  \"data\": {\n    \"name\": \"User Name\",\n    \"email\": \"user@example.com\",\n    \"role\": \"user_role\",\n    \"isPasswordReset\": true\n  }\n}\n\n

Error Responses

400 Bad Request: Triggered if the request body is missing required fields or if the data types mismatch.
\n
401 Unauthorized: Triggered for invalid email/password combinations.
\n
403 Forbidden: Triggered if the user exists and credentials are correct, but their account status is marked as 'inactive'.
\n

Notes

The password hash will never be returned in the payload.
\n
Authorization is handled statelessly via cookies rather than Bearer tokens in the response headers.
\n

This endpoint is used for user authentication, allowing users to log in to the application. It accepts user credentials and returns an authentication token along with user details upon successful login.

Request

Method: POST
\n
Endpoint: http://localhost:5000/api/v1/auth/login
\n

Headers

Content-Type: application/json
Ensure that the request body is formatted as JSON.

Request Body

The request body must be in JSON format and should contain the following parameters:

email (string): The email address of the user attempting to log in.
\n
password (string): The password associated with the user's account.
\n

Example Request Body:

{\n  \"email\": \"user@example.com\",\n  \"password\": \"your_password\"\n}\n\n

Response

Upon a successful login, the server responds with a status code of 200 and a JSON object containing the following structure:

status (string): Status of the request (usually empty on success).
\n
token (string): A JWT token that can be used for subsequent authenticated requests.
\n
data (object): Contains user information, structured as follows:
\n
- user (object): Details about the authenticated user:
  \n
  - _id (string): Unique identifier for the user.
    \n
  - name (string): The name of the user.
    \n
  - email (string): The email address of the user.
    \n
  - role (string): The role of the user within the application.
    \n
  - status (string): The current status of the user account.
    \n
  - isPasswordReset (boolean): Indicates if the user has reset their password.
    \n
  - createdAt (string): Timestamp of when the user was created.
    \n
  - updatedAt (string): Timestamp of the last update to the user information.
    \n
  - __v (number): Version key for the user document.
    \n
  \n
\n

Example Response:

{\n  \"status\": \"\",\n  \"token\": \"your_jwt_token\",\n  \"data\": {\n    \"user\": {\n      \"_id\": \"user_id\",\n      \"name\": \"User Name\",\n      \"email\": \"user@example.com\",\n      \"role\": \"user_role\",\n      \"status\": \"active\",\n      \"isPasswordReset\": true,\n      \"createdAt\": \"timestamp\",\n      \"updatedAt\": \"timestamp\",\n      \"__v\": 0\n    }\n  }\n}\n\n

Notes

Ensure that the email and password are correct to receive a successful response.
\n
The token returned in the response should be stored securely for use in subsequent requests that require authentication.
\n

This endpoint allows users to authenticate and obtain a token for accessing protected resources. It requires the user's email and password to be sent in the request body.

\n","urlObject":{"path":["auth","login"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"4bfa7d5f-bfbf-4a8c-915a-dfe9efcb2e66"},{"name":"Change password","id":"022b2704-4d11-4aaa-aee0-b45d25e1a359","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"currentPassword\" : \"2q0rmqym\",\n \"newPassword\" : \"Sammaiah@004\"\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:5000/api/v1/auth/change-password","description":"

Change Password Endpoint

This endpoint allows users to change their account password. It requires the current password and the new password as part of the request payload.

Request

Method: POST
\n
Endpoint: http://localhost:5000/api/v1/auth/change-password
\n
Content-Type: application/json
\n

Request Body Parameters

The request body must be sent in JSON format and should include the following parameters:

currentPassword (string): The user's current password that needs to be verified.
\n
newPassword (string): The new password that the user wishes to set.
\n

Example Request Body

{\n  \"currentPassword\": \"your_current_password\",\n  \"newPassword\": \"your_new_password\"\n}\n\n

Expected Response

Upon a successful password change, the API will return a response indicating the success of the operation. The exact structure of the response may vary, but it typically includes a status message confirming that the password has been updated.

Notes

Ensure that the new password meets any security requirements set by the application (e.g., minimum length, complexity).
\n
If the current password is incorrect, the API will return an error response indicating the failure of the password change attempt.
\n

\n","urlObject":{"path":["auth","change-password"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"022b2704-4d11-4aaa-aee0-b45d25e1a359"}],"id":"c1bdf0c5-ca77-48f4-9100-8787f9856fdf","description":"

This folder handles all user session management, identity verification, and credential updates for the Finance Dashboard system.

The API relies on stateless JWT tokens securely passed via HTTP-only cookies. Once authenticated, Postman will automatically save and attach the jwt cookie to your subsequent requests, avoiding the need to manually pass Bearer tokens to access the protected Admin, Records, and Analytics routes.

Key constraints:

Access Control: Only users with an active status can log in; suspended users will be immediately rejected.
\n
Onboarding: New users logging in with a system-generated password are required to change their credentials upon their first successful login.
\n

\n","_postman_id":"c1bdf0c5-ca77-48f4-9100-8787f9856fdf"},{"name":"Admin","item":[{"name":"Add user","id":"01f53162-0857-4ba0-9677-bb81af067fb8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"// {\n// \"name\" : \"Sam Analyst\",\n// \"email\" : \"sammaiahguguloth3@gmail.com\",\n// \"role\" : \"analyst\"\n// }\n\n\n{\n \"name\" : \"Sam Viewver\",\n \"email\" : \"sammaiahguguloth.connect@gmail.com\",\n \"role\" : \"viewer\"\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:5000/api/v1/admin/users","description":"

Add User Endpoint

This endpoint allows you to add a new user to the system. It accepts a POST request to the specified URL.

Request Method

POST

Endpoint

http://localhost:5000/api/v1/admin/users

Request Body Parameters

The request body must be a JSON object containing the following parameters:

name (string): The full name of the user being added.
\n
email (string): The email address of the user being added. This should be a valid email format.
\n
role (string): The role assigned to the user. This could be values such as \"viewer\", \"editor\", \"admin\", etc.
\n

Expected Response Format

Upon a successful request, the API will return a response indicating the status of the operation, typically including the newly created user's details or a confirmation message. The response will be in JSON format.

Ensure that all required fields are included in the request body to avoid errors.

\n","urlObject":{"path":["admin","users"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"01f53162-0857-4ba0-9677-bb81af067fb8"},{"name":"Get users","id":"78774627-ebeb-4ba7-aaae-773df2ef321e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://localhost:5000/api/v1/admin/users","description":"

Overview

Name: Get All Users
\n
Endpoint: GET /api/v1/admin/users
\n
Access Control: Private & Restricted. Requires a valid JWT token of a user with the admin role.
\n
Description: This endpoint retrieves a complete list of all users registered on the platform. It is strictly reserved for administrative auditing and user management purposes.
\n

Request Details

Headers:
\n
- Authorization: Bearer
\n
Body: None (GET request)
\n

Responses

200 OK (Success)
\n
- Triggered when the request is authorized and the list of users is successfully fetched.
  \n
- { \"status\": \"success\", \"results\": 2, \"data\": { \"users\": [ { \"_id\": \"\", \"name\": \"\", \"email\": \"\", \"role\": \"\", \"status\": \"\", \"isPasswordReset\": , \"createdAt\": \"\" }, { \"_id\": \"\", \"name\": \"\", \"email\": \"\", \"role\": \"\", \"status\": \"\", \"isPasswordReset\": , \"createdAt\": \"\" } ] }}
  \n
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing from the headers, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who is not an Admin (e.g., Analyst or Viewer) attempts to access this endpoint.
\n

This endpoint retrieves a list of users from the admin panel. It is primarily used for administrative purposes, allowing administrators to view all registered users in the system.

Request

Method: GET
\n
URL: http://localhost:5000/api/v1/admin/users
\n

Response

The response will contain a JSON object with the following structure:

users: An array of user objects, each containing details about a user. The user object may include the following fields:
\n
- id: Unique identifier for the user.
  \n
- name: The name of the user.
  \n
- email: The email address of the user.
  \n
- role: The role assigned to the user (e.g., admin, user).
  \n
- status: The current status of the user account (e.g., active, inactive).
  \n
\n

Example Response

{\n  \"users\": [\n    {\n      \"id\": \"123\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"role\": \"admin\",\n      \"status\": \"active\"\n    },\n    {\n      \"id\": \"124\",\n      \"name\": \"Jane Smith\",\n      \"email\": \"jane.smith@example.com\",\n      \"role\": \"user\",\n      \"status\": \"inactive\"\n    }\n  ]\n}\n\n

Notes

This endpoint does not require any request body.
\n
Ensure that appropriate authentication and authorization are in place to access this endpoint, as it deals with sensitive user data.
\n

\n","urlObject":{"path":["admin","users"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"78774627-ebeb-4ba7-aaae-773df2ef321e"},{"name":"Update user status","id":"984f29f8-a49d-40ed-b8c6-787cc9cb49bd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"status\" : \"inactive\"\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:5000/api/v1/admin/users/69cf925456810aeefcd78981/status","description":"

Overview

Name: Update User Status
\n
Endpoint: PATCH /api/v1/admin/users/:id/status
\n
Access Control: Private & Restricted. Requires a valid JWT token of a user with the admin role.
\n
Description: This endpoint allows administrators to activate or deactivate a user's account. Setting a user's status to 'inactive' will instantly restrict them from logging in or making any verified requests.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Path Parameters:
\n
- id (string, required): The unique MongoDB ObjectId of the target user.
\n
Body (raw JSON):
\n
- status (string, required): The target status of the user's account. Acceptable enum values are typically 'active' and 'inactive'.
\n

Responses

200 OK (Success)
\n
- Triggered when the user's status is successfully updated.
  \n
- { \"status\": \"success\", \"data\": { \"user\": { \"_id\": \"60d0fe4f5311236168a109ca\", \"name\": \"Jane Smith\", \"email\": \"janesmith@example.com\", \"role\": \"analyst\", \"status\": \"inactive\", \"updatedAt\": \"2023-11-03T14:20:00.000Z\" } } }
  \n
\n
400 Bad Request (Validation Error)
\n
- Triggered if the status field is missing from the body or contains an invalid value (e.g., trying to set it to 'pending' instead of 'active' or 'inactive').
  \n
- Triggered if the id in the URL is not a valid MongoDB ObjectId format.
  \n
\n
404 Not Found
\n
- Triggered if the provided id is valid but no user with that ID exists in the database.
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who is not an Admin attempts to access this endpoint.
\n

This endpoint allows you to update the status of a specific user in the system. By sending a PATCH request to the designated URL, you can change the user's status to reflect their current state, such as \"active\" or \"inactive\".

Request

Method: PATCH
\n
URL: http://localhost:5000/api/v1/admin/users/{user_id}/status
\n

Path Parameters

user_id (string): The unique identifier of the user whose status you want to update. In the example, it is 69cf925456810aeefcd78981.

Request Body

The request body must be a JSON object containing the following key:

status (string): The new status for the user. Possible values include \"active\", \"inactive\", etc.

Example Request:

PATCH http://localhost:5000/api/v1/admin/users/69cf925456810aeefcd78981/status\nContent-Type: application/json\nAuthorization: Bearer {your_jwt_token}\n{\n  \"status\": \"inactive\"\n}\n\n

Response

Upon a successful request, the server will respond with a status code indicating the result of the operation. The response body typically includes a confirmation of the updated status.

Response Structure

status (string): A message indicating the success or failure of the update operation.
\n
data (object): Contains the updated user information.
\n
- user (object): The user whose status was updated.
  \n
  - _id (string): The unique identifier of the user.
    \n
  - status (string): The new status of the user.
    \n
  - updatedAt (string): The timestamp of when the status was updated.
    \n
  \n
\n

Example Response:

{\n  \"status\": \"success\",\n  \"data\": {\n    \"user\": {\n      \"_id\": \"69cf925456810aeefcd78981\",\n      \"status\": \"inactive\",\n      \"updatedAt\": \"2023-11-03T14:20:00.000Z\"\n    }\n  }\n}\n\n

Summary

This API endpoint is essential for managing user statuses within the application, allowing administrators to effectively control user access and activity based on their current status.

Name: Update User Status
\n
Endpoint: PATCH /api/v1/admin/users/:id/status
\n
Access Control: Private & Restricted. Requires a valid JWT token of a user with the admin role.
\n
Description: This endpoint allows administrators to activate or deactivate a user's account. Setting a user's status to 'inactive' will instantly restrict them from logging in or making any verified requests.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Path Parameters:
\n
- id (string, required): The unique MongoDB ObjectId of the target user.
\n
Body (raw JSON):
\n
- status (string, required): The target status of the user's account. Acceptable enum values are typically 'active' and 'inactive'.
\n

Responses

200 OK (Success)
\n
- Triggered when the user's status is successfully updated.
  \n
- { \"status\": \"success\", \"data\": { \"user\": { \"_id\": \"60d0fe4f5311236168a109ca\", \"name\": \"Jane Smith\", \"email\": \"janesmith@example.com\", \"role\": \"analyst\", \"status\": \"inactive\", \"updatedAt\": \"2023-11-03T14:20:00.000Z\" } } }
  \n
\n
400 Bad Request (Validation Error)
\n
- Triggered if the status field is missing from the body or contains an invalid value (e.g., trying to set it to 'pending' instead of 'active' or 'inactive').
  \n
- Triggered if the id in the URL is not a valid MongoDB ObjectId format.
  \n
\n
404 Not Found
\n
- Triggered if the provided id is valid but no user with that ID exists in the database.
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who is not an Admin attempts to access this endpoint.
\n

Request

Method: PATCH
\n
URL: http://localhost:5000/api/v1/admin/users/{user_id}/status
\n

Path Parameters

user_id (string): The unique identifier of the user whose status you want to update. In the example, it is 69cf925456810aeefcd78981.

Request Body

The request body must be a JSON object containing the following key:

status (string): The new status for the user. Possible values include \"active\", \"inactive\", etc.

Example Request:

PATCH http://localhost:5000/api/v1/admin/users/69cf925456810aeefcd78981/status\nContent-Type: application/json\n{\n  \"status\": \"inactive\"\n}\n\n

Response

Upon a successful request, the server will respond with a status code indicating the result of the operation. The response body typically includes a confirmation of the updated status.

Response Structure

status (string): A message indicating the success or failure of the update operation.
\n
user_id (string): The unique identifier of the user whose status was updated.
\n
updated_status (string): The new status of the user.
\n

Example Response:

{\n  \"status\": \"success\",\n  \"user_id\": \"69cf925456810aeefcd78981\",\n  \"updated_status\": \"inactive\"\n}\n\n

Summary

This API endpoint is essential for managing user statuses within the application, allowing administrators to effectively control user access and activity based on their current status.

\n","urlObject":{"path":["admin","users","69cf925456810aeefcd78981","status"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"984f29f8-a49d-40ed-b8c6-787cc9cb49bd"}],"id":"3a88cb3a-2d02-4d9d-9fe9-162bfa957946","description":"

Contains all restricted administrative APIs. Actions here require an Admin-level JWT token and include user creation, status toggling, and core record management.

\n","_postman_id":"3a88cb3a-2d02-4d9d-9fe9-162bfa957946"},{"name":"Records","item":[{"name":"Create record","id":"2bc039de-e643-4cd9-8e73-f48f8fcb5eea","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"description":"

Overview

Name: Create Record
\n
Endpoint: POST /api/v1/records
\n
Access Control: Private & Restricted. Requires a valid JWT token of a user with the admin role.
\n
Description: This endpoint allows administrators to add a new financial transaction (income or expense) to the system. Upon creation, the record is automatically linked to the administrator who created it via the createdBy field.
\n

Request Details

Headers:

Content-Type: application/json: Specifies the media type of the resource.
\n
Authorization: Bearer : A valid JWT token for authentication, required for access.
\n

Body (raw JSON):

amount (number, required): A positive numeric value representing the transaction amount.
\n
type (string, required): The transaction classification. Must be strictly either \"income\" or \"expense\".
\n
category (string, required): The category label for the record (e.g., \"Salary\", \"Equipment\", \"Office Rent\").
\n
date (string, optional): The transaction date in ISO 8601 format. Defaults to the current server time if omitted.
\n
description (string, optional): A brief note providing additional context for the transaction.
\n

Examples

Example Request Body:

{\n  \"amount\": 1250.75,\n  \"type\": \"expense\",\n  \"category\": \"Office Supplies\",\n  \"date\": \"2024-03-20T10:00:00.000Z\",\n  \"description\": \"Monthly stationery and printer ink restock\"\n}\n\n

Example Success Response (201 Created):

{\n  \"status\": \"success\",\n  \"data\": {\n    \"record\": {\n      \"_id\": \"65f9a2b3e4b0a12345678901\",\n      \"amount\": 1250.75,\n      \"type\": \"expense\",\n      \"category\": \"Office Supplies\",\n      \"date\": \"2024-03-20T10:00:00.000Z\",\n      \"description\": \"Monthly stationery and printer ink restock\",\n      \"createdBy\": \"65f9a1a2e4b0a12345678888\",\n      \"deletedAt\": null,\n      \"createdAt\": \"2024-03-20T14:30:15.123Z\",\n      \"updatedAt\": \"2024-03-20T14:30:15.123Z\"\n    }\n  }\n}\n\n

Example Error Response (400 Bad Request):

{\n  \"status\": \"fail\",\n  \"message\": \"Amount must be positive\"\n}\n\n

Example Error Response (403 Forbidden):

{\n  \"status\": \"fail\",\n  \"message\": \"You do not have permission to perform this action\"\n}\n\n

Overview

This endpoint is designed to retrieve data from the specified resource. It utilizes the HTTP GET method, which is commonly used to request data from a server.

Purpose

The primary purpose of this request is to fetch information related to the specified resource. This could include details such as user information, product details, or any other relevant data that the API is designed to provide.

Request Parameters

The request does not require any input parameters as it is a simple GET request. However, if applicable, query parameters can be appended to the URL to filter or modify the data being retrieved.

Example Request

GET /api/resource\n\n

Response Structure

The response will typically be in JSON format and will contain the following fields:

status: Indicates the success or failure of the request.
\n
data: Contains the actual data retrieved from the server.
\n
message: Provides additional information about the request status.
\n

Example Response

{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": 1,\n    \"name\": \"Sample Item\",\n    \"description\": \"This is a sample item description.\",\n    \"price\": 100.00\n  },\n  \"message\": \"Data retrieved successfully.\"\n}\n\n

Conclusion

This endpoint is essential for accessing resource data efficiently. Ensure to handle the response appropriately based on the status field to determine if the request was successful or if there were any issues.

\n","urlObject":{"query":[],"variable":[]},"url":""},"response":[],"_postman_id":"2bc039de-e643-4cd9-8e73-f48f8fcb5eea"},{"name":"Update record","id":"7089bb2d-e390-4d91-b2ca-41728c88bd11","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"description\" : \"Thi is updated description\"\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:5000/api/v1/records/69cfa2e96c616bc6da573539","description":"

Overview

Name: Update Record
\n
Endpoint: PATCH /api/v1/records/:id
\n
Access Control: Private & Restricted. Requires a valid JWT token of a user with the admin role.
\n
Description: This endpoint allows administrators to update the details of a specific financial record. Because it uses the PATCH method, only the fields provided in the payload will be updated; any omitted fields will retain their current values in the database.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Path Parameters:
\n
- id (string, required): The unique MongoDB ObjectId of the record to update.
\n
Body (raw JSON): (All fields are optional)
\n
- amount (number): The financial value of the record. Must be a positive number.
  \n
- type (string): The financial transaction type. Must be either income or expense.
  \n
- category (string): The category of the record (e.g., \"Food\", \"Rent\"). Cannot be empty if provided.
  \n
- date (string): Record transaction date (ISO 8601 Datetime format).
  \n
- description (string): Additional context or notes for the transaction.
  \n
\n

Expected Responses

200 OK (Success)
\n
- Triggered when the record is successfully updated.
  \n
- {\"status\": \"success\",\"data\": { \"record\": { \"_id\": \"60d0fe4f5311236168a109ca\", \"amount\": 150.50, \"type\": \"expense\", \"category\": \"Utilities\", \"description\": \"Updated water bill amount\", \"date\": \"2023-11-04T09:00:00.000Z\", \"updatedAt\": \"2023-11-04T12:00:00.000Z\" }}}
  \n
\n
400 Bad Request (Validation Error)
\n
- Triggered if amount is a negative number, type is invalid, or if the path id is not a valid MongoDB ObjectId.
\n
404 Not Found
\n
- Triggered if the provided id is valid but no financial record with that ID exists in the database.
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who is not an Admin attempts to modify records.
\n

This endpoint allows you to update the description of a specific record identified by its unique ID. By sending a PATCH request to the specified URL, you can modify the existing description of the record.

Request Format

Method: PATCH
\n
URL: http://localhost:5000/api/v1/records/{recordId}
\n
Request Body: The request body must be in JSON format and should include the following key:
\n
- description (string): The new description for the record. This should be a concise string that describes the record's purpose or content.
\n

Example Request Body:

{\n  \"description\": \"This is updated description\"\n}\n\n

Response Structure

Upon a successful update, the server will respond with a JSON object that typically includes the updated record details. The response may contain the following fields:

id (string): The unique identifier of the updated record.
\n
description (string): The updated description of the record.
\n
updated_at (string): A timestamp indicating when the record was last updated.
\n

Example Response:

{\n  \"id\": \"69cfa2e96c616bc6da573539\",\n  \"description\": \"This is updated description\",\n  \"updated_at\": \"2023-10-01T12:00:00Z\"\n}\n\n

Ensure that your request body is properly formatted as JSON to avoid errors during the update process.

\n","urlObject":{"path":["records","69cfa2e96c616bc6da573539"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"7089bb2d-e390-4d91-b2ca-41728c88bd11"},{"name":"Soft delete a record","id":"0b1c1ab3-0bf5-4736-be16-49c634c8724b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"http://localhost:5000/api/v1/records/69cfb122b39085b1c7edac81","description":"

Overview

Name: Delete Record (Soft Delete)
\n
Endpoint: DELETE /api/v1/records/:id
\n
Access Control: Private & Restricted. Requires a valid JWT token of a user with the admin role.
\n
Description: This endpoint is used by administrators to delete a financial transaction record. The platform utilizes a 'soft delete' mechanism, meaning the record is not permanently removed from the database immediately. Instead, it is flagged as deleted (e.g., via a deletedAt timestamp or isDeleted boolean), ensuring it is excluded from dashboards and analysis, but preserving data integrity in case a restore is necessary.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Path Parameters:
\n
- id (string, required): The unique MongoDB ObjectId of the record to be deleted.
\n
Body: None
\n

Responses

200 OK (or 204 No Content) (Success)
\n
- Triggered when the record is successfully soft-deleted.
  \n
- { \"status\": \"success\", \"message\": \"Record successfully deleted\" }
  \n
\n
400 Bad Request (Validation Error)
\n
- Triggered if the path id is not a valid structured MongoDB ObjectId.
\n
404 Not Found
\n
- Triggered if the provided id is valid but no active financial record with that ID exists in the database (or if it has already been deleted).
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who is not an Admin attempts to delete a record.
\n

This endpoint is used to delete a specific record identified by its unique identifier (ID) from the database. The ID must be provided in the URL path.

Request

Method: DELETE
\n
URL: http://localhost:5000/api/v1/records/{id}
\n
Path Parameter:
\n
- id (string): The unique identifier of the record to be deleted. In this example, the ID is 69cfb122b39085b1c7edac81.
\n

Response

Upon successful deletion of the record, the server will respond with a status code indicating the outcome of the request. The response body may contain a confirmation message or status details, but specific structure details are not provided in this documentation.

Expected Behavior

Success: A successful deletion will typically return a 204 No Content status code, indicating that the record has been successfully removed.
\n
Failure: If the record does not exist or if there are issues with the request, appropriate error codes (e.g., 404 Not Found, 400 Bad Request) will be returned.
\n

Ensure to handle these responses appropriately in your application.

\n","urlObject":{"path":["records","69cfb122b39085b1c7edac81"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"0b1c1ab3-0bf5-4736-be16-49c634c8724b"},{"name":"Get records","id":"8d73f51f-86d7-494c-b9a7-a2c8122889cd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://localhost:5000/api/v1/records/?page=1&limit=1&search=update&category=Salary","description":"

Overview

Name: Get All Records
\n
Endpoint: GET /api/v1/records
\n
Access Control: Private. Requires a valid JWT token. Accessible by Admins, Analysts, and Viewers.
\n
Description: This endpoint retrieves the financial transaction records from the database. It supports advanced features such as pagination, searching, and filtering (by type and category) to allow Analysts and Viewers to drill down into specific financial data points. Soft-deleted records are automatically excluded from the results.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Body: None (GET request)
\n
Query Parameters (Optional):
\n
- page (number): The page number for pagination (e.g., 1).
  \n
- limit (number): The amount of records to return per page (e.g., 10).
  \n
- type (string): Filter records by transaction type (enum: income, expense).
  \n
- category (string): Filter records by a specific category (e.g., food, rent).
  \n
- search (string): Search text applied to record descriptions or titles (e.g., rent).
  \n
\n

Expected Responses

200 OK (Success)
\n
- Triggered when the records are successfully retrieved based on the provided query filters.
  \n
- { \"status\": \"success\", \"results\": 2, \"data\": { \"records\": [ { \"_id\": \"60d0fe4f5311236168a109ca\", \"amount\": 5000, \"type\": \"income\", \"category\": \"Salary\", \"description\": \"Monthly Salary\", \"date\": \"2023-11-01T10:00:00.000Z\" }, { \"_id\": \"60d0fe4f5311236168a109cb\", \"amount\": 1500, \"type\": \"expense\", \"category\": \"Rent\", \"description\": \"Office Rent\", \"date\": \"2023-11-02T10:00:00.000Z\" } ] } }
  \n
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n

This endpoint allows users to retrieve a list of records based on specified search criteria. It supports pagination and filtering by category.

Request

Method: GET
\n
URL: http://localhost:5000/api/v1/records/
\n

Query Parameters

page (integer): The page number of the results to retrieve. This is useful for pagination.
\n
limit (integer): The maximum number of records to return per page.
\n
search (string): A search term to filter the records. In this case, it is set to \"update\".
\n
category (string): The category to filter the records. In this case, it is set to \"Salary\".
\n

Response

The response will contain a structured JSON object with the following properties:

totalRecords (integer): The total number of records that match the search criteria.
\n
currentPage (integer): The current page number of the results returned.
\n
records (array): An array of record objects that match the search criteria. Each record object may contain various attributes relevant to the records.
\n

This endpoint is useful for applications that need to display or process records based on user-defined search and filter parameters.

\n","urlObject":{"path":["records",""],"host":["http://localhost:5000/api/v1"],"query":[{"key":"page","value":"1"},{"key":"limit","value":"1"},{"key":"search","value":"update"},{"key":"category","value":"Salary"}],"variable":[]}},"response":[],"_postman_id":"8d73f51f-86d7-494c-b9a7-a2c8122889cd"}],"id":"65a70433-0a2c-4a6b-a963-a686e5fd53f8","_postman_id":"65a70433-0a2c-4a6b-a963-a686e5fd53f8","description":""},{"name":"Analytics","item":[{"name":"Get summary","id":"dd74201c-9f0d-4895-8572-677292019650","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://localhost:5000/api/v1/analytics/summary","description":"

Overview

Name: Get Analytics Summary
\n
Endpoint: GET /api/v1/analytics/summary
\n
Access Control: Private & Restricted. Requires a valid JWT token. Accessible strictly by Admins and Analysts (Viewers are blocked from this endpoint).
\n
Description: This endpoint runs an aggregation to calculate the platform's high-level financial overview. It returns the total calculated income, the total expense, and the resulting net balance. Soft-deleted records are completely ignored in these calculations.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Body: None (GET request)
\n

Responses

200 OK (Success)
\n
- Triggered when the aggregation is successful and the summary is returned.
  \n
- {\"status\": \"success\",\"data\": { \"summary\": { \"totalIncome\": 150000.50, \"totalExpense\": 45000.25, \"netBalance\": 105000.25 }}}
  \n
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who strictly has the viewer role attempts to hit this endpoint, as it is restricted to admin and analyst only.
\n

This endpoint retrieves a summary of analytics data from the Zorvyn platform. It is designed to provide users with a quick overview of key metrics and insights related to their analytics.

Request Parameters

This is a GET request and does not require any input parameters in the query string. However, users may need to include authentication tokens or other headers as specified in the API documentation for authorization.

Response Structure

The response will be in JSON format and will include the following key fields:

totalVisits: Represents the total number of visits recorded.
\n
uniqueVisitors: Indicates the count of unique visitors.
\n
pageViews: The total number of pages viewed during the specified period.
\n
averageSessionDuration: The average duration of user sessions.
\n
bounceRate: The percentage of visitors who leave after viewing only one page.
\n

This summary provides essential metrics that can help users assess the performance of their digital assets and make informed decisions based on user engagement data.

Usage

To effectively use this endpoint, ensure that you have the necessary authentication in place and be prepared to handle the JSON response to extract the relevant analytics data.

\n","urlObject":{"path":["analytics","summary"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"dd74201c-9f0d-4895-8572-677292019650"},{"name":"Get Stats","id":"8315ca87-5ca7-4efa-9fac-b5b324fb4878","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://localhost:5000/api/v1/analytics/stats","description":"

Overview

Name: Get Analytics Stats
\n
Endpoint: GET /api/v1/analytics/stats
\n
Access Control: Private & Restricted. Requires a valid JWT token. Accessible strictly by Admins and Analysts (Viewers are blocked from this endpoint).
\n
Description: This endpoint runs specialized aggregation pipelines over the records to generate visualizable data for dashboards. It returns detailed statistical breakdowns, including category-wise spending/income totals and monthly financial trends. Soft-deleted records are automatically excluded from the aggregations.
\n

Request Details

Headers:
\n
- Content-Type: application/json
  \n
- Authorization: Bearer
  \n
\n
Body: None (GET request)
\n

Responses

200 OK (Success)
\n
- Triggered when the aggregation is successful and the detailed statistics are returned.
  \n
- {\"status\": \"success\",\"data\": { \"stats\": { \"categoryTotals\": [ { \"category\": \"Salary\", \"type\": \"income\", \"total\": 150000 }, { \"category\": \"Rent\", \"type\": \"expense\", \"total\": 15000 }, { \"category\": \"Food\", \"type\": \"expense\", \"total\": 4500 } ], \"monthlyTrends\": [ { \"month\": \"2023-10\", \"income\": 50000, \"expense\": 12000, \"net\": 38000 }, { \"month\": \"2023-11\", \"income\": 50000, \"expense\": 14500, \"net\": 35500 } ] }}}
  \n
\n
401 Unauthorized (Authentication Failed)
\n
- Triggered if the JWT token is missing, expired, or invalid.
\n
403 Forbidden (Role Restriction)
\n
- Triggered if a logged-in user who strictly has the viewer role attempts to hit this endpoint, as it is restricted to admin and analyst only.
\n

This endpoint retrieves analytics statistics for the application. It is designed to provide insights into various metrics that can help in understanding user engagement and application performance.

Request Headers

Authorization: Required. This header should contain the bearer token for authentication. Ensure that you have the necessary permissions to access the analytics data.
\n
Content-Type: Optional. Typically set to application/json, but not required for GET requests.
\n

Request Body

This is a GET request and does not require a request body.

Response Structure

The response will be in JSON format and will include the following fields:

status: A string indicating the success or failure of the request.
\n
data: An object containing the analytics statistics, which may include:
\n
- totalUsers: Integer representing the total number of users.
  \n
- activeUsers: Integer representing the number of active users.
  \n
- sessionDuration: Average session duration in seconds.
  \n
- pageViews: Total number of page views.
  \n
\n

Example Response

{\n  \"status\": \"success\",\n  \"data\": {\n    \"totalUsers\": 1000,\n    \"activeUsers\": 300,\n    \"sessionDuration\": 120,\n    \"pageViews\": 5000\n  }\n}\n\n

Ensure to handle the response appropriately based on the status field to provide feedback or further action in your application.

\n","urlObject":{"path":["analytics","stats"],"host":["http://localhost:5000/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"8315ca87-5ca7-4efa-9fac-b5b324fb4878"}],"id":"3348f036-9637-4d98-85bd-678d6324da23","description":"

Data aggregation and reporting endpoints. Used to calculate net balances, category-wise spending, and visualize monthly financial trends.

\n","_postman_id":"3348f036-9637-4d98-85bd-678d6324da23"},{"name":"meida","item":[{"name":"New Request","id":"e8d2ec8a-c14b-4112-97bf-170e8a07df0a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"urlObject":{"query":[],"variable":[]},"url":""},"response":[],"_postman_id":"e8d2ec8a-c14b-4112-97bf-170e8a07df0a"}],"id":"fcb8e270-49ab-430c-83d7-5b901772ee41","_postman_id":"fcb8e270-49ab-430c-83d7-5b901772ee41","description":""}],"variable":[{"key":"ZORVYN_BASE_URL","value":"http://localhost:5000/api/v1","type":"default"}]}