The paySphere collection provides a complete set of endpoints for managing a cloud-based payroll and employee management system. It enables organizations to authenticate users, manage employee records, and process payroll operations through a unified REST API.
\nBase URL: https://paysphere-p0nt.onrender.com
This collection is organized to support the core workflows of a payroll platform — from onboarding users and managing employee data to finalizing payroll runs and retrieving summary reports. It is intended for developers integrating with the paySphere backend or testing its API behavior.
\nThe collection is divided into three functional areas:
\nHandles user onboarding, session management, and account settings.
\nEndpoints for creating and retrieving employee records.
\nEndpoints for executing and reviewing payroll operations.
\nMost endpoints require a Bearer JWT token in the Authorization header, obtained via the User Login endpoint.
Authorization: Bearer <JWT_TOKEN>\nRegister a new user account in paySphere.
\nMethod: POST
Endpoint: /api/auth/signup
Base URL: https://paysphere-p0nt.onrender.com
This endpoint creates a new user account with the provided details. On success, it returns an authentication token (JWT) that can be used for subsequent authenticated requests, along with the registered company name.
\nNo authentication required. This is a public endpoint used to onboard new users.
\nThe request body must be a JSON object with the following fields:
\n{\n \"fullName\": \"Jane Doe\",\n \"email\": \"jane@example.com\",\n \"companyName\": \"TechCorp Solutions\",\n \"password\": \"securepassword123\"\n}\nReturned when the user is successfully registered.
\n{\n \"token\": \"<JWT token>\",\n \"companyName\": \"TechCorp Solutions\"\n}\ntoken securely on the client side.Authorization: Bearer <token> header for protected endpoints.Authenticate an existing paySphere user and obtain a JSON Web Token (JWT) for accessing protected endpoints.
\nMethod: POST
Endpoint: /api/auth/login
Base URL: https://paysphere-p0nt.onrender.com
This endpoint verifies the user's credentials (email and password) against the paySphere user store. On successful authentication, it returns a signed JWT that must be included in the Authorization header of subsequent requests to access protected resources.
No authentication required. This is a public endpoint used to issue tokens to registered users.
\n{\n \"email\": \"user@example.com\",\n \"password\": \"yourSecurePassword\"\n}\n\nReturns a JWT token that can be used for authenticated requests.
\n{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"companyName\": \"Acme Corp\"\n}\n\nReturned when required fields are missing or malformed.
\nReturned when the credentials are invalid (incorrect email or password).
\nStore the returned token securely on the client (for example, in an HTTP-only cookie or secure storage).
Include the token in subsequent requests using the Authorization: Bearer header.
Tokens may expire — re-authenticate via this endpoint when a 401 response is received from protected endpoints.
\nRetrieves the authenticated user's account settings from the paySphere service.
\nGET https://paysphere-p0nt.onrender.com/api/auth/settings
This endpoint requires a valid JWT bearer token to be sent in the Authorization header.
The token is typically obtained from the User Login endpoint and must not be expired.
\n/api/auth/settingsOn success, the endpoint returns the user's settings associated with the authenticated account.
\n{\n \"success\": true,\n \"settings\": {\n \"userId\": \"69f4e3364ee6e77761a48bf0f\",\n \"notifications\": true,\n \"currency\": \"USD\",\n \"language\": \"en\"\n }\n}\nAllows an authenticated user to update their account and profile settings in paySphere. Use this endpoint to change personal information, notification preferences, and app-level preferences such as language, currency, and theme.
\nThis endpoint requires a valid authentication token. Include a Bearer token in the Authorization header:
Authorization: Bearer <your_access_token>\nRequests without a valid token will be rejected with a 401 Unauthorized response.
Send a JSON payload containing the fields you want to update. All fields are optional — only include the ones you wish to change.
\n\n\nNote: The exact set of updatable fields may vary; the list above is illustrative of typical paySphere settings.
\n
200 OKReturns the updated settings object.
\n{\n \"success\": true,\n \"data\": {\n \"userId\": \"usr_123456\",\n \"displayName\": \"Dev Patel\",\n \"email\": \"dev@example.com\",\n \"phoneNumber\": \"+14155552671\",\n \"notificationPreferences\": {\n \"email\": true,\n \"sms\": false,\n \"push\": true\n },\n \"language\": \"en\",\n \"currency\": \"USD\",\n \"theme\": \"dark\",\n \"updatedAt\": \"2025-01-15T10:30:00Z\"\n }\n}\ncurl --location --request PATCH 'https://api.paysphere.com/v1/settings' \\\n --header 'Authorization: Bearer <your_access_token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"displayName\": \"Dev Patel\",\n \"language\": \"en\",\n \"currency\": \"USD\",\n \"theme\": \"dark\",\n \"notificationPreferences\": {\n \"email\": true,\n \"sms\": false,\n \"push\": true\n }\n }'\n{\n \"success\": true,\n \"message\": \"Settings updated successfully.\"\n}\nEndpoints that handle user onboarding, authentication, and account preferences for the paySphere platform. This folder covers user signup and login flows (issuing JWT tokens for downstream API access), as well as retrieving and updating user-level settings. Use these requests to establish an authenticated session before calling employee or payroll endpoints.
\nIncluded requests:
\nPOST /api/auth/signup — User SignUpPOST /api/auth/login — User LoginGET /api/auth/settings — Get SettingsPUT /api/auth/settings — Update SettingsCreates a new employee record in the paySphere system under the authenticated user's company.
\nPOST https://paysphere-p0nt.onrender.com/api/employees/
This endpoint requires a valid Bearer token (JWT) in the Authorization header.
Authorization: Bearer <your_jwt_token>\nSend a JSON payload with the following fields:
\n{\n \"fullName\": \"Robert Smith\",\n \"role\": \"Software Engineer\",\n \"monthlySalary\": 45000,\n \"overtimeRate\": 650\n}\nThe employee was successfully created. Returns a confirmation message along with the created employee object.
\n{\n \"message\": \"Employee added successfully\",\n \"employee\": {\n \"fullName\": \"Robert Smith\",\n \"role\": \"Software Engineer\",\n \"monthlySalary\": 45000,\n \"overtimeRate\": 650,\n \"companyName\": \"TechCorp Solutions\",\n \"createdBy\": \"69f4e3364ee6e7761a48bf0f\",\n \"_id\": \"69f5bd8fec6bd868cdb19c9d\",\n \"createdAt\": \"2026-05-02T09:02:07.262Z\",\n \"updatedAt\": \"2026-05-02T09:02:07.262Z\",\n \"__v\": 0\n }\n}\ncompanyName and createdBy are automatically populated from the authenticated user's token; they should not be sent in the request body.Retrieves a list of all employees associated with the authenticated user's account in the paySphere system.
\nGET https://paysphere-p0nt.onrender.com/api/employees/
This endpoint requires a Bearer token (JWT) in the Authorization header.
GETReturns a JSON object containing an employees array. Each employee object includes:
{\n \"employees\": [\n {\n \"_id\": \"69f5bd8fec6bd868cdb19c9d\",\n \"fullName\": \"Robert Smith\",\n \"role\": \"Software Engineer\",\n \"monthlySalary\": 45000,\n \"overtimeRate\": 650,\n \"companyName\": \"TechCorp Solutions\",\n \"createdBy\": \"69f4e3364ee6e7761a48bf0f\",\n \"createdAt\": \"2026-05-02T09:02:07.262Z\",\n \"updatedAt\": \"2026-05-02T09:02:07.262Z\",\n \"__v\": 0\n }\n ]\n}\ncreatedBy matches the token subject).Retrieves a list of the most recently added or updated employees associated with the authenticated user's account in the paySphere system. This endpoint is useful for dashboards and activity feeds where the latest employee records need to be surfaced.
\nGET https://paysphere-p0nt.onrender.com/api/employees/recent
\n\nNote: Confirm the exact path with the paySphere API maintainers if the URL has not yet been configured on this request.
\n
This endpoint requires a valid Bearer token (JWT) in the Authorization header.
The JWT is typically obtained from the User Login endpoint and must not be expired.
\nGETGET https://paysphere-p0nt.onrender.com/api/employees/recent?limit=5\nAuthorization: Bearer <JWT_TOKEN>\nReturns a JSON array of recently added/updated employee objects, ordered from most recent to least recent.
\n[\n {\n \"id\": \"emp_123\",\n \"fullName\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\",\n \"role\": \"Engineer\",\n \"department\": \"R&D\",\n \"createdAt\": \"2026-05-01T12:34:56.000Z\",\n \"updatedAt\": \"2026-05-02T08:15:00.000Z\"\n }\n]\nEndpoints for managing the employee directory within paySphere. This folder lets you add new employees to the organization, list all existing employee records, and fetch the most recently added employees. These requests form the foundation for downstream payroll operations, which depend on up-to-date employee data.
\nIncluded requests:
\nPOST /api/employees/ — Add EmployeeGET /api/employees/ — Get EmployeesGET /api/employees/recent/ — Get Recent EmployeesFinalizes the monthly payroll for one or more employees by calculating their net salary based on base salary, leave deductions, overtime pay, bonuses, and other deductions. Each finalized payroll entry is persisted and returned with a unique payroll ID.
\nPOST https://paysphere-p0nt.onrender.com/api/payroll/finalize/
Requires a valid JWT bearer token in the Authorization header.
Authorization: Bearer <token>\nSend a JSON payload with the following structure:
\n{\n \"month\": 5,\n \"year\": 2026,\n \"activities\": [\n {\n \"name\": \"Robert Smith\",\n \"tags\": [\n { \"label\": \"2 days leave\" },\n { \"label\": \"10 hrs overtime\" },\n { \"label\": \"5000 bonus\" },\n { \"label\": \"1500 deduction\" }\n ]\n }\n ]\n}\nReturns a 200 OK with a summary message and a results array containing the computed payroll for each employee.
{\n \"message\": \"Payroll finalized for 1 employee\",\n \"results\": [\n {\n \"employeeName\": \"Robert Smith\",\n \"baseSalary\": 45000,\n \"leaveDays\": 2,\n \"leaveDeduction\": 2400,\n \"overtimeHours\": 10,\n \"overtimePay\": 6500,\n \"bonus\": 5000,\n \"deductions\": 1500,\n \"netSalary\": 52600,\n \"payrollId\": \"69f5c01d39d45a76df5c4b0f\"\n }\n ]\n}\nbaseSalary − leaveDeduction + overtimePay + bonus − deductions.401 Unauthorized — Missing or invalid bearer token.400 Bad Request — Invalid or missing fields in the request body.404 Not Found — An employee referenced in activities does not exist.Retrieves an aggregated summary of payroll information for the authenticated organization/user.
\nGET https://paysphere-p0nt.onrender.com/api/payroll/summary/
This endpoint requires a Bearer token in the Authorization header.
Authorization: Bearer <JWT_TOKEN>\nThe JWT is obtained via the login/authentication flow of the paySphere API.
\nNone.
\nNone.
\nNone — this is a GET request.
Returns a JSON object containing the payroll summary, typically including totals such as gross pay, net pay, deductions, taxes, and employee counts for the current payroll cycle.
\n{\n \"totalEmployees\": 0,\n \"totalGrossPay\": 0,\n \"totalNetPay\": 0,\n \"totalDeductions\": 0,\n \"totalTaxes\": 0,\n \"payPeriod\": \"YYYY-MM\"\n}\nEndpoints that drive the payroll lifecycle in paySphere. This folder includes finalizing payroll for the current cycle and retrieving an aggregated payroll summary for the authenticated organization. All requests here require a valid bearer token and assume employees have already been onboarded via the Employee Management folder.
\nIncluded requests:
\nPOST /api/payroll/finalize/ — Finalize PayrollGET /api/payroll/summary/ — Get Payroll Summary