Workforce Operating System - REST API Reference

Complete REST API documentation for all services in Workforce Operating System

This document provides comprehensive REST API documentation for all services. Use this reference to understand available endpoints, request/response formats, and authentication requirements.

Table of Contents

Introduction

Workforce Operating System

Version : 1.0.355

WorkforceOS is a unified, web-based platform that enables businesses to efficiently manage employees, schedules, attendance, tasks, and workforce operations with full company-level data isolation. Designed for multi-role access, internal departments, AI-driven insights, and integrated communication via email and in-app notifications.

How to Use Project Documents

The Workforceos project has been designed and generated using Mindbricks, a powerful microservice-based backend generation platform. All documentation is automatically produced by the Mindbricks Genesis Engine, based on the high-level architectural patterns defined by the user or inferred by AI.

This documentation set is intended for both AI agents and human developers—including frontend and backend engineers—who need precise and structured information about how to interact with the backend services of this project. Each document reflects the live architecture of the system, providing a reliable reference for API consumption, data models, authentication flows, and business logic.

By following this documentation, developers can seamlessly integrate with the backend, while AI agents can use it to reason about the service structure, make accurate decisions, or even generate compatible client-side code.

Accessing Project Services

Each service generated by Mindbricks is exposed via a dedicated REST API endpoint. Every service documentation set includes the base URL of that service along with the specific API paths for each available route.

Before consuming any API, developers or agents must understand the service URL structure and environment-specific endpoints.

Service Endpoint Structure

Environment URL Pattern Example
Preview https://workforceos.prw.mindbricks.com/auth-api
Staging https://workforceos-stage.mindbricks.co/auth-api
Production https://workforceos.mindbricks.co/auth-api

Replace auth with the actual service name as lower case (e.g., order-api, bff-service, customermanagement-api etc.).

Environment Usage Notes

Frontend applications should be designed to easily switch between environments, allowing dynamic endpoint targeting for Preview, Staging, and Production.

Getting Started: Use the Auth Service First

Before interacting with other services in the Workforceos project, AI agents and developers should begin by integrating with the Auth Service.

Mindbricks automatically generates a dedicated authentication microservice based on the project’s authentication definitions provided by the architect. This service provides the essential user and access management foundation for the project.

Agents should first utilize the Auth Service to:

Auth Service Documentation

Use the following resources to understand and integrate the Auth Service:

Note: For most frontend use cases, the REST API Guide will be the primary source. The Event Guide and Service Design documents are especially useful when integrating with other backend microservices or building systems that interact with the auth service indirectly.

Using the BFF (Backend-for-Frontend) Service

In Mindbricks, all backend services are designed with an advanced CQRS (Command Query Responsibility Segregation) architecture. Within this architecture, business services are responsible for managing their respective domains and ensuring the accuracy and freshness of domain data.

The BFF service complements these business services by providing a read-only aggregation and query layer tailored specifically for frontend and client-side applications.

Key Principles of the BFF Service

BFF Service Documentation

Tip: Use the BFF service as the main entry point for all frontend data queries. It simplifies access, reduces round-trips, and ensures that data is shaped appropriately for the UI layer.

Business Services Overview

The Workforce Operating System project consists of multiple business services, each responsible for managing a specific domain within the system. These services expose their own REST APIs and documentation sets, and are accessible based on the environment (Preview, Staging, Production).

Usage Guidance

Business services are primarily designed to:

For advanced query needs across multiple services or aggregated views, prefer using the BFF service.

Available Business Services

employeeProfile Service

Description: Manages extended employee profile data, employment/tax details, and employee-related documents/certifications for each company. Extends user identities with HR, department, and compliance info. Allows managers and admins to review employee profiles and documents…

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/employeeprofile-api
Staging https://workforceos-stage.mindbricks.co/employeeprofile-api
Production https://workforceos.mindbricks.co/employeeprofile-api

scheduleManagement Service

Description: Microservice managing shift scheduling, shift templates, assignment of users/departments to shifts, and schedule conflict detection for WorkforceOS.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/schedulemanagement-api
Staging https://workforceos-stage.mindbricks.co/schedulemanagement-api
Production https://workforceos.mindbricks.co/schedulemanagement-api

attendanceManagement Service

Description: Handles employee attendance logging (check-in/out), attendance rules (lateness/absence/early-leave), real-time & historical logs, and publishes notification events. Enforces company data isolation, strict record uniqueness, and one-per-shift attendance rule.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/attendancemanagement-api
Staging https://workforceos-stage.mindbricks.co/attendancemanagement-api
Production https://workforceos.mindbricks.co/attendancemanagement-api

taskManagement Service

Description: Handles creation, assignment, update, and tracking of tasks tied to employees, shifts, or departments. Supports admins/managers assigning tasks; employees viewing and completing tasks; accountability tracking. Exposes APIs for creating, updating, deleting, and listing tasks with data enrichment. Data is .company-tenant-scoped…

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/taskmanagement-api
Staging https://workforceos-stage.mindbricks.co/taskmanagement-api
Production https://workforceos.mindbricks.co/taskmanagement-api

leaveManagement Service

Description: Handles employee leave/absence requests, review/approval workflows, and automatic integration with shift assignments, ensuring company data isolation and leave history access for employees and managers/admins.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/leavemanagement-api
Staging https://workforceos-stage.mindbricks.co/leavemanagement-api
Production https://workforceos.mindbricks.co/leavemanagement-api

payrollReporting Service

Description: Handles payroll report records for employees based on calculated hours, overtime, absences from attendance/leave. Provides summary views by user/period/department, allows payment status entry (not processing). Employees can view their own reports. Company tenant scoped and RBAC-enforced.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/payrollreporting-api
Staging https://workforceos-stage.mindbricks.co/payrollreporting-api
Production https://workforceos.mindbricks.co/payrollreporting-api

announcementManagement Service

Description: Handles company-wide and department-specific announcements, supporting scheduled or immediate delivery. Enables admins/managers to create, edit, and manage rich-text announcements, assign audience (all/company/department/users), and triggers events for notification delivery. Employees see relevant announcements in history/detail. Fully tenant-scoped.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/announcementmanagement-api
Staging https://workforceos-stage.mindbricks.co/announcementmanagement-api
Production https://workforceos.mindbricks.co/announcementmanagement-api

aiWorkforceAnalytics Service

Description: Microservice for computing and delivering AI-powered workforce analytics (e.g., shift optimization, absenteeism insights, staffing trends) for eligible (subscribed) companies. Handles insight calculation, storage, and secure distribution to authorized users. Publishes insight alerts/events for notifications. Strictly enforces company data isolation and subscription gating on all features.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/aiworkforceanalytics-api
Staging https://workforceos-stage.mindbricks.co/aiworkforceanalytics-api
Production https://workforceos.mindbricks.co/aiworkforceanalytics-api

subscriptionManagement Service

Description: Manages company AI subscriptions through Stripe payments. Companies must pay via Stripe to activate AI features—no manual subscription creation allowed. Handles the full Stripe payment lifecycle: checkout, payment confirmation, activation, and cancellation. The subscription status is entirely driven by Stripe webhook events. SuperAdmin/saasAdmin bypass payment for platform management.

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/subscriptionmanagement-api
Staging https://workforceos-stage.mindbricks.co/subscriptionmanagement-api
Production https://workforceos.mindbricks.co/subscriptionmanagement-api

agentHub Service

Description: AI Agent Hub

Documentation:

Base URL Examples:

Environment URL
Preview https://workforceos.prw.mindbricks.com/agenthub-api
Staging https://workforceos-stage.mindbricks.co/agenthub-api
Production https://workforceos.mindbricks.co/agenthub-api

Connect via MCP (Model Context Protocol)

All backend services in the Workforceos project expose their Business APIs as MCP tools. These tools are aggregated by the MCP-BFF service into a single unified endpoint that external AI tools can connect to.

Unified MCP Endpoint

Environment StreamableHTTP (recommended) SSE (legacy fallback)
Preview https://workforceos.prw.mindbricks.com/mcpbff-api/mcp https://workforceos.prw.mindbricks.com/mcpbff-api/mcp/sse
Staging https://workforceos-stage.mindbricks.co/mcpbff-api/mcp https://workforceos-stage.mindbricks.co/mcpbff-api/mcp/sse
Production https://workforceos.mindbricks.co/mcpbff-api/mcp https://workforceos.mindbricks.co/mcpbff-api/mcp/sse

Authentication

MCP connections require authentication via the Authorization header:

OAuth is not supported for MCP connections at this time.

Connecting from Cursor

Add the following to your project’s .cursor/mcp.json:

{
  "mcpServers": {
    "workforceos": {
      "url": "https://workforceos.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mbx_your_api_key_here"
      }
    }
  }
}

Connecting from Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "workforceos": {
      "url": "https://workforceos.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mbx_your_api_key_here"
      }
    }
  }
}

What’s Available

Once connected, the AI tool can discover and call all Business API tools from all services — CRUD operations, custom queries, file operations, and more. The MCP-BFF handles routing each tool call to the correct backend service and propagates your authentication context.

Conclusion

This documentation set provides a comprehensive guide for understanding and consuming the Workforce Operating System backend, generated by the Mindbricks platform. It is structured to support both AI agents and human developers in navigating authentication, data access, service responsibilities, and system architecture.

To summarize:

Each service offers a complete set of documentation—REST API guides, event interface definitions, and design insights—to help you integrate efficiently and confidently.

Whether you are building a frontend application, configuring an automation agent, or simply exploring the architecture, this documentation is your primary reference for working with the backend of this project.

For environment-specific access, ensure you’re using the correct base URLs (Preview, Staging, Production), and coordinate with the project owner for any custom deployments.

Service API Documentation

REST API GUIDE

workforceos-auth-service

Version: 1.0.20

Authentication service for the project

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the Auth Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our Auth Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the Auth Service via HTTP requests for purposes such as creating, updating, deleting and querying Auth objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the Auth Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the Auth service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the Auth service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the Auth service.

This service is configured to listen for HTTP requests on port 3011, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the Auth service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The Auth service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the Auth service.

Multi Tenant Architecture

The Auth service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the Auth service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the Auth service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the Auth service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

Auth service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

User resource

Resource Definition : A data object that stores the user information and handles login settings. User Resource Properties

Name Type Required Default Definition
email String * A string value to represent the user's email.*
password String * A string value to represent the user's password. It will be stored as hashed.*
fullname String A string value to represent the fullname of the user
avatar String The avatar url of the user. A random avatar will be generated if not provided
roleId String A string value to represent the roleId of the user.
emailVerified Boolean A boolean value to represent the email verification status of the user.
companyId ID An ID value to represent the tenant id of the company

UserGroup resource

Resource Definition : A data object that stores the user group information. UserGroup Resource Properties

Name Type Required Default Definition
groupName String * A string value to represent the group name.*
avatar String * A string value to represent the groups icon.*
companyId ID An ID value to represent the tenant id of the company

UserGroupMember resource

Resource Definition : A data object that stores the members of the user group. UserGroupMember Resource Properties

Name Type Required Default Definition
groupId ID * An ID value to represent the group that the user is asssigned as a memeber to.*
userId ID * An ID value to represent the user that is assgined as a member to the group.*
ownerId ID An ID value to represent the admin user who assgined the member.
companyId ID An ID value to represent the tenant id of the company

Company resource

Resource Definition : A data object that stores the information for company Company Resource Properties

Name Type Required Default Definition
name String A string value to represent one word name of the company
codename String A string value to represent a unique code name for the company which is generated automatically using name
fullname String A string value to represent the fullname of the company
avatar String A string value represent the url of the company avatar. Keep null for random avatar.
ownerId ID An ID value to represent the user id of company owner who created the tenant
industry String The industry the company operates in (e.g., Technology, Healthcare, Finance, etc.)
companySize String The size of the company (e.g., 1-10, 11-50, 51-200, etc.)

UserAvatarsFile resource

Resource Definition : Auto-generated file storage for the userAvatars database bucket. Files are stored as BYTEA in PostgreSQL. UserAvatarsFile Resource Properties

Name Type Required Default Definition
fileName String Original file name as uploaded by the client.
mimeType String MIME type of the uploaded file (e.g., image/png, application/pdf).
fileSize Integer File size in bytes.
accessKey String 12-character random key for shareable access. Auto-generated on upload.
ownerId ID ID of the user who uploaded the file (from session).
fileData Blob Binary file content. Stored as BYTEA in PostgreSQL or Buffer in MongoDB.
metadata Object Optional JSON metadata for the file (tags, alt text, etc.).
userId ID Reference to the owner user record.
companyId ID An ID value to represent the tenant id of the company

CompanyAvatarsFile resource

Resource Definition : Auto-generated file storage for the companyAvatars database bucket. Files are stored as BYTEA in PostgreSQL. CompanyAvatarsFile Resource Properties

Name Type Required Default Definition
fileName String Original file name as uploaded by the client.
mimeType String MIME type of the uploaded file (e.g., image/png, application/pdf).
fileSize Integer File size in bytes.
accessKey String 12-character random key for shareable access. Auto-generated on upload.
ownerId ID ID of the user who uploaded the file (from session).
fileData Blob Binary file content. Stored as BYTEA in PostgreSQL or Buffer in MongoDB.
metadata Object Optional JSON metadata for the file (tags, alt text, etc.).
companyId ID Reference to the owner company record.

Business Api

Get User API

This api is used by admin roles or the users themselves to get the user profile information.

Rest Route

The getUser API REST controller can be triggered via the following route:

/v1/users/:userId

Rest Request Parameters

The getUser api has got 1 regular request parameter

Parameter Type Required Population
userId ID true request.params?.[“userId”]
userId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/users/:userId

  axios({
    method: 'GET',
    url: `/v1/users/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update User API

This route is used by admins to update user profiles.

Rest Route

The updateUser API REST controller can be triggered via the following route:

/v1/users/:userId

Rest Request Parameters

The updateUser api has got 3 regular request parameters

Parameter Type Required Population
userId ID true request.params?.[“userId”]
fullname String false request.body?.[“fullname”]
avatar String false request.body?.[“avatar”]
userId : This id paremeter is used to select the required data object that will be updated
fullname : A string value to represent the fullname of the user
avatar : The avatar url of the user. A random avatar will be generated if not provided

REST Request To access the api you can use the REST controller with the path PATCH /v1/users/:userId

  axios({
    method: 'PATCH',
    url: `/v1/users/${userId}`,
    data: {
            fullname:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Profile API

This route is used by users to update their own profiles. The target user is always the session user — no userId is needed in the URL.

Rest Route

The updateProfile API REST controller can be triggered via the following route:

/v1/profile

Rest Request Parameters

The updateProfile api has got 2 regular request parameters

Parameter Type Required Population
fullname String false request.body?.[“fullname”]
avatar String false request.body?.[“avatar”]
fullname : A string value to represent the fullname of the user
avatar : The avatar url of the user. A random avatar will be generated if not provided

REST Request To access the api you can use the REST controller with the path PATCH /v1/profile

  axios({
    method: 'PATCH',
    url: '/v1/profile',
    data: {
            fullname:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Create User API

This api is used by admin roles to create a new user manually from admin panels

Rest Route

The createUser API REST controller can be triggered via the following route:

/v1/users

Rest Request Parameters

The createUser api has got 6 regular request parameters

Parameter Type Required Population
avatar String false request.body?.[“avatar”]
roleId String false request.body?.[“roleId”]
emailVerified Boolean false request.body?.[“emailVerified”]
email String true request.body?.[“email”]
password String true request.body?.[“password”]
fullname String true request.body?.[“fullname”]
avatar : The avatar url of the user. If not sent, a default random one will be generated.
roleId : The role to assign to the new user. Defaults to ‘tenantUser’ when omitted.
emailVerified : Pre-verify the user’s email at admin-create time. Defaults to false (the user must run the public verify-email flow to flip this to true).
email : A string value to represent the user’s email.
password : A string value to represent the user’s password. It will be stored as hashed.
fullname : A string value to represent the fullname of the user

REST Request To access the api you can use the REST controller with the path POST /v1/users

  axios({
    method: 'POST',
    url: '/v1/users',
    data: {
            avatar:"String",  
            roleId:"String",  
            emailVerified:"Boolean",  
            email:"String",  
            password:"String",  
            fullname:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete User API

This api is used by admins to delete user profiles.

Rest Route

The deleteUser API REST controller can be triggered via the following route:

/v1/users/:userId

Rest Request Parameters

The deleteUser api has got 1 regular request parameter

Parameter Type Required Population
userId ID true request.params?.[“userId”]
userId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/users/:userId

  axios({
    method: 'DELETE',
    url: `/v1/users/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Archive Profile API

This api is used by users to archive their own profiles. The target user is always the session user — no userId is needed in the URL.

Rest Route

The archiveProfile API REST controller can be triggered via the following route:

/v1/profile

Rest Request Parameters The archiveProfile api has got no request parameters.

REST Request To access the api you can use the REST controller with the path DELETE /v1/profile

  axios({
    method: 'DELETE',
    url: '/v1/profile',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Users API

The list of users is filtered by the tenantId.

Rest Route

The listUsers API REST controller can be triggered via the following route:

/v1/users

Rest Request Parameters

Filter Parameters

The listUsers api supports 3 optional filter parameters for filtering list results:

email (String): A string value to represent the user’s email.

fullname (String): A string value to represent the fullname of the user

roleId (String): A string value to represent the roleId of the user.

REST Request To access the api you can use the REST controller with the path GET /v1/users

  axios({
    method: 'GET',
    url: '/v1/users',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // email: '<value>' // Filter by email
        // fullname: '<value>' // Filter by fullname
        // roleId: '<value>' // Filter by roleId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "users",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"users": [
		{
			"id": "ID",
			"email": "String",
			"password": "String",
			"fullname": "String",
			"avatar": "String",
			"roleId": "String",
			"emailVerified": "Boolean",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Search Users API

The list of users is filtered by the tenantId.

Rest Route

The searchUsers API REST controller can be triggered via the following route:

/v1/searchusers

Rest Request Parameters

The searchUsers api has got 1 regular request parameter

Parameter Type Required Population
keyword String true request.query?.[“keyword”]
keyword :

Filter Parameters

The searchUsers api supports 1 optional filter parameter for filtering list results:

roleId (String): A string value to represent the roleId of the user.

REST Request To access the api you can use the REST controller with the path GET /v1/searchusers

  axios({
    method: 'GET',
    url: '/v1/searchusers',
    data: {
    
    },
    params: {
             keyword:'"String"',  
    
        // Filter parameters (see Filter Parameters section above)
        // roleId: '<value>' // Filter by roleId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "users",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"users": [
		{
			"id": "ID",
			"email": "String",
			"password": "String",
			"fullname": "String",
			"avatar": "String",
			"roleId": "String",
			"emailVerified": "Boolean",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Update Userrole API

This route is used by admin roles to update the user role.The default role is tenantUser when a tenant user is registered. A tenant user’s role can be updated by tenantAdmin / tenantOwner, while saas user’s role is updated by superAdmin or saasAdmin

Rest Route

The updateUserRole API REST controller can be triggered via the following route:

/v1/userrole/:userId

Rest Request Parameters

The updateUserRole api has got 2 regular request parameters

Parameter Type Required Population
userId ID true request.params?.[“userId”]
roleId String true request.body?.[“roleId”]
userId : This id paremeter is used to select the required data object that will be updated
roleId : The new roleId of the user to be updated

REST Request To access the api you can use the REST controller with the path PATCH /v1/userrole/:userId

  axios({
    method: 'PATCH',
    url: `/v1/userrole/${userId}`,
    data: {
            roleId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Userpassword API

This route is used to update the password of users in the profile page by users themselves. The target user is always the session user — no userId is needed in the URL.

Rest Route

The updateUserPassword API REST controller can be triggered via the following route:

/v1/profile/password

Rest Request Parameters

The updateUserPassword api has got 2 regular request parameters

Parameter Type Required Population
oldPassword String true request.body?.[“oldPassword”]
newPassword String true request.body?.[“newPassword”]
oldPassword : The old password of the user that will be overridden bu the new one. Send for double check.
newPassword : The new password of the user to be updated

REST Request To access the api you can use the REST controller with the path PATCH /v1/profile/password

  axios({
    method: 'PATCH',
    url: '/v1/profile/password',
    data: {
            oldPassword:"String",  
            newPassword:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Userpasswordbyadmin API

This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords

Rest Route

The updateUserPasswordByAdmin API REST controller can be triggered via the following route:

/v1/userpasswordbyadmin/:userId

Rest Request Parameters

The updateUserPasswordByAdmin api has got 2 regular request parameters

Parameter Type Required Population
userId ID true request.params?.[“userId”]
password String true request.body?.[“password”]
userId : This id paremeter is used to select the required data object that will be updated
password : The new password of the user to be updated

REST Request To access the api you can use the REST controller with the path PATCH /v1/userpasswordbyadmin/:userId

  axios({
    method: 'PATCH',
    url: `/v1/userpasswordbyadmin/${userId}`,
    data: {
            password:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Briefuser API

This route is used by public to get simple user profile information.

Rest Route

The getBriefUser API REST controller can be triggered via the following route:

/v1/briefuser/:userId

Rest Request Parameters

The getBriefUser api has got 1 regular request parameter

Parameter Type Required Population
userId ID true request.params?.[“userId”]
userId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/briefuser/:userId

  axios({
    method: 'GET',
    url: `/v1/briefuser/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"isActive": true
	}
}

Stream Test API

Test API for iterator action streaming via SSE.

Rest Route

The streamTest API REST controller can be triggered via the following route:

/v1/streamtest/:userId

Rest Request Parameters

The streamTest api has got 1 regular request parameter

Parameter Type Required Population
userId ID true request.params?.[“userId”]
userId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/streamtest/:userId

  axios({
    method: 'GET',
    url: `/v1/streamtest/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Register Companyowner API

This api is used by public users to register themselves as tenant owners to create both a user account and a company account they own.

Rest Route

The registerCompanyOwner API REST controller can be triggered via the following route:

/v1/registercompanyowner

Rest Request Parameters

The registerCompanyOwner api has got 6 regular request parameters

Parameter Type Required Population
avatar String false request.body?.[“avatar”]
socialCode String false request.body?.[“socialCode”]
password String true request.body?.[“password”]
email String true request.body?.[“email”]
company Object true request.body?.[“company”]
fullname String true request.body?.[“fullname”]
avatar : The avatar url of the user. If not sent, a default random one will be generated.
socialCode : Send this social code if it is sent to you after a social login authetication of an unregistred user. The users profile data will be complemented from the autheticated social profile using this code. If you provide the social code there is no need to give full profile data of the user, just give the ones that are not included in social profiles.
password : The password defined by the the user that is being registered.
email : The email defined by the the user that is being registered.
company : The company informatiion for the tenant that the created user will own.
fullname : The full name defined by the the user that is being registered.

REST Request To access the api you can use the REST controller with the path POST /v1/registercompanyowner

  axios({
    method: 'POST',
    url: '/v1/registercompanyowner',
    data: {
            avatar:"String",  
            socialCode:"String",  
            password:"String",  
            email:"String",  
            company:"Object",  
            fullname:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"company": "Object"
}

Register Companyuser API

This route is used by public users to register themselves to tenants that are created by tenant owners.

Rest Route

The registerCompanyUser API REST controller can be triggered via the following route:

/v1/registercompanyuser

Rest Request Parameters

The registerCompanyUser api has got 5 regular request parameters

Parameter Type Required Population
socialCode String false request.body?.[“socialCode”]
password String true request.body?.[“password”]
email String true request.body?.[“email”]
fullname String true request.body?.[“fullname”]
avatar String false request.body?.[“avatar”]
socialCode : Send this social code if it is sent to you after a social login authetication of an unregistred user. The users profile data will be complemented from the autheticated social profile using this code. If you provide the social code there is no need to give full profile data of the user, just give the ones that are not included in social profiles.
password : The password defined by the the user that is being registered.
email : The email defined by the the user that is being registered.
fullname : The full name defined by the the user that is being registered.
avatar : The avatar url of the user. A random avatar will be generated if not provided

REST Request To access the api you can use the REST controller with the path POST /v1/registercompanyuser

  axios({
    method: 'POST',
    url: '/v1/registercompanyuser',
    data: {
            socialCode:"String",  
            password:"String",  
            email:"String",  
            fullname:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Create Company API

This route is used by Saas Admin to create a tenant (Company) manually without public registration. After creating the tenant, a user should be updated to be owner of this tenant.

Rest Route

The createCompany API REST controller can be triggered via the following route:

/v1/companies

Rest Request Parameters

The createCompany api has got 5 regular request parameters

Parameter Type Required Population
avatar String request.body?.[“avatar”]
name String true request.body?.[“name”]
fullname String true request.body?.[“fullname”]
industry String false request.body?.[“industry”]
companySize String false request.body?.[“companySize”]
avatar : A string value represent the url of the Company avatar. Keep null for random avatar.
name : A string value to represent one word name of the company
fullname : A string value to represent the fullname of the company
industry : The industry the company operates in (e.g., Technology, Healthcare, Finance, etc.)
companySize : The size of the company (e.g., 1-10, 11-50, 51-200, etc.)

REST Request To access the api you can use the REST controller with the path POST /v1/companies

  axios({
    method: 'POST',
    url: '/v1/companies',
    data: {
            avatar:"String",  
            name:"String",  
            fullname:"String",  
            industry:"String",  
            companySize:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"id": "ID",
		"name": "String",
		"codename": "String",
		"fullname": "String",
		"avatar": "String",
		"ownerId": "ID",
		"industry": "String",
		"companySize": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Company API

Get a company in current tenant scope. A protected tenant-level route for logged-in users.

Rest Route

The getCompany API REST controller can be triggered via the following route:

/v1/companies

Rest Request Parameters The getCompany api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/companies

  axios({
    method: 'GET',
    url: '/v1/companies',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"id": "ID",
		"name": "String",
		"codename": "String",
		"fullname": "String",
		"avatar": "String",
		"ownerId": "ID",
		"industry": "String",
		"companySize": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Companyhome API

Get public tenant-home information in tenant level.

Rest Route

The getCompanyHome API REST controller can be triggered via the following route:

/v1/companyhome/:codename

Rest Request Parameters

The getCompanyHome api has got 1 regular request parameter

Parameter Type Required Population
codename String true request.params?.[“codename”]
codename : The codename of the company to fetch

REST Request To access the api you can use the REST controller with the path GET /v1/companyhome/:codename

  axios({
    method: 'GET',
    url: `/v1/companyhome/${codename}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"isActive": true
	}
}

Get Companyprofile API

Get tenant profile information in tenant level. A private route for tenantOwner and tenantAdmin.

Rest Route

The getCompanyProfile API REST controller can be triggered via the following route:

/v1/companyprofile

Rest Request Parameters The getCompanyProfile api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/companyprofile

  axios({
    method: 'GET',
    url: '/v1/companyprofile',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"id": "ID",
		"name": "String",
		"codename": "String",
		"fullname": "String",
		"avatar": "String",
		"ownerId": "ID",
		"industry": "String",
		"companySize": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Companyaccount API

Get tenant account information by id. A private SaaS-level route for superAdmin, saasAdmin and saasUser.

Rest Route

The getCompanyAccount API REST controller can be triggered via the following route:

/v1/companyaccounts/:companyId

Rest Request Parameters

The getCompanyAccount api has got 1 regular request parameter

Parameter Type Required Population
companyId ID true request.params?.[“companyId”]
companyId : The id of the company account to fetch

REST Request To access the api you can use the REST controller with the path GET /v1/companyaccounts/:companyId

  axios({
    method: 'GET',
    url: `/v1/companyaccounts/${companyId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"id": "ID",
		"name": "String",
		"codename": "String",
		"fullname": "String",
		"avatar": "String",
		"ownerId": "ID",
		"industry": "String",
		"companySize": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Companiesaccounts API

List tenant accounts in SaaS level for superAdmin, saasAdmin and saasUser.

Rest Route

The listCompaniesAccounts API REST controller can be triggered via the following route:

/v1/companyaccounts

Rest Request Parameters

Filter Parameters

The listCompaniesAccounts api supports 5 optional filter parameters for filtering list results:

name (String): A string value to represent one word name of the company

codename (String): A string value to represent a unique code name for the company which is generated automatically using name

fullname (String): A string value to represent the fullname of the company

avatar (String): A string value represent the url of the company avatar. Keep null for random avatar.

ownerId (ID): An ID value to represent the user id of company owner who created the tenant

REST Request To access the api you can use the REST controller with the path GET /v1/companyaccounts

  axios({
    method: 'GET',
    url: '/v1/companyaccounts',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // name: '<value>' // Filter by name
        // codename: '<value>' // Filter by codename
        // fullname: '<value>' // Filter by fullname
        // avatar: '<value>' // Filter by avatar
        // ownerId: '<value>' // Filter by ownerId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companies",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"companies": [
		{
			"id": "ID",
			"name": "String",
			"codename": "String",
			"fullname": "String",
			"avatar": "String",
			"ownerId": "ID",
			"industry": "String",
			"companySize": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

List Briefcompanies API

Get a list of companies, this route can be called by public, no login required

Rest Route

The listBriefCompanies API REST controller can be triggered via the following route:

/v1/briefcompanies

Rest Request Parameters The listBriefCompanies api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/briefcompanies

  axios({
    method: 'GET',
    url: '/v1/briefcompanies',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companies",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"companies": [
		{
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Briefcompany API

Get brief public information of a company by id. A public SaaS-level route.

Rest Route

The getBriefCompany API REST controller can be triggered via the following route:

/v1/briefcompanies/:codename

Rest Request Parameters

The getBriefCompany api has got 1 regular request parameter

Parameter Type Required Population
codename String true request.params?.[“codename”]
codename : The codename of the company to fetch

REST Request To access the api you can use the REST controller with the path GET /v1/briefcompanies/:codename

  axios({
    method: 'GET',
    url: `/v1/briefcompanies/${codename}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"isActive": true
	}
}

Update Company API

Update a company by id. An admin route which can be called by admins or tenant owners.

Rest Route

The updateCompany API REST controller can be triggered via the following route:

/v1/companies/:companyId

Rest Request Parameters

The updateCompany api has got 6 regular request parameters

Parameter Type Required Population
companyId ID true request.params?.[“companyId”]
name String false request.body?.[“name”]
fullname String false request.body?.[“fullname”]
avatar String false request.body?.[“avatar”]
industry String false request.body?.[“industry”]
companySize String false request.body?.[“companySize”]
companyId : This id paremeter is used to select the required data object that will be updated
name : A string value to represent one word name of the company
fullname : A string value to represent the fullname of the company
avatar : A string value represent the url of the company avatar. Keep null for random avatar.
industry : The industry the company operates in (e.g., Technology, Healthcare, Finance, etc.)
companySize : The size of the company (e.g., 1-10, 11-50, 51-200, etc.)

REST Request To access the api you can use the REST controller with the path PATCH /v1/companies/:companyId

  axios({
    method: 'PATCH',
    url: `/v1/companies/${companyId}`,
    data: {
            name:"String",  
            fullname:"String",  
            avatar:"String",  
            industry:"String",  
            companySize:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"id": "ID",
		"name": "String",
		"codename": "String",
		"fullname": "String",
		"avatar": "String",
		"ownerId": "ID",
		"industry": "String",
		"companySize": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Company API

Delete a company by id. An admin route which can be called by admins or tenant owners.

Rest Route

The deleteCompany API REST controller can be triggered via the following route:

/v1/companies/:companyId

Rest Request Parameters

The deleteCompany api has got 1 regular request parameter

Parameter Type Required Population
companyId ID true request.params?.[“companyId”]
companyId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/companies/:companyId

  axios({
    method: 'DELETE',
    url: `/v1/companies/${companyId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "company",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"company": {
		"id": "ID",
		"name": "String",
		"codename": "String",
		"fullname": "String",
		"avatar": "String",
		"ownerId": "ID",
		"industry": "String",
		"companySize": "String",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Create Usergroup API

This route is used by admin roles to create a new usergroup manually from admin panels

Rest Route

The createUserGroup API REST controller can be triggered via the following route:

/v1/usergroups

Rest Request Parameters

The createUserGroup api has got 2 regular request parameters

Parameter Type Required Population
avatar String false request.body?.[“avatar”]
groupName String true request.body?.[“groupName”]
avatar : A string value to represent the groups icon.
groupName : A string value to represent the group name.

REST Request To access the api you can use the REST controller with the path POST /v1/usergroups

  axios({
    method: 'POST',
    url: '/v1/usergroups',
    data: {
            avatar:"String",  
            groupName:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Usergroup API

This route is used by admin to update user groups.

Rest Route

The updateUserGroup API REST controller can be triggered via the following route:

/v1/usergroups/:userGroupId

Rest Request Parameters

The updateUserGroup api has got 3 regular request parameters

Parameter Type Required Population
userGroupId ID true request.params?.[“userGroupId”]
groupName String false request.body?.[“groupName”]
avatar String false request.body?.[“avatar”]
userGroupId : This id paremeter is used to select the required data object that will be updated
groupName : A string value to represent the group name.
avatar : A string value to represent the groups icon.

REST Request To access the api you can use the REST controller with the path PATCH /v1/usergroups/:userGroupId

  axios({
    method: 'PATCH',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
            groupName:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Usergroup API

This route is used by admin to delete a user group.

Rest Route

The deleteUserGroup API REST controller can be triggered via the following route:

/v1/usergroups/:userGroupId

Rest Request Parameters

The deleteUserGroup api has got 1 regular request parameter

Parameter Type Required Population
userGroupId ID true request.params?.[“userGroupId”]
userGroupId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/usergroups/:userGroupId

  axios({
    method: 'DELETE',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Usergroup API

This is a public route to get the user group information.

Rest Route

The getUserGroup API REST controller can be triggered via the following route:

/v1/usergroups/:userGroupId

Rest Request Parameters

The getUserGroup api has got 1 regular request parameter

Parameter Type Required Population
userGroupId ID true request.params?.[“userGroupId”]
userGroupId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/usergroups/:userGroupId

  axios({
    method: 'GET',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Usergroups API

This is a public route to get the list of groups.

Rest Route

The listUserGroups API REST controller can be triggered via the following route:

/v1/usergroups

Rest Request Parameters

Filter Parameters

The listUserGroups api supports 2 optional filter parameters for filtering list results:

groupName (String): A string value to represent the group name.

avatar (String): A string value to represent the groups icon.

REST Request To access the api you can use the REST controller with the path GET /v1/usergroups

  axios({
    method: 'GET',
    url: '/v1/usergroups',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // groupName: '<value>' // Filter by groupName
        // avatar: '<value>' // Filter by avatar
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroups",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userGroups": [
		{
			"id": "ID",
			"groupName": "String",
			"avatar": "String",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Usergroupmember API

This is a public route to get the user group member information.

Rest Route

The getUserGroupMember API REST controller can be triggered via the following route:

/v1/usergroupmembers/:userGroupMemberId

Rest Request Parameters

The getUserGroupMember api has got 1 regular request parameter

Parameter Type Required Population
userGroupMemberId ID true request.params?.[“userGroupMemberId”]
userGroupMemberId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/usergroupmembers/:userGroupMemberId

  axios({
    method: 'GET',
    url: `/v1/usergroupmembers/${userGroupMemberId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Create Usergroupmember API

This route is used by admin roles to add a user to a group.

Rest Route

The createUserGroupMember API REST controller can be triggered via the following route:

/v1/usergroupmembers

Rest Request Parameters

The createUserGroupMember api has got 2 regular request parameters

Parameter Type Required Population
groupId ID true request.body?.[“groupId”]
userId ID true request.body?.[“userId”]
groupId : An ID value to represent the group that the user is asssigned as a memeber to.
userId : An ID value to represent the user that is assgined as a member to the group.

REST Request To access the api you can use the REST controller with the path POST /v1/usergroupmembers

  axios({
    method: 'POST',
    url: '/v1/usergroupmembers',
    data: {
            groupId:"ID",  
            userId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Usergroupmember API

This route is used by admin to delete a member from a group.

Rest Route

The deleteUserGroupMember API REST controller can be triggered via the following route:

/v1/usergroupmembers/:userGroupMemberId

Rest Request Parameters

The deleteUserGroupMember api has got 1 regular request parameter

Parameter Type Required Population
userGroupMemberId ID true request.params?.[“userGroupMemberId”]
userGroupMemberId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/usergroupmembers/:userGroupMemberId

  axios({
    method: 'DELETE',
    url: `/v1/usergroupmembers/${userGroupMemberId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Usergroupmembers API

This is a public route to get the list of group members of a group.

Rest Route

The listUserGroupMembers API REST controller can be triggered via the following route:

/v1/listusergroupmembers/:groupId

Rest Request Parameters

The listUserGroupMembers api has got 1 regular request parameter

Parameter Type Required Population
groupId ID true request.params?.[“groupId”]
groupId : An ID value to represent the group that the user is asssigned as a memeber to… The parameter is used to query data.

Filter Parameters

The listUserGroupMembers api supports 2 optional filter parameters for filtering list results:

userId (ID): An ID value to represent the user that is assgined as a member to the group.

ownerId (ID): An ID value to represent the admin user who assgined the member.

REST Request To access the api you can use the REST controller with the path GET /v1/listusergroupmembers/:groupId

  axios({
    method: 'GET',
    url: `/v1/listusergroupmembers/${groupId}`,
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // ownerId: '<value>' // Filter by ownerId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMembers",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userGroupMembers": [
		{
			"id": "ID",
			"groupId": "ID",
			"userId": "ID",
			"ownerId": "ID",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": {
				"email": "String",
				"fullname": "String",
				"avatar": "String"
			}
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Useravatarsfile API

[Default get API] — This is the designated default get API for the userAvatarsFile data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getUserAvatarsFile API REST controller can be triggered via the following route:

/v1/useravatarsfiles/:userAvatarsFileId

Rest Request Parameters

The getUserAvatarsFile api has got 1 regular request parameter

Parameter Type Required Population
userAvatarsFileId ID true request.params?.[“userAvatarsFileId”]
userAvatarsFileId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/useravatarsfiles/:userAvatarsFileId

  axios({
    method: 'GET',
    url: `/v1/useravatarsfiles/${userAvatarsFileId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userAvatarsFile",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"userAvatarsFile": {
		"id": "ID",
		"fileName": "String",
		"mimeType": "String",
		"fileSize": "Integer",
		"accessKey": "String",
		"ownerId": "ID",
		"fileData": "Blob",
		"metadata": "Object",
		"userId": "ID",
		"companyId": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

List Useravatarsfiles API

[Default list API] — This is the designated default list API for the userAvatarsFile data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listUserAvatarsFiles API REST controller can be triggered via the following route:

/v1/useravatarsfiles

Rest Request Parameters

Filter Parameters

The listUserAvatarsFiles api supports 3 optional filter parameters for filtering list results:

mimeType (String): MIME type of the uploaded file (e.g., image/png, application/pdf).

ownerId (ID): ID of the user who uploaded the file (from session).

userId (ID): Reference to the owner user record.

REST Request To access the api you can use the REST controller with the path GET /v1/useravatarsfiles

  axios({
    method: 'GET',
    url: '/v1/useravatarsfiles',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // mimeType: '<value>' // Filter by mimeType
        // ownerId: '<value>' // Filter by ownerId
        // userId: '<value>' // Filter by userId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userAvatarsFiles",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userAvatarsFiles": [
		{
			"id": "ID",
			"fileName": "String",
			"mimeType": "String",
			"fileSize": "Integer",
			"accessKey": "String",
			"ownerId": "ID",
			"fileData": "Blob",
			"metadata": "Object",
			"userId": "ID",
			"companyId": "ID",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Delete Useravatarsfile API

[Default delete API] — This is the designated default delete API for the userAvatarsFile data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The deleteUserAvatarsFile API REST controller can be triggered via the following route:

/v1/useravatarsfiles/:userAvatarsFileId

Rest Request Parameters

The deleteUserAvatarsFile api has got 1 regular request parameter

Parameter Type Required Population
userAvatarsFileId ID true request.params?.[“userAvatarsFileId”]
userAvatarsFileId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/useravatarsfiles/:userAvatarsFileId

  axios({
    method: 'DELETE',
    url: `/v1/useravatarsfiles/${userAvatarsFileId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userAvatarsFile",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userAvatarsFile": {
		"id": "ID",
		"fileName": "String",
		"mimeType": "String",
		"fileSize": "Integer",
		"accessKey": "String",
		"ownerId": "ID",
		"fileData": "Blob",
		"metadata": "Object",
		"userId": "ID",
		"companyId": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": false
	}
}

Get Companyavatarsfile API

[Default get API] — This is the designated default get API for the companyAvatarsFile data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getCompanyAvatarsFile API REST controller can be triggered via the following route:

/v1/companyavatarsfiles/:companyAvatarsFileId

Rest Request Parameters

The getCompanyAvatarsFile api has got 1 regular request parameter

Parameter Type Required Population
companyAvatarsFileId ID true request.params?.[“companyAvatarsFileId”]
companyAvatarsFileId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/companyavatarsfiles/:companyAvatarsFileId

  axios({
    method: 'GET',
    url: `/v1/companyavatarsfiles/${companyAvatarsFileId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companyAvatarsFile",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"companyAvatarsFile": {
		"id": "ID",
		"fileName": "String",
		"mimeType": "String",
		"fileSize": "Integer",
		"accessKey": "String",
		"ownerId": "ID",
		"fileData": "Blob",
		"metadata": "Object",
		"companyId": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

List Companyavatarsfiles API

[Default list API] — This is the designated default list API for the companyAvatarsFile data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listCompanyAvatarsFiles API REST controller can be triggered via the following route:

/v1/companyavatarsfiles

Rest Request Parameters

Filter Parameters

The listCompanyAvatarsFiles api supports 3 optional filter parameters for filtering list results:

mimeType (String): MIME type of the uploaded file (e.g., image/png, application/pdf).

ownerId (ID): ID of the user who uploaded the file (from session).

companyId (ID): Reference to the owner company record.

REST Request To access the api you can use the REST controller with the path GET /v1/companyavatarsfiles

  axios({
    method: 'GET',
    url: '/v1/companyavatarsfiles',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // mimeType: '<value>' // Filter by mimeType
        // ownerId: '<value>' // Filter by ownerId
        // companyId: '<value>' // Filter by companyId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companyAvatarsFiles",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"companyAvatarsFiles": [
		{
			"id": "ID",
			"fileName": "String",
			"mimeType": "String",
			"fileSize": "Integer",
			"accessKey": "String",
			"ownerId": "ID",
			"fileData": "Blob",
			"metadata": "Object",
			"companyId": "ID",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Delete Companyavatarsfile API

[Default delete API] — This is the designated default delete API for the companyAvatarsFile data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The deleteCompanyAvatarsFile API REST controller can be triggered via the following route:

/v1/companyavatarsfiles/:companyAvatarsFileId

Rest Request Parameters

The deleteCompanyAvatarsFile api has got 1 regular request parameter

Parameter Type Required Population
companyAvatarsFileId ID true request.params?.[“companyAvatarsFileId”]
companyAvatarsFileId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/companyavatarsfiles/:companyAvatarsFileId

  axios({
    method: 'DELETE',
    url: `/v1/companyavatarsfiles/${companyAvatarsFileId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companyAvatarsFile",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"companyAvatarsFile": {
		"id": "ID",
		"fileName": "String",
		"mimeType": "String",
		"fileSize": "Integer",
		"accessKey": "String",
		"ownerId": "ID",
		"fileData": "Blob",
		"metadata": "Object",
		"companyId": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": false
	}
}

Authentication Specific Routes

Route: login

Route Definition: Handles the login process by verifying user credentials and generating an authenticated session.

Route Type: login

Access Routes:

Parameters

Parameter Type Required Population
username String Yes request.body.username
password String Yes request.body.password

Notes

// Sample POST /login call
axios.post("/login", {
  username: "user@example.com",
  password: "securePassword"
});

Success Response

Returns the authenticated session object with a status code 200 OK.

A secure HTTP-only cookie and an access token header are included in the response.

{
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  ...
}

Error Responses

Route: logout

Route Definition: Logs the user out by terminating the current session and clearing the access token.

Route Type: logout

Access Route: POST /logout

Parameters

This route does not require any parameters in the body or query.

Behavior

// Sample POST /logout call
axios.post("/logout", {}, {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Notes

Error Responses 00200 OK:** Always returned, regardless of whether a session existed. Logout is treated as idempotent.

Route: publickey

Route Definition: Returns the public RSA key used to verify JWT access tokens issued by the auth service.

Route Type: publicKeyFetch

Access Route: GET /publickey

Parameters

Parameter Type Required Population
keyId String No request.query.keyId

Behavior

// Sample GET /publickey call
axios.get("/publickey", {
  params: {
    keyId: "currentKeyIdOptional"
  }
});

Success Response Returns the active public key and its associated keyId.

{
    "keyId": "a1b2c3d4",
    "keyData": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhki...\n-----END PUBLIC KEY-----"
}

Error Responses 404 Not Found: Public key file could not be found on the server.

Token Key Management

Mindbricks uses RSA key pairs to sign and verify JWT access tokens securely.
While the auth service signs each token with a private key, other services within the system — or external clients — need the corresponding public key to verify the authenticity and integrity of received tokens.

The /publickey endpoint allows services and clients to dynamically fetch the currently active public key, ensuring that token verification remains secure even if key rotation is performed.

Note:
The /publickey route is not intended for direct frontend (browser) consumption.
Instead, it is primarily used by trusted backend services, APIs, or middleware systems that need to independently verify access tokens issued by the auth service — without making verification-dependent API calls to the auth service itself.

Accessing the public key is crucial for validating user sessions efficiently and maintaining a decentralized trust model across your platform.

Route: relogin

Route Definition: Performs a silent login by verifying the current access token, refreshing the session, and returning a new access token along with updated user information.

Route Type: sessionRefresh

Access Route: GET /relogin

Parameters

This route does not require any request parameters.

Behavior

// Example call to refresh session
axios.get("/relogin", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns a new session object, refreshed from database data.

{
  "sessionId": "new-session-uuid",
  "userId": "user-uuid",
  "email": "user@example.com",
  "roleId": "admin",
  "accessToken": "new-jwt-token",
  ...
}

Error Responses

{
  "status": "ERR",
  "message": "Cannot relogin"
}

Notes

Tip: This route is ideal when you want to rebuild a user’s session in the frontend without requiring them to manually log in again.

Verification Services — Email Verification

Email verification is a two-step flow that ensures a user’s email address is verified and trusted by the system.

All verification services, including email verification, are located under the /verification-services base path.

When is Email Verification Triggered?

Email Verification Flow

  1. Frontend calls /verification-services/email-verification/start with the user’s email address.
    • Mindbricks checks if the email is already verified.
    • A secret code is generated and stored in the cache linked to the user.
    • The code is sent to the user’s email or returned in the response (only in development environments for easier testing).
  2. User receives the code and enters it into the frontend application.
  3. Frontend calls /verification-services/email-verification/complete with the email and the received secretCode.
    • Mindbricks checks that the code is valid, not expired, and matches.
    • If valid, the user’s emailVerified flag is set to true, and a success response is returned.

API Endpoints

POST /verification-services/email-verification/start

Purpose
Starts the email verification process by generating and sending a secret verification code.

Request Body

Parameter Type Required Description
email String Yes The email address to verify 
{
  "email": "user@example.com"
}

Success Response

Secret code details (in development environment). Confirms that the verification step has been started.

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "secretCode": "123456",
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z"
}

⚠️ In production, the secret code is only sent via email, not exposed in the API response.

Error Responses

POST /verification-services/email-verification/complete

Purpose
Completes the email verification by validating the secret code.

Request Body

Parameter Type Required Description
email String Yes The user email being verified
secretCode String Yes The secret code received via email 
{
  "email": "user@example.com",
  "secretCode": "123456"
}

Success Response

Returns confirmation that the email has been verified.

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "isVerified": true
}

Error Responses

Important Behavioral Notes

Resend Throttling

You can only request a new verification code after a cooldown period (resendTimeWindow, e.g., 60 seconds).

Expiration Handling

Verification codes expire after a configured period (expireTimeWindow, e.g., 1 day).

One Code Per Session

Only one active verification session per user is allowed at a time.

💡 Mindbricks automatically manages spam prevention, session caching, expiration, and event broadcasting (start/complete events) for all verification steps.

Verification Services — Mobile Verification

Mobile verification is a two-step flow that ensures a user’s mobile number is verified and trusted by the system.

All verification services, including mobile verification, are located under the /verification-services base path.

When is Mobile Verification Triggered?

Mobile Verification Flow

  1. Frontend calls /verification-services/mobile-verification/start with the user’s email address (used to locate the user).
    • Mindbricks checks if the mobile number is already verified.
    • A secret code is generated and stored in the cache linked to the user.
    • The code is sent to the user’s mobile via SMS or returned in the response (only in development environments for easier testing).
  2. User receives the code and enters it into the frontend application.
  3. Frontend calls /verification-services/mobile-verification/complete with the email and the received secretCode.
    • Mindbricks checks that the code is valid, not expired, and matches.
    • If valid, the user’s mobileVerified flag is set to true, and a success response is returned.

API Endpoints

POST /verification-services/mobile-verification/start

Purpose:
Starts the mobile verification process by generating and sending a secret verification code.

Request Body

Parameter Type Required Description
email String Yes The email address associated with the mobile number to verify 
{
  "email": "user@example.com"
}

Success Response
Secret code details (in development environment). Confirms that the verification step has been started.

{
  "userId": "user-uuid",
  "mobile": "+15551234567",
  "secretCode": "123456",
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z"
}

⚠️ In production, the secret code is only sent via SMS, not exposed in the API response.

Error Responses

POST /verification-services/mobile-verification/complete

Purpose:
Completes the mobile verification by validating the secret code.

Request Body

Parameter Type Required Description
email String Yes The user’s email being verified
secretCode String Yes The secret code received via SMS 
{
  "email": "user@example.com",
  "secretCode": "123456"
}

Success Response
Returns confirmation that the mobile number has been verified.

{
  "userId": "user-uuid",
  "mobile": "+15551234567",
  "isVerified": true
}

Error Responses
403 Forbidden:

Important Behavioral Notes

Resend Throttling:
You can only request a new verification code after a cooldown period (resendTimeWindow, e.g., 60 seconds).

Expiration Handling:
Verification codes expire after a configured period (expireTimeWindow, e.g., 1 day).

One Code Per Session:
Only one active verification session per user is allowed at a time.

💡 Mindbricks automatically manages spam prevention, session caching, expiration, and event broadcasting (start/complete events) for all verification steps.

Verification Services — Email 2FA Verification

Email 2FA (Two-Factor Authentication) provides an additional layer of security by requiring users to confirm their identity using a secret code sent to their email address. This process is used in login flows or sensitive actions that need extra verification.

All verification services, including 2FA, are located under the /verification-services base path.

When is Email 2FA Triggered?

Email 2FA Flow

  1. Frontend calls /verification-services/email-2factor-verification/start with the user’s id, session id, client info, and reason.
    • Mindbricks identifies the user and checks if a cooldown period applies.
    • A new secret code is generated and stored, linked to the current session ID.
    • The code is sent via email or returned in development environments.
  2. User receives the code and enters it into the frontend application.
  3. Frontend calls /verification-services/email-2factor-verification/complete with the userId, sessionId, and the secretCode.
    • Mindbricks verifies the code, validates the session, and updates the session to remove the 2FA requirement.

API Endpoints

POST /verification-services/email-2factor-verification/start

Purpose:
Starts the email-based 2FA process by generating and sending a verification code.

Request Body

Parameter Type Required Description
userId String Yes The user’s ID
sessionId String Yes The current session ID
client String No Optional client tag or context
reason String No Optional reason for triggering 2FA 
{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "client": "login-page",
  "reason": "Login requires email 2FA"
}

Success Response

{
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "email": "user@example.com",
  "secretCode": "123456",
  "expireTime": 300,
  "date": "2024-04-29T10:00:00.000Z"
}

⚠️ In production, the secretCode is only sent via email, not exposed in the API response.

Error Responses

POST /verification-services/email-2factor-verification/complete

Purpose:
Completes the email 2FA process by validating the secret code and session.

Request Body

Parameter Type Required Description
userId String Yes The user’s ID
sessionId String Yes The session ID the code is tied to
secretCode String Yes The secret code received via email 
{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "secretCode": "123456"
}

Success Response

Returns an updated session with 2FA disabled:

{
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "sessionNeedsEmail2FA": false,
  ...
}

Error Responses

Important Behavioral Notes

Verification Services — Mobile 2FA Verification

Mobile 2FA (Two-Factor Authentication) is a security mechanism that adds an extra layer of authentication using a user’s verified mobile number.

All verification services, including mobile 2FA, are accessible under the /verification-services base path.

When is Mobile 2FA Triggered?

Mobile 2FA Verification Flow

  1. Frontend calls /verification-services/mobile-2factor-verification/start with the user’s id, session id, client info, and reason.
    • Mindbricks finds the user by id.
    • Verifies that the user has a verified mobile number.
    • A secret code is generated and cached against the session.
    • The code is sent to the user’s verified mobile number or returned in the response (only in development environments).
  2. User receives the code and enters it in the frontend app.
  3. Frontend calls /verification-services/mobile-2factor-verification/complete with the userId, sessionId, and secretCode.
    • Mindbricks validates the code for expiration and correctness.
    • If valid, the session flag sessionNeedsMobile2FA is cleared.
    • A refreshed session object is returned.

API Endpoints

POST /verification-services/mobile-2factor-verification/start

Purpose:
Initiates mobile-based 2FA by generating and sending a secret code.

Request Body

Parameter Type Required Description
userId String Yes The user’s ID
sessionId String Yes The current session ID
client String No Optional client tag or context
reason String No Optional reason for triggering 2FA 
{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "client": "login-page",
  "reason": "Login requires mobile 2FA"
}

Success Response
Returns the generated code (only in development), expiration info, and metadata.

{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "mobile": "+15551234567",
  "secretCode": "654321",
  "expireTime": 300,
  "date": "2024-04-29T11:00:00.000Z"
}

⚠️ In production environments, the secret code is not included in the response and is instead delivered via SMS.

Error Responses

POST /verification-services/mobile-2factor-verification/complete

Purpose:
Completes mobile 2FA verification by validating the secret code and updating the session.

Request Body

Parameter Type Required Description
userId String Yes ID of the user
sessionId String Yes ID of the session
secretCode String Yes The 6-digit code received via SMS 
{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "secretCode": "654321"
}

Success Response
Returns the updated session with sessionNeedsMobile2FA: false.

{
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "sessionNeedsMobile2FA": false,
  "accessToken": "jwt-token",
  "expiresIn": 86400
}

Error Responses

Behavioral Notes

💡 Mindbricks handles session integrity, rate limiting, and secure code delivery to ensure a robust mobile 2FA process.

Verification Services — Password Reset by Email

Password Reset by Email enables a user to securely reset their password using a secret code sent to their registered email address.

All verification services, including password reset by email, are located under the /verification-services base path.

When is Password Reset by Email Triggered?

Password Reset Flow

  1. Frontend calls /verification-services/password-reset-by-email/start with the user’s email.
    • Mindbricks checks if the user exists and if the email is registered.
    • A secret code is generated and stored in the cache linked to the user.
    • The code is sent to the user’s email, or returned in the response (in development environments only for testing).
  2. User receives the code and enters it into the frontend along with the new password.
  3. Frontend calls /verification-services/password-reset-by-email/complete with the email, the secretCode, and the new password.
    • Mindbricks checks that the code is valid, not expired, and matches.
    • If valid, the user’s password is reset, their emailVerified flag is set to true, and a success response is returned.

API Endpoints

POST /verification-services/password-reset-by-email/start

Purpose:
Starts the password reset process by generating and sending a secret verification code.

Request Body

Parameter Type Required Description
email String Yes The email address of the user 
{
  "email": "user@example.com"
}

Success Response

Returns secret code details (only in development environment) and confirmation that the verification step has been started.

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "secretCode": "123456", 
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z"
}

⚠️ In production, the secret code is only sent via email and not exposed in the API response.

Error Responses

POST /verification-services/password-reset-by-email/complete

Purpose:
Completes the password reset process by validating the secret code and updating the user’s password.

Request Body

Parameter Type Required Description
email String Yes The email address of the user
secretCode String Yes The code received via email
password String Yes The new password the user wants to set 
{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "newSecurePassword123"
}

Success Response

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "isVerified": true
}

Error Responses

Important Behavioral Notes

Resend Throttling:

A new verification code can only be requested after a cooldown period (configured via resendTimeWindow, e.g., 60 seconds).

Expiration Handling:

Verification codes automatically expire after a predefined period (expireTimeWindow, e.g., 1 day).

Session & Event Handling:

Mindbricks manages:

Verification Services — Password Reset by Mobile

Password reset by mobile provides users with a secure mechanism to reset their password using a verification code sent via SMS to their registered mobile number.

All verification services, including password reset by mobile, are located under the /verification-services base path.

When is Password Reset by Mobile Triggered?

Password Reset by Mobile Flow

  1. Frontend calls /verification-services/password-reset-by-mobile/start with the user’s mobile number or associated identifier.
    • Mindbricks checks if a user with the given mobile exists.
    • A secret code is generated and stored in the cache for that user.
    • The code is sent to the user’s mobile (or returned in development environments for testing).
  2. User receives the code via SMS and enters it into the frontend app.
  3. Frontend calls /verification-services/password-reset-by-mobile/complete with the user’s email, the secretCode, and the new password.
    • Mindbricks validates the secret code and its expiration.
    • If valid, it updates the user’s password and returns a success response.

API Endpoints

POST /verification-services/password-reset-by-mobile/start

Purpose:
Initiates the mobile-based password reset by sending a verification code to the user’s mobile.

Request Body

Parameter Type Required Description
mobile String Yes The mobile number to verify 
{
  "mobile": "+905551234567"
}

Success Response

Returns the verification context (code returned only in development):

{
  "userId": "user-uuid",
  "mobile": "+905551234567",
  "secretCode": "123456", 
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z"
}

⚠️ In production, the secretCode is not included in the response and is only sent via SMS.

Error Responses

POST /verification-services/password-reset-by-mobile/complete

Purpose:
Finalizes the password reset process by validating the received verification code and updating the user’s password.

Request Body

Parameter Type Required Description
email String Yes The email address of the user
secretCode String Yes The code received via SMS
password String Yes The new password to assign 
{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "NewSecurePassword123!"
}

Success Response

{
  "userId": "user-uuid",
  "mobile": "+905551234567",
  "isVerified": true
}

Important Behavioral Notes

💡 Mindbricks handles spam protection, session caching, and event-based logging (for both start and complete operations) as part of the verification service base class.

Verification Method Types

🧾 For byCode Verifications

This verification type requires the user to manually enter a 6-digit code.

Frontend Action:
Display a secure input page where the user can enter the code they received via email or SMS. After collecting the code and any required metadata (such as userId or sessionId), make a POST request to the corresponding /complete endpoint.

🔗 For byLink Verifications

This verification type uses a clickable link embedded in an email (or SMS message).

Frontend Action:
The link points to a GET page in your frontend that parses userId and code from the query string and sends them to the backend via a POST request to the corresponding /complete endpoint. This enables one-click verification without requiring the user to type in a code.

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-employeeprofile-service

Version: 1.0.16

Manages extended employee profile data, employment/tax details, and employee-related documents/certifications for each company. Extends user identities with HR, department, and compliance info. Allows managers and admins to review employee profiles and documents…

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the EmployeeProfile Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our EmployeeProfile Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the EmployeeProfile Service via HTTP requests for purposes such as creating, updating, deleting and querying EmployeeProfile objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the EmployeeProfile Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the EmployeeProfile service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the EmployeeProfile service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the EmployeeProfile service.

This service is configured to listen for HTTP requests on port 3001, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the EmployeeProfile service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The EmployeeProfile service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the EmployeeProfile service.

Multi Tenant Architecture

The EmployeeProfile service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the EmployeeProfile service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the EmployeeProfile service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the EmployeeProfile service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

EmployeeProfile service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

EmployeeProfile resource

Resource Definition : Extended business-centric employee profile with employment, compensation, department, and management fields associated to an auth user. Enables company to track staff employment metadata, department, position, and assigned manager for full HR oversight. EmployeeProfile Resource Properties

Name Type Required Default Definition
userId ID Reference to the auth user for this employee profile.
employmentStartDate Date Employee's official employment start date.
position String Employee's job title or position
contractType Enum Type of employment contract for this employee.
salary Double Employee's salary for reporting (managers/admins only).
departmentId ID Reference to the department (userGroup) this employee belongs to.
managerId ID ID of the assigned manager or supervisor (userId from auth:user).
notes Text Manager/admin internal notes (not visible to employees).
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

contractType Enum Property

Property Definition : Type of employment contract for this employee.Enum Options

Name Value Index
permanent "permanent"" 0
temporary "temporary"" 1
contract "contract"" 2

EmployeeDocument resource

Resource Definition : Document or certification attached to an employee profile. E.g., work permit, certification, or contract files. EmployeeDocument Resource Properties

Name Type Required Default Definition
employeeProfileId ID Reference to the related employeeProfile record.
documentType String Type of document (e.g., ID, contract, certification).
documentUrl String URL to the file storage location or bucket for this document.
validUntil Date Expiration date of document, if applicable. Used for tracking compliance/renewal.
companyId ID An ID value to represent the tenant id of the company

Business Api

Create Employeeprofile API

[Default create API] — This is the designated default create API for the employeeProfile data object. Frontend generators and AI agents should use this API for standard CRUD operations. Creates a new employee profile for a user in the company.

Rest Route

The createEmployeeProfile API REST controller can be triggered via the following route:

/v1/employeeprofiles

Rest Request Parameters

The createEmployeeProfile api has got 8 regular request parameters

Parameter Type Required Population
userId ID true request.body?.[“userId”]
employmentStartDate Date true request.body?.[“employmentStartDate”]
position String true request.body?.[“position”]
contractType Enum true request.body?.[“contractType”]
salary Double false request.body?.[“salary”]
departmentId ID false request.body?.[“departmentId”]
managerId ID false request.body?.[“managerId”]
notes Text false request.body?.[“notes”]
userId : Reference to the auth user for this employee profile.
employmentStartDate : Employee’s official employment start date.
position : Employee’s job title or position
contractType : Type of employment contract for this employee.
salary : Employee’s salary for reporting (managers/admins only).
departmentId : Reference to the department (userGroup) this employee belongs to.
managerId : ID of the assigned manager or supervisor (userId from auth:user).
notes : Manager/admin internal notes (not visible to employees).

REST Request To access the api you can use the REST controller with the path POST /v1/employeeprofiles

  axios({
    method: 'POST',
    url: '/v1/employeeprofiles',
    data: {
            userId:"ID",  
            employmentStartDate:"Date",  
            position:"String",  
            contractType:"Enum",  
            salary:"Double",  
            departmentId:"ID",  
            managerId:"ID",  
            notes:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeProfile",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeProfile": {
		"id": "ID",
		"userId": "ID",
		"employmentStartDate": "Date",
		"position": "String",
		"contractType": "Enum",
		"contractType_idx": "Integer",
		"salary": "Double",
		"departmentId": "ID",
		"managerId": "ID",
		"notes": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Employeeprofile API

[Default update API] — This is the designated default update API for the employeeProfile data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update the employee profile for a given user. Employees can only update their own profile; admins/managers can update any profile in the same company.

Rest Route

The updateEmployeeProfile API REST controller can be triggered via the following route:

/v1/employeeprofiles/:employeeProfileId

Rest Request Parameters

The updateEmployeeProfile api has got 8 regular request parameters

Parameter Type Required Population
employeeProfileId ID true request.params?.[“employeeProfileId”]
employmentStartDate Date false request.body?.[“employmentStartDate”]
position String false request.body?.[“position”]
contractType Enum false request.body?.[“contractType”]
salary Double false request.body?.[“salary”]
departmentId ID false request.body?.[“departmentId”]
managerId ID false request.body?.[“managerId”]
notes Text false request.body?.[“notes”]
employeeProfileId : This id paremeter is used to select the required data object that will be updated
employmentStartDate : Employee’s official employment start date.
position : Employee’s job title or position
contractType : Type of employment contract for this employee.
salary : Employee’s salary for reporting (managers/admins only).
departmentId : Reference to the department (userGroup) this employee belongs to.
managerId : ID of the assigned manager or supervisor (userId from auth:user).
notes : Manager/admin internal notes (not visible to employees).

REST Request To access the api you can use the REST controller with the path PATCH /v1/employeeprofiles/:employeeProfileId

  axios({
    method: 'PATCH',
    url: `/v1/employeeprofiles/${employeeProfileId}`,
    data: {
            employmentStartDate:"Date",  
            position:"String",  
            contractType:"Enum",  
            salary:"Double",  
            departmentId:"ID",  
            managerId:"ID",  
            notes:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeProfile",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeProfile": {
		"id": "ID",
		"userId": "ID",
		"employmentStartDate": "Date",
		"position": "String",
		"contractType": "Enum",
		"contractType_idx": "Integer",
		"salary": "Double",
		"departmentId": "ID",
		"managerId": "ID",
		"notes": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Employeeprofile API

[Default get API] — This is the designated default get API for the employeeProfile data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get detailed employee profile info, with enriched user, department, and manager references. Employees may view their own record; admins/managers can view any profile in company.

Rest Route

The getEmployeeProfile API REST controller can be triggered via the following route:

/v1/employeeprofiles/:employeeProfileId

Rest Request Parameters

The getEmployeeProfile api has got 1 regular request parameter

Parameter Type Required Population
employeeProfileId ID true request.params?.[“employeeProfileId”]
employeeProfileId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/employeeprofiles/:employeeProfileId

  axios({
    method: 'GET',
    url: `/v1/employeeprofiles/${employeeProfileId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeProfile",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeProfile": {
		"id": "ID",
		"userId": "ID",
		"employmentStartDate": "Date",
		"position": "String",
		"contractType": "Enum",
		"contractType_idx": "Integer",
		"salary": "Double",
		"departmentId": "ID",
		"managerId": "ID",
		"notes": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"user": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		},
		"manager": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		}
	}
}

List Employeeprofiles API

[Default list API] — This is the designated default list API for the employeeProfile data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all employee profiles for a company, filterable by department, position, contract type, and manager.

Rest Route

The listEmployeeProfiles API REST controller can be triggered via the following route:

/v1/employeeprofiles

Rest Request Parameters

Filter Parameters

The listEmployeeProfiles api supports 4 optional filter parameters for filtering list results:

userId (ID): Reference to the auth user for this employee profile.

employmentStartDate (Date): Employee’s official employment start date.

departmentId (ID): Reference to the department (userGroup) this employee belongs to.

managerId (ID): ID of the assigned manager or supervisor (userId from auth:user).

REST Request To access the api you can use the REST controller with the path GET /v1/employeeprofiles

  axios({
    method: 'GET',
    url: '/v1/employeeprofiles',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // employmentStartDate: '<value>' // Filter by employmentStartDate
        // departmentId: '<value>' // Filter by departmentId
        // managerId: '<value>' // Filter by managerId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeProfiles",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"employeeProfiles": [
		{
			"id": "ID",
			"userId": "ID",
			"employmentStartDate": "Date",
			"position": "String",
			"contractType": "Enum",
			"contractType_idx": "Integer",
			"salary": "Double",
			"departmentId": "ID",
			"managerId": "ID",
			"notes": "Text",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"department": [
				null,
				null,
				null
			],
			"manager": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Create Employeedocument API

[Default create API] — This is the designated default create API for the employeeDocument data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a new document entry for an employee profile.

Rest Route

The createEmployeeDocument API REST controller can be triggered via the following route:

/v1/employeedocuments

Rest Request Parameters

The createEmployeeDocument api has got 4 regular request parameters

Parameter Type Required Population
employeeProfileId ID true request.body?.[“employeeProfileId”]
documentType String true request.body?.[“documentType”]
documentUrl String true request.body?.[“documentUrl”]
validUntil Date false request.body?.[“validUntil”]
employeeProfileId : Reference to the related employeeProfile record.
documentType : Type of document (e.g., ID, contract, certification).
documentUrl : URL to the file storage location or bucket for this document.
validUntil : Expiration date of document, if applicable. Used for tracking compliance/renewal.

REST Request To access the api you can use the REST controller with the path POST /v1/employeedocuments

  axios({
    method: 'POST',
    url: '/v1/employeedocuments',
    data: {
            employeeProfileId:"ID",  
            documentType:"String",  
            documentUrl:"String",  
            validUntil:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeDocument",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeDocument": {
		"id": "ID",
		"employeeProfileId": "ID",
		"documentType": "String",
		"documentUrl": "String",
		"validUntil": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Employeedocument API

[Default update API] — This is the designated default update API for the employeeDocument data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update a specific employee document (e.g., to update expiration date or replace file reference).

Rest Route

The updateEmployeeDocument API REST controller can be triggered via the following route:

/v1/employeedocuments/:employeeDocumentId

Rest Request Parameters

The updateEmployeeDocument api has got 4 regular request parameters

Parameter Type Required Population
employeeDocumentId ID true request.params?.[“employeeDocumentId”]
documentType String false request.body?.[“documentType”]
documentUrl String false request.body?.[“documentUrl”]
validUntil Date false request.body?.[“validUntil”]
employeeDocumentId : This id paremeter is used to select the required data object that will be updated
documentType : Type of document (e.g., ID, contract, certification).
documentUrl : URL to the file storage location or bucket for this document.
validUntil : Expiration date of document, if applicable. Used for tracking compliance/renewal.

REST Request To access the api you can use the REST controller with the path PATCH /v1/employeedocuments/:employeeDocumentId

  axios({
    method: 'PATCH',
    url: `/v1/employeedocuments/${employeeDocumentId}`,
    data: {
            documentType:"String",  
            documentUrl:"String",  
            validUntil:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeDocument",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeDocument": {
		"id": "ID",
		"employeeProfileId": "ID",
		"documentType": "String",
		"documentUrl": "String",
		"validUntil": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Employeedocument API

[Default get API] — This is the designated default get API for the employeeDocument data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get a specific employee document by ID, with enriched employeeProfile info.

Rest Route

The getEmployeeDocument API REST controller can be triggered via the following route:

/v1/employeedocuments/:employeeDocumentId

Rest Request Parameters

The getEmployeeDocument api has got 1 regular request parameter

Parameter Type Required Population
employeeDocumentId ID true request.params?.[“employeeDocumentId”]
employeeDocumentId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/employeedocuments/:employeeDocumentId

  axios({
    method: 'GET',
    url: `/v1/employeedocuments/${employeeDocumentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeDocument",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeDocument": {
		"id": "ID",
		"employeeProfileId": "ID",
		"documentType": "String",
		"documentUrl": "String",
		"validUntil": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"employeeProfile": {
			"userId": "ID",
			"position": "String",
			"contractType": "Enum",
			"contractType_idx": "Integer"
		}
	}
}

List Employeedocuments API

[Default list API] — This is the designated default list API for the employeeDocument data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all documents for employee profiles (optionally filtered by type, validity, or profile).

Rest Route

The listEmployeeDocuments API REST controller can be triggered via the following route:

/v1/employeedocuments

Rest Request Parameters

Filter Parameters

The listEmployeeDocuments api supports 2 optional filter parameters for filtering list results:

employeeProfileId (ID): Reference to the related employeeProfile record.

validUntil (Date): Expiration date of document, if applicable. Used for tracking compliance/renewal.

REST Request To access the api you can use the REST controller with the path GET /v1/employeedocuments

  axios({
    method: 'GET',
    url: '/v1/employeedocuments',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // employeeProfileId: '<value>' // Filter by employeeProfileId
        // validUntil: '<value>' // Filter by validUntil
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeDocuments",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"employeeDocuments": [
		{
			"id": "ID",
			"employeeProfileId": "ID",
			"documentType": "String",
			"documentUrl": "String",
			"validUntil": "Date",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"employeeProfile": {
				"userId": "ID",
				"position": "String",
				"contractType": "Enum",
				"contractType_idx": "Integer"
			}
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Delete Employeeprofile API

Rest Route

The deleteEmployeeProfile API REST controller can be triggered via the following route:

/v1/employeeprofiles/:employeeProfileId

Rest Request Parameters

The deleteEmployeeProfile api has got 1 regular request parameter

Parameter Type Required Population
employeeProfileId ID true request.params?.[“employeeProfileId”]
employeeProfileId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/employeeprofiles/:employeeProfileId

  axios({
    method: 'DELETE',
    url: `/v1/employeeprofiles/${employeeProfileId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeProfile",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeProfile": {
		"id": "ID",
		"userId": "ID",
		"employmentStartDate": "Date",
		"position": "String",
		"contractType": "Enum",
		"contractType_idx": "Integer",
		"salary": "Double",
		"departmentId": "ID",
		"managerId": "ID",
		"notes": "Text",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Employeedocument API

Rest Route

The deleteEmployeeDocument API REST controller can be triggered via the following route:

/v1/employeedocuments/:employeeDocumentId

Rest Request Parameters

The deleteEmployeeDocument api has got 1 regular request parameter

Parameter Type Required Population
employeeDocumentId ID true request.params?.[“employeeDocumentId”]
employeeDocumentId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/employeedocuments/:employeeDocumentId

  axios({
    method: 'DELETE',
    url: `/v1/employeedocuments/${employeeDocumentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "employeeDocument",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"employeeDocument": {
		"id": "ID",
		"employeeProfileId": "ID",
		"documentType": "String",
		"documentUrl": "String",
		"validUntil": "Date",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-schedulemanagement-service

Version: 1.0.11

Microservice managing shift scheduling, shift templates, assignment of users/departments to shifts, and schedule conflict detection for WorkforceOS.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the ScheduleManagement Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our ScheduleManagement Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the ScheduleManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying ScheduleManagement objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the ScheduleManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the ScheduleManagement service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the ScheduleManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the ScheduleManagement service.

This service is configured to listen for HTTP requests on port 3001, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the ScheduleManagement service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The ScheduleManagement service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the ScheduleManagement service.

Multi Tenant Architecture

The ScheduleManagement service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the ScheduleManagement service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the ScheduleManagement service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the ScheduleManagement service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

ScheduleManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

ShiftTemplate resource

Resource Definition : Template for recurring or standard shift patterns. Owned by company. Used to quickly schedule repeatable work shifts; optionally scoped to a department. ShiftTemplate Resource Properties

Name Type Required Default Definition
name String Display name for the template (e.g., 'Morning Shift').
description Text Description/purpose of the shift template.
startTime String Template start time in HH:mm format.
endTime String Template end time in HH:mm format.
recurrenceRule String RFC 5545 RRULE-formatted string describing recurrence (e.g., weekly, biweekly).
departmentId ID Restricts applicability of template to a department if set.
companyId ID An ID value to represent the tenant id of the company

Shift resource

Resource Definition : A scheduled shift for a company. Defines date, time span, location, and assignment to users/departments. Core entity for workforce operations. Shift Resource Properties

Name Type Required Default Definition
shiftDate Date Date of shift (YYYY-MM-DD).
startTime String Shift start time (HH:mm local time).
endTime String Shift end time (HH:mm local time).
location String Physical or logical location for the shift (if applicable).
departmentId ID Limits or indicates department responsible for this shift.
assignedUserIds ID User IDs assigned to the shift.
assignedDepartmentIds ID Department IDs (userGroups) assigned to the shift; employees in these groups are considered assigned.
status Enum Status of the shift (scheduled, completed, cancelled).
createdBy ID User who created the shift.
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Status of the shift (scheduled, completed, cancelled).Enum Options

Name Value Index
scheduled "scheduled"" 0
completed "completed"" 1
cancelled "cancelled"" 2

Business Api

Create Shifttemplate API

[Default create API] — This is the designated default create API for the shiftTemplate data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a new shift template for the company.

Rest Route

The createShiftTemplate API REST controller can be triggered via the following route:

/v1/shifttemplates

Rest Request Parameters

The createShiftTemplate api has got 6 regular request parameters

Parameter Type Required Population
name String true request.body?.[“name”]
description Text false request.body?.[“description”]
startTime String true request.body?.[“startTime”]
endTime String true request.body?.[“endTime”]
recurrenceRule String true request.body?.[“recurrenceRule”]
departmentId ID false request.body?.[“departmentId”]
name : Display name for the template (e.g., ‘Morning Shift’).
description : Description/purpose of the shift template.
startTime : Template start time in HH:mm format.
endTime : Template end time in HH:mm format.
recurrenceRule : RFC 5545 RRULE-formatted string describing recurrence (e.g., weekly, biweekly).
departmentId : Restricts applicability of template to a department if set.

REST Request To access the api you can use the REST controller with the path POST /v1/shifttemplates

  axios({
    method: 'POST',
    url: '/v1/shifttemplates',
    data: {
            name:"String",  
            description:"Text",  
            startTime:"String",  
            endTime:"String",  
            recurrenceRule:"String",  
            departmentId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shiftTemplate",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"shiftTemplate": {
		"id": "ID",
		"name": "String",
		"description": "Text",
		"startTime": "String",
		"endTime": "String",
		"recurrenceRule": "String",
		"departmentId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Shifttemplate API

[Default update API] — This is the designated default update API for the shiftTemplate data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update an existing shift template.

Rest Route

The updateShiftTemplate API REST controller can be triggered via the following route:

/v1/shifttemplates/:shiftTemplateId

Rest Request Parameters

The updateShiftTemplate api has got 7 regular request parameters

Parameter Type Required Population
shiftTemplateId ID true request.params?.[“shiftTemplateId”]
name String false request.body?.[“name”]
description Text false request.body?.[“description”]
startTime String false request.body?.[“startTime”]
endTime String false request.body?.[“endTime”]
recurrenceRule String false request.body?.[“recurrenceRule”]
departmentId ID false request.body?.[“departmentId”]
shiftTemplateId : This id paremeter is used to select the required data object that will be updated
name : Display name for the template (e.g., ‘Morning Shift’).
description : Description/purpose of the shift template.
startTime : Template start time in HH:mm format.
endTime : Template end time in HH:mm format.
recurrenceRule : RFC 5545 RRULE-formatted string describing recurrence (e.g., weekly, biweekly).
departmentId : Restricts applicability of template to a department if set.

REST Request To access the api you can use the REST controller with the path PATCH /v1/shifttemplates/:shiftTemplateId

  axios({
    method: 'PATCH',
    url: `/v1/shifttemplates/${shiftTemplateId}`,
    data: {
            name:"String",  
            description:"Text",  
            startTime:"String",  
            endTime:"String",  
            recurrenceRule:"String",  
            departmentId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shiftTemplate",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"shiftTemplate": {
		"id": "ID",
		"name": "String",
		"description": "Text",
		"startTime": "String",
		"endTime": "String",
		"recurrenceRule": "String",
		"departmentId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Shifttemplate API

[Default delete API] — This is the designated default delete API for the shiftTemplate data object. Frontend generators and AI agents should use this API for standard CRUD operations. Delete a shift template by id.

Rest Route

The deleteShiftTemplate API REST controller can be triggered via the following route:

/v1/shifttemplates/:shiftTemplateId

Rest Request Parameters

The deleteShiftTemplate api has got 1 regular request parameter

Parameter Type Required Population
shiftTemplateId ID true request.params?.[“shiftTemplateId”]
shiftTemplateId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/shifttemplates/:shiftTemplateId

  axios({
    method: 'DELETE',
    url: `/v1/shifttemplates/${shiftTemplateId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shiftTemplate",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"shiftTemplate": {
		"id": "ID",
		"name": "String",
		"description": "Text",
		"startTime": "String",
		"endTime": "String",
		"recurrenceRule": "String",
		"departmentId": "ID",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Shifttemplate API

[Default get API] — This is the designated default get API for the shiftTemplate data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get detailed info for a shift template.

Rest Route

The getShiftTemplate API REST controller can be triggered via the following route:

/v1/shifttemplates/:shiftTemplateId

Rest Request Parameters

The getShiftTemplate api has got 1 regular request parameter

Parameter Type Required Population
shiftTemplateId ID true request.params?.[“shiftTemplateId”]
shiftTemplateId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/shifttemplates/:shiftTemplateId

  axios({
    method: 'GET',
    url: `/v1/shifttemplates/${shiftTemplateId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shiftTemplate",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"shiftTemplate": {
		"id": "ID",
		"name": "String",
		"description": "Text",
		"startTime": "String",
		"endTime": "String",
		"recurrenceRule": "String",
		"departmentId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Shifttemplates API

[Default list API] — This is the designated default list API for the shiftTemplate data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all shift templates for the company, filterable by department.

Rest Route

The listShiftTemplates API REST controller can be triggered via the following route:

/v1/shifttemplates

Rest Request Parameters

Filter Parameters

The listShiftTemplates api supports 2 optional filter parameters for filtering list results:

name (String): Display name for the template (e.g., ‘Morning Shift’).

departmentId (ID): Restricts applicability of template to a department if set.

REST Request To access the api you can use the REST controller with the path GET /v1/shifttemplates

  axios({
    method: 'GET',
    url: '/v1/shifttemplates',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // name: '<value>' // Filter by name
        // departmentId: '<value>' // Filter by departmentId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shiftTemplates",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"shiftTemplates": [
		{
			"id": "ID",
			"name": "String",
			"description": "Text",
			"startTime": "String",
			"endTime": "String",
			"recurrenceRule": "String",
			"departmentId": "ID",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"department": [
				null,
				null,
				null
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Create Shift API

[Default create API] — This is the designated default create API for the shift data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a shift for a specific date, with assigned users or departments. Enforces conflict detection: blocks if any assigned user has an overlapping shift OR an approved leave request covering the shift date.

Rest Route

The createShift API REST controller can be triggered via the following route:

/v1/shifts

Rest Request Parameters

The createShift api has got 8 regular request parameters

Parameter Type Required Population
shiftDate Date true request.body?.[“shiftDate”]
startTime String true request.body?.[“startTime”]
endTime String true request.body?.[“endTime”]
location String false request.body?.[“location”]
departmentId ID false request.body?.[“departmentId”]
assignedUserIds ID false request.body?.[“assignedUserIds”]
assignedDepartmentIds ID false request.body?.[“assignedDepartmentIds”]
status Enum true request.body?.[“status”]
shiftDate : Date of shift (YYYY-MM-DD).
startTime : Shift start time (HH:mm local time).
endTime : Shift end time (HH:mm local time).
location : Physical or logical location for the shift (if applicable).
departmentId : Limits or indicates department responsible for this shift.
assignedUserIds : User IDs assigned to the shift.
assignedDepartmentIds : Department IDs (userGroups) assigned to the shift; employees in these groups are considered assigned.
status : Status of the shift (scheduled, completed, cancelled).

REST Request To access the api you can use the REST controller with the path POST /v1/shifts

  axios({
    method: 'POST',
    url: '/v1/shifts',
    data: {
            shiftDate:"Date",  
            startTime:"String",  
            endTime:"String",  
            location:"String",  
            departmentId:"ID",  
            assignedUserIds:"ID",  
            assignedDepartmentIds:"ID",  
            status:"Enum",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shift",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"shift": {
		"id": "ID",
		"shiftDate": "Date",
		"startTime": "String",
		"endTime": "String",
		"location": "String",
		"departmentId": "ID",
		"assignedUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"status": "Enum",
		"status_idx": "Integer",
		"createdBy": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Shift API

[Default update API] — This is the designated default update API for the shift data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update details or assignment of an existing shift. Runs conflict detection on new assignments: blocks if any assigned user has an overlapping shift OR an approved leave request covering the shift date.

Rest Route

The updateShift API REST controller can be triggered via the following route:

/v1/shifts/:shiftId

Rest Request Parameters

The updateShift api has got 9 regular request parameters

Parameter Type Required Population
shiftId ID true request.params?.[“shiftId”]
shiftDate Date true request.body?.[“shiftDate”]
startTime String true request.body?.[“startTime”]
endTime String true request.body?.[“endTime”]
location String false request.body?.[“location”]
departmentId ID false request.body?.[“departmentId”]
assignedUserIds ID false request.body?.[“assignedUserIds”]
assignedDepartmentIds ID false request.body?.[“assignedDepartmentIds”]
status Enum false request.body?.[“status”]
shiftId : This id paremeter is used to select the required data object that will be updated
shiftDate : Date of shift (YYYY-MM-DD).
startTime : Shift start time (HH:mm local time).
endTime : Shift end time (HH:mm local time).
location : Physical or logical location for the shift (if applicable).
departmentId : Limits or indicates department responsible for this shift.
assignedUserIds : User IDs assigned to the shift.
assignedDepartmentIds : Department IDs (userGroups) assigned to the shift; employees in these groups are considered assigned.
status : Status of the shift (scheduled, completed, cancelled).

REST Request To access the api you can use the REST controller with the path PATCH /v1/shifts/:shiftId

  axios({
    method: 'PATCH',
    url: `/v1/shifts/${shiftId}`,
    data: {
            shiftDate:"Date",  
            startTime:"String",  
            endTime:"String",  
            location:"String",  
            departmentId:"ID",  
            assignedUserIds:"ID",  
            assignedDepartmentIds:"ID",  
            status:"Enum",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shift",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"shift": {
		"id": "ID",
		"shiftDate": "Date",
		"startTime": "String",
		"endTime": "String",
		"location": "String",
		"departmentId": "ID",
		"assignedUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"status": "Enum",
		"status_idx": "Integer",
		"createdBy": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Shift API

[Default delete API] — This is the designated default delete API for the shift data object. Frontend generators and AI agents should use this API for standard CRUD operations. Delete a shift by id.

Rest Route

The deleteShift API REST controller can be triggered via the following route:

/v1/shifts/:shiftId

Rest Request Parameters

The deleteShift api has got 1 regular request parameter

Parameter Type Required Population
shiftId ID true request.params?.[“shiftId”]
shiftId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/shifts/:shiftId

  axios({
    method: 'DELETE',
    url: `/v1/shifts/${shiftId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shift",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"shift": {
		"id": "ID",
		"shiftDate": "Date",
		"startTime": "String",
		"endTime": "String",
		"location": "String",
		"departmentId": "ID",
		"assignedUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"status": "Enum",
		"status_idx": "Integer",
		"createdBy": "ID",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Shift API

[Default get API] — This is the designated default get API for the shift data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get details for a specific shift (enriched with user and department info for assignments).

Rest Route

The getShift API REST controller can be triggered via the following route:

/v1/shifts/:shiftId

Rest Request Parameters

The getShift api has got 1 regular request parameter

Parameter Type Required Population
shiftId ID true request.params?.[“shiftId”]
shiftId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/shifts/:shiftId

  axios({
    method: 'GET',
    url: `/v1/shifts/${shiftId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shift",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"shift": {
		"id": "ID",
		"shiftDate": "Date",
		"startTime": "String",
		"endTime": "String",
		"location": "String",
		"departmentId": "ID",
		"assignedUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"status": "Enum",
		"status_idx": "Integer",
		"createdBy": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"assignedUsers": {
			"fullname": "String",
			"avatar": "String"
		},
		"createdByUser": {
			"fullname": "String",
			"avatar": "String"
		}
	}
}

List Shifts API

[Default list API] — This is the designated default list API for the shift data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all shifts, filterable by date, assigned user, department, status, etc. Employees can see only shifts assigned to them or their department.

Rest Route

The listShifts API REST controller can be triggered via the following route:

/v1/shifts

Rest Request Parameters

Filter Parameters

The listShifts api supports 7 optional filter parameters for filtering list results:

shiftDate (Date): Date of shift (YYYY-MM-DD).

departmentId (ID): Limits or indicates department responsible for this shift.

assignedUserIds (ID array): User IDs assigned to the shift.

assignedUserIds_op (String): Operator for filtering array property “assignedUserIds”. Use “contains” to check if array contains the value, or “overlap” to check if arrays have common elements.

assignedDepartmentIds (ID array): Department IDs (userGroups) assigned to the shift; employees in these groups are considered assigned.

assignedDepartmentIds_op (String): Operator for filtering array property “assignedDepartmentIds”. Use “contains” to check if array contains the value, or “overlap” to check if arrays have common elements.

status (Enum): Status of the shift (scheduled, completed, cancelled).

REST Request To access the api you can use the REST controller with the path GET /v1/shifts

  axios({
    method: 'GET',
    url: '/v1/shifts',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // shiftDate: '<value>' // Filter by shiftDate
        // departmentId: '<value>' // Filter by departmentId
        // assignedUserIds: '<value>' // Filter by assignedUserIds
        // assignedUserIds_op: '<value>' // Filter by assignedUserIds_op
        // assignedDepartmentIds: '<value>' // Filter by assignedDepartmentIds
        // assignedDepartmentIds_op: '<value>' // Filter by assignedDepartmentIds_op
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "shifts",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"shifts": [
		{
			"id": "ID",
			"shiftDate": "Date",
			"startTime": "String",
			"endTime": "String",
			"location": "String",
			"departmentId": "ID",
			"assignedUserIds": "ID",
			"assignedDepartmentIds": "ID",
			"status": "Enum",
			"status_idx": "Integer",
			"createdBy": "ID",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"assignedUsers": [
				{
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"assignedDepartments": [
				null,
				null,
				null
			],
			"department": [
				null,
				null,
				null
			],
			"createdByUser": [
				{
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-attendancemanagement-service

Version: 1.0.5

Handles employee attendance logging (check-in/out), attendance rules (lateness/absence/early-leave), real-time & historical logs, and publishes notification events. Enforces company data isolation, strict record uniqueness, and one-per-shift attendance rule.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the AttendanceManagement Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our AttendanceManagement Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the AttendanceManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying AttendanceManagement objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the AttendanceManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the AttendanceManagement service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the AttendanceManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the AttendanceManagement service.

This service is configured to listen for HTTP requests on port 3002, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the AttendanceManagement service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The AttendanceManagement service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the AttendanceManagement service.

Multi Tenant Architecture

The AttendanceManagement service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the AttendanceManagement service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the AttendanceManagement service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the AttendanceManagement service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

AttendanceManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

AttendanceRecord resource

Resource Definition : Records a specific user's attendance for a shift (check-in/out), with status (present, absent, late, leftEarly, pending), lateness minutes, absence reason, and manager/admin notes. Enforces strict uniqueness (one record per user per shift per day) and company-level data isolation. AttendanceRecord Resource Properties

Name Type Required Default Definition
userId ID Referenced user (employee)
shiftId ID Related shift
checkInTime Date User check-in timestamp (set on check-in)
checkOutTime Date User check-out timestamp (set on check-out)
status Enum Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)
lateByMinutes Integer How many minutes late (if late)
absenceReason String Reason for absence (manager-provided, e.g., sick, leave)
managerNote Text Manager/admin note (optional for manual absence management)
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)Enum Options

Name Value Index
pending "pending"" 0
present "present"" 1
absent "absent"" 2
late "late"" 3
leftEarly "leftEarly"" 4

Business Api

Check Inattendance API

[Default create API] — This is the designated default create API for the attendanceRecord data object. Frontend generators and AI agents should use this API for standard CRUD operations. Allows a user to check in for an assigned shift. Enforces strict one-record-per-user/shift/day, automatically determines status (present/late). Records check-in timestamp; only permitted if user assigned to shift.

API Frontend Description By The Backend Architect

Rendered as employee’s check-in button for assigned shift. Shows feedback on result (on-time/late/error). Manager/admin may impersonate check-in (override role checks).

Rest Route

The checkInAttendance API REST controller can be triggered via the following route:

/v1/check-in

Rest Request Parameters

The checkInAttendance api has got 8 regular request parameters

Parameter Type Required Population
shiftId ID true request.body?.[“shiftId”]
userId ID true request.body?.[“userId”]
checkInTime Date true request.body?.[“checkInTime”]
checkOutTime Date false request.body?.[“checkOutTime”]
status Enum true request.body?.[“status”]
lateByMinutes Integer false request.body?.[“lateByMinutes”]
absenceReason String false request.body?.[“absenceReason”]
managerNote Text false request.body?.[“managerNote”]
shiftId : ID of the shift for check-in
userId : Referenced user (employee)
checkInTime : User check-in timestamp (set on check-in)
checkOutTime : User check-out timestamp (set on check-out)
status : Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)
lateByMinutes : How many minutes late (if late)
absenceReason : Reason for absence (manager-provided, e.g., sick, leave)
managerNote : Manager/admin note (optional for manual absence management)

REST Request To access the api you can use the REST controller with the path POST /v1/check-in

  axios({
    method: 'POST',
    url: '/v1/check-in',
    data: {
            shiftId:"ID",  
            userId:"ID",  
            checkInTime:"Date",  
            checkOutTime:"Date",  
            status:"Enum",  
            lateByMinutes:"Integer",  
            absenceReason:"String",  
            managerNote:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "attendanceRecord",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"attendanceRecord": {
		"id": "ID",
		"userId": "ID",
		"shiftId": "ID",
		"checkInTime": "Date",
		"checkOutTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"lateByMinutes": "Integer",
		"absenceReason": "String",
		"managerNote": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Check Outattendance API

[Default update API] — This is the designated default update API for the attendanceRecord data object. Frontend generators and AI agents should use this API for standard CRUD operations. Sets check-out timestamp and updates status (if left early), allowed only if check-in exists but no check-out. User may only check out own attendance.

API Frontend Description By The Backend Architect

Rendered as check-out button for active shift; shows result or error why not possible (e.g., already checked out, not checked in, not assigned).

Rest Route

The checkOutAttendance API REST controller can be triggered via the following route:

/v1/check-out

Rest Request Parameters

The checkOutAttendance api has got 6 regular request parameters

Parameter Type Required Population
attendanceRecordId ID true request.body?.[“attendanceRecordId”]
checkOutTime Date false request.body?.[“checkOutTime”]
status Enum true request.body?.[“status”]
lateByMinutes Integer false request.body?.[“lateByMinutes”]
absenceReason String false request.body?.[“absenceReason”]
managerNote Text false request.body?.[“managerNote”]
attendanceRecordId : ID of the attendance record to check out (must be of current user and not already checked out)
checkOutTime : User check-out timestamp (set on check-out)
status : Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)
lateByMinutes : How many minutes late (if late)
absenceReason : Reason for absence (manager-provided, e.g., sick, leave)
managerNote : Manager/admin note (optional for manual absence management)

REST Request To access the api you can use the REST controller with the path POST /v1/check-out

  axios({
    method: 'POST',
    url: '/v1/check-out',
    data: {
            attendanceRecordId:"ID",  
            checkOutTime:"Date",  
            status:"Enum",  
            lateByMinutes:"Integer",  
            absenceReason:"String",  
            managerNote:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "attendanceRecord",
	"method": "POST",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"attendanceRecord": {
		"id": "ID",
		"userId": "ID",
		"shiftId": "ID",
		"checkInTime": "Date",
		"checkOutTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"lateByMinutes": "Integer",
		"absenceReason": "String",
		"managerNote": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Mark Attendanceabsent API

Manager/admin marks an employee as absent for a shift (typically after missed check-in). Can set absenceReason, and adds admin note.

API Frontend Description By The Backend Architect

For managers/admins: select user/shift, set absence reason/note. No employee self-access.

Rest Route

The markAttendanceAbsent API REST controller can be triggered via the following route:

/v1/mark-absent

Rest Request Parameters

The markAttendanceAbsent api has got 7 regular request parameters

Parameter Type Required Population
userId ID true request.body?.[“userId”]
shiftId ID true request.body?.[“shiftId”]
absenceReason String false request.body?.[“absenceReason”]
managerNote Text false request.body?.[“managerNote”]
checkOutTime Date false request.body?.[“checkOutTime”]
status Enum true request.body?.[“status”]
lateByMinutes Integer false request.body?.[“lateByMinutes”]
userId : User to be marked absent
shiftId : Shift for absence
absenceReason : Reason for absence
managerNote : Manager note (internal)
checkOutTime : User check-out timestamp (set on check-out)
status : Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)
lateByMinutes : How many minutes late (if late)

REST Request To access the api you can use the REST controller with the path POST /v1/mark-absent

  axios({
    method: 'POST',
    url: '/v1/mark-absent',
    data: {
            userId:"ID",  
            shiftId:"ID",  
            absenceReason:"String",  
            managerNote:"Text",  
            checkOutTime:"Date",  
            status:"Enum",  
            lateByMinutes:"Integer",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "attendanceRecord",
	"method": "POST",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"attendanceRecord": {
		"id": "ID",
		"userId": "ID",
		"shiftId": "ID",
		"checkInTime": "Date",
		"checkOutTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"lateByMinutes": "Integer",
		"absenceReason": "String",
		"managerNote": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Attendancerecord API

[Default get API] — This is the designated default get API for the attendanceRecord data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get an attendance record by ID; enrichment with user/shift details. Employees can see only their own; admin/manager can view any in company.

API Frontend Description By The Backend Architect

For employees: show own record only; enriched with shift info. For admins/managers: enriched with user/shift and notes fields.

Rest Route

The getAttendanceRecord API REST controller can be triggered via the following route:

/v1/attendance-records/:attendanceRecordId

Rest Request Parameters

The getAttendanceRecord api has got 1 regular request parameter

Parameter Type Required Population
attendanceRecordId ID true request.params?.[“attendanceRecordId”]
attendanceRecordId : Attendance record ID

REST Request To access the api you can use the REST controller with the path GET /v1/attendance-records/:attendanceRecordId

  axios({
    method: 'GET',
    url: `/v1/attendance-records/${attendanceRecordId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "attendanceRecord",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"attendanceRecord": {
		"id": "ID",
		"userId": "ID",
		"shiftId": "ID",
		"checkInTime": "Date",
		"checkOutTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"lateByMinutes": "Integer",
		"absenceReason": "String",
		"managerNote": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"user": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		},
		"shift": {
			"shiftDate": "Date",
			"startTime": "String",
			"endTime": "String",
			"location": "String",
			"departmentId": "ID"
		}
	}
}

List Attendancerecords API

[Default list API] — This is the designated default list API for the attendanceRecord data object. Frontend generators and AI agents should use this API for standard CRUD operations. Lists attendance records, filterable by user, shift, status, date. Employees see only own, admin/manager all for company. Enriches with user & shift info.

API Frontend Description By The Backend Architect

Paged list for quick view of attendance, filter/search by user, shift, status, date. Show basic status; enrich row with user & shift as appropriate. Employee may only see own.

Rest Route

The listAttendanceRecords API REST controller can be triggered via the following route:

/v1/attendance-records

Rest Request Parameters

Filter Parameters

The listAttendanceRecords api supports 3 optional filter parameters for filtering list results:

userId (ID): Referenced user (employee)

shiftId (ID): Related shift

status (Enum): Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)

REST Request To access the api you can use the REST controller with the path GET /v1/attendance-records

  axios({
    method: 'GET',
    url: '/v1/attendance-records',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // shiftId: '<value>' // Filter by shiftId
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "attendanceRecords",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"attendanceRecords": [
		{
			"id": "ID",
			"userId": "ID",
			"shiftId": "ID",
			"checkInTime": "Date",
			"checkOutTime": "Date",
			"status": "Enum",
			"status_idx": "Integer",
			"lateByMinutes": "Integer",
			"absenceReason": "String",
			"managerNote": "Text",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"shift": [
				{
					"shiftDate": "Date",
					"startTime": "String",
					"endTime": "String",
					"location": "String",
					"departmentId": "ID"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-taskmanagement-service

Version: 1.0.82

Handles creation, assignment, update, and tracking of tasks tied to employees, shifts, or departments. Supports admins/managers assigning tasks; employees viewing and completing tasks; accountability tracking. Exposes APIs for creating, updating, deleting, and listing tasks with data enrichment. Data is .company-tenant-scoped…

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the TaskManagement Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our TaskManagement Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the TaskManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying TaskManagement objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the TaskManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the TaskManagement service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the TaskManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the TaskManagement service.

This service is configured to listen for HTTP requests on port 3004, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the TaskManagement service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The TaskManagement service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the TaskManagement service.

Multi Tenant Architecture

The TaskManagement service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the TaskManagement service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the TaskManagement service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the TaskManagement service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

TaskManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

TaskAssignment resource

Resource Definition : Main task assignment created by admins/managers. Defines the task template and target recipients (users/departments). Individual tasks are auto-generated for each employee from this assignment. TaskAssignment Resource Properties

Name Type Required Default Definition
title String Task title visible to all assignees
description Text Detailed task description
dueTime Date Deadline for task completion
status Enum Assignment status: active (distributing to employees) or cancelled (admin cancelled the whole assignment)
assignerId ID User who created this task assignment
assigneeUserIds ID Direct user assignments - these users will receive individual tasks
assignedDepartmentIds ID Department assignments - all users in these departments will receive individual tasks
shiftId ID Optional shift link for the task
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Assignment status: active (distributing to employees) or cancelled (admin cancelled the whole assignment)Enum Options

Name Value Index
active "active"" 0
cancelled "cancelled"" 1
completed "completed"" 2

IndividualTask resource

Resource Definition : Individual task record assigned to a single employee. Created automatically when a taskAssignment is created. Each employee works on their own copy and can mark it complete independently. IndividualTask Resource Properties

Name Type Required Default Definition
taskAssignmentId ID Reference to the parent task assignment
assigneeUserId ID The employee who receives this individual task
title String Task title (copied from parent assignment)
description Text Task description (copied from parent assignment)
status Enum Individual task status: pending, completed, or cancelled
completedTime Date When this employee completed their task
dueTime Date Deadline for completion (copied from parent)
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Individual task status: pending, completed, or cancelledEnum Options

Name Value Index
pending "pending"" 0
completed "completed"" 1
cancelled "cancelled"" 2

Business Api

Create Taskassignment API

Admin/Manager creates a task assignment. System automatically creates individual task records for all assigned users (direct + from departments) with deduplication.

Rest Route

The createTaskAssignment API REST controller can be triggered via the following route:

/v1/taskassignments

Rest Request Parameters

The createTaskAssignment api has got 7 regular request parameters

Parameter Type Required Population
title String true request.body?.[“title”]
description Text false request.body?.[“description”]
dueTime Date false request.body?.[“dueTime”]
status Enum true request.body?.[“status”]
assigneeUserIds ID false request.body?.[“assigneeUserIds”]
assignedDepartmentIds ID false request.body?.[“assignedDepartmentIds”]
shiftId ID false request.body?.[“shiftId”]
title : Task title visible to all assignees
description : Detailed task description
dueTime : Deadline for task completion
status : Assignment status: active (distributing to employees) or cancelled (admin cancelled the whole assignment)
assigneeUserIds : Direct user assignments - these users will receive individual tasks
assignedDepartmentIds : Department assignments - all users in these departments will receive individual tasks
shiftId : Optional shift link for the task

REST Request To access the api you can use the REST controller with the path POST /v1/taskassignments

  axios({
    method: 'POST',
    url: '/v1/taskassignments',
    data: {
            title:"String",  
            description:"Text",  
            dueTime:"Date",  
            status:"Enum",  
            assigneeUserIds:"ID",  
            assignedDepartmentIds:"ID",  
            shiftId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "taskAssignment",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"taskAssignment": {
		"id": "ID",
		"title": "String",
		"description": "Text",
		"dueTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"assignerId": "ID",
		"assigneeUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"shiftId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Myindividualtasks API

Employee lists their own individual tasks. Returns tasks assigned to the current user with optional filtering by status.

Rest Route

The listMyIndividualTasks API REST controller can be triggered via the following route:

/v1/myindividualtasks

Rest Request Parameters

Filter Parameters

The listMyIndividualTasks api supports 4 optional filter parameters for filtering list results:

taskAssignmentId (ID): Reference to the parent task assignment

assigneeUserId (ID): The employee who receives this individual task

status (Enum): Individual task status: pending, completed, or cancelled

dueTime (Date): Deadline for completion (copied from parent)

REST Request To access the api you can use the REST controller with the path GET /v1/myindividualtasks

  axios({
    method: 'GET',
    url: '/v1/myindividualtasks',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // taskAssignmentId: '<value>' // Filter by taskAssignmentId
        // assigneeUserId: '<value>' // Filter by assigneeUserId
        // status: '<value>' // Filter by status
        // dueTime: '<value>' // Filter by dueTime
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "individualTasks",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"individualTasks": [
		{
			"id": "ID",
			"taskAssignmentId": "ID",
			"assigneeUserId": "ID",
			"title": "String",
			"description": "Text",
			"status": "Enum",
			"status_idx": "Integer",
			"completedTime": "Date",
			"dueTime": "Date",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"taskAssignment": {
				"title": "String",
				"description": "Text",
				"dueTime": "Date",
				"status": "Enum",
				"status_idx": "Integer",
				"assignerId": "ID",
				"assigneeUserIds": "ID",
				"assignedDepartmentIds": "ID",
				"shiftId": "ID",
				"isActive": true,
				"createdAt": "Date",
				"updatedAt": "Date"
			}
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Taskassignmentwithprogress API

Admin/Manager views a task assignment with completion progress. Returns the assignment details along with aggregated stats and list of individual tasks with their completion status.

Rest Route

The getTaskAssignmentWithProgress API REST controller can be triggered via the following route:

/v1/taskassignmentwithprogress/:taskAssignmentId

Rest Request Parameters

The getTaskAssignmentWithProgress api has got 1 regular request parameter

Parameter Type Required Population
taskAssignmentId ID true request.params?.[“taskAssignmentId”]
taskAssignmentId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/taskassignmentwithprogress/:taskAssignmentId

  axios({
    method: 'GET',
    url: `/v1/taskassignmentwithprogress/${taskAssignmentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "taskAssignment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"taskAssignment": {
		"id": "ID",
		"title": "String",
		"description": "Text",
		"dueTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"assignerId": "ID",
		"assigneeUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"shiftId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Myindividualtask API

Employee views a single individual task. Only returns the task if it belongs to the current user.

Rest Route

The getMyIndividualTask API REST controller can be triggered via the following route:

/v1/myindividualtask/:individualTaskId

Rest Request Parameters

The getMyIndividualTask api has got 1 regular request parameter

Parameter Type Required Population
individualTaskId ID true request.params?.[“individualTaskId”]
individualTaskId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/myindividualtask/:individualTaskId

  axios({
    method: 'GET',
    url: `/v1/myindividualtask/${individualTaskId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "individualTask",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"individualTask": {
		"id": "ID",
		"taskAssignmentId": "ID",
		"assigneeUserId": "ID",
		"title": "String",
		"description": "Text",
		"status": "Enum",
		"status_idx": "Integer",
		"completedTime": "Date",
		"dueTime": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Taskassignments API

Admin/Manager lists all task assignments in the company. Supports filtering by status, assigner, and due date.

Rest Route

The listTaskAssignments API REST controller can be triggered via the following route:

/v1/taskassignments

Rest Request Parameters

Filter Parameters

The listTaskAssignments api supports 9 optional filter parameters for filtering list results:

title (String): Task title visible to all assignees

dueTime (Date): Deadline for task completion

status (Enum): Assignment status: active (distributing to employees) or cancelled (admin cancelled the whole assignment)

assignerId (ID): User who created this task assignment

assigneeUserIds (ID array): Direct user assignments - these users will receive individual tasks

assigneeUserIds_op (String): Operator for filtering array property “assigneeUserIds”. Use “contains” to check if array contains the value, or “overlap” to check if arrays have common elements.

assignedDepartmentIds (ID array): Department assignments - all users in these departments will receive individual tasks

assignedDepartmentIds_op (String): Operator for filtering array property “assignedDepartmentIds”. Use “contains” to check if array contains the value, or “overlap” to check if arrays have common elements.

shiftId (ID): Optional shift link for the task

REST Request To access the api you can use the REST controller with the path GET /v1/taskassignments

  axios({
    method: 'GET',
    url: '/v1/taskassignments',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // title: '<value>' // Filter by title
        // dueTime: '<value>' // Filter by dueTime
        // status: '<value>' // Filter by status
        // assignerId: '<value>' // Filter by assignerId
        // assigneeUserIds: '<value>' // Filter by assigneeUserIds
        // assigneeUserIds_op: '<value>' // Filter by assigneeUserIds_op
        // assignedDepartmentIds: '<value>' // Filter by assignedDepartmentIds
        // assignedDepartmentIds_op: '<value>' // Filter by assignedDepartmentIds_op
        // shiftId: '<value>' // Filter by shiftId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "taskAssignments",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"taskAssignments": [
		{
			"id": "ID",
			"title": "String",
			"description": "Text",
			"dueTime": "Date",
			"status": "Enum",
			"status_idx": "Integer",
			"assignerId": "ID",
			"assigneeUserIds": "ID",
			"assignedDepartmentIds": "ID",
			"shiftId": "ID",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Delete Taskassignment API

Rest Route

The deleteTaskAssignment API REST controller can be triggered via the following route:

/v1/taskassignments/:taskAssignmentId

Rest Request Parameters

The deleteTaskAssignment api has got 1 regular request parameter

Parameter Type Required Population
taskAssignmentId ID true request.params?.[“taskAssignmentId”]
taskAssignmentId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/taskassignments/:taskAssignmentId

  axios({
    method: 'DELETE',
    url: `/v1/taskassignments/${taskAssignmentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "taskAssignment",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"taskAssignment": {
		"id": "ID",
		"title": "String",
		"description": "Text",
		"dueTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"assignerId": "ID",
		"assigneeUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"shiftId": "ID",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Individualtask API

Rest Route

The updateIndividualTask API REST controller can be triggered via the following route:

/v1/individualtasks/:individualTaskId

Rest Request Parameters

The updateIndividualTask api has got 5 regular request parameters

Parameter Type Required Population
individualTaskId ID true request.params?.[“individualTaskId”]
title String false request.body?.[“title”]
description Text false request.body?.[“description”]
status Enum false request.body?.[“status”]
dueTime Date false request.body?.[“dueTime”]
individualTaskId : This id paremeter is used to select the required data object that will be updated
title : Task title (copied from parent assignment)
description : Task description (copied from parent assignment)
status : Individual task status: pending, completed, or cancelled
dueTime : Deadline for completion (copied from parent)

REST Request To access the api you can use the REST controller with the path PATCH /v1/individualtasks/:individualTaskId

  axios({
    method: 'PATCH',
    url: `/v1/individualtasks/${individualTaskId}`,
    data: {
            title:"String",  
            description:"Text",  
            status:"Enum",  
            dueTime:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "individualTask",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"individualTask": {
		"id": "ID",
		"taskAssignmentId": "ID",
		"assigneeUserId": "ID",
		"title": "String",
		"description": "Text",
		"status": "Enum",
		"status_idx": "Integer",
		"completedTime": "Date",
		"dueTime": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Taskassignment API

Rest Route

The updateTaskAssignment API REST controller can be triggered via the following route:

/v1/taskassignments/:taskAssignmentId

Rest Request Parameters

The updateTaskAssignment api has got 8 regular request parameters

Parameter Type Required Population
taskAssignmentId ID true request.params?.[“taskAssignmentId”]
title String false request.body?.[“title”]
description Text false request.body?.[“description”]
dueTime Date false request.body?.[“dueTime”]
status Enum false request.body?.[“status”]
assigneeUserIds ID false request.body?.[“assigneeUserIds”]
assignedDepartmentIds ID false request.body?.[“assignedDepartmentIds”]
shiftId ID false request.body?.[“shiftId”]
taskAssignmentId : This id paremeter is used to select the required data object that will be updated
title : Task title visible to all assignees
description : Detailed task description
dueTime : Deadline for task completion
status : Assignment status: active (distributing to employees) or cancelled (admin cancelled the whole assignment)
assigneeUserIds : Direct user assignments - these users will receive individual tasks
assignedDepartmentIds : Department assignments - all users in these departments will receive individual tasks
shiftId : Optional shift link for the task

REST Request To access the api you can use the REST controller with the path PATCH /v1/taskassignments/:taskAssignmentId

  axios({
    method: 'PATCH',
    url: `/v1/taskassignments/${taskAssignmentId}`,
    data: {
            title:"String",  
            description:"Text",  
            dueTime:"Date",  
            status:"Enum",  
            assigneeUserIds:"ID",  
            assignedDepartmentIds:"ID",  
            shiftId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "taskAssignment",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"taskAssignment": {
		"id": "ID",
		"title": "String",
		"description": "Text",
		"dueTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"assignerId": "ID",
		"assigneeUserIds": "ID",
		"assignedDepartmentIds": "ID",
		"shiftId": "ID",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Create Individualtask API

Rest Route

The createIndividualTask API REST controller can be triggered via the following route:

/v1/individualtasks

Rest Request Parameters

The createIndividualTask api has got 7 regular request parameters

Parameter Type Required Population
taskAssignmentId ID true request.body?.[“taskAssignmentId”]
assigneeUserId ID true request.body?.[“assigneeUserId”]
title String true request.body?.[“title”]
description Text false request.body?.[“description”]
status Enum true request.body?.[“status”]
completedTime Date false request.body?.[“completedTime”]
dueTime Date false request.body?.[“dueTime”]
taskAssignmentId : Reference to the parent task assignment
assigneeUserId : The employee who receives this individual task
title : Task title (copied from parent assignment)
description : Task description (copied from parent assignment)
status : Individual task status: pending, completed, or cancelled
completedTime : When this employee completed their task
dueTime : Deadline for completion (copied from parent)

REST Request To access the api you can use the REST controller with the path POST /v1/individualtasks

  axios({
    method: 'POST',
    url: '/v1/individualtasks',
    data: {
            taskAssignmentId:"ID",  
            assigneeUserId:"ID",  
            title:"String",  
            description:"Text",  
            status:"Enum",  
            completedTime:"Date",  
            dueTime:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "individualTask",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"individualTask": {
		"id": "ID",
		"taskAssignmentId": "ID",
		"assigneeUserId": "ID",
		"title": "String",
		"description": "Text",
		"status": "Enum",
		"status_idx": "Integer",
		"completedTime": "Date",
		"dueTime": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Individualtask API

Rest Route

The deleteIndividualTask API REST controller can be triggered via the following route:

/v1/individualtasks/:individualTaskId

Rest Request Parameters

The deleteIndividualTask api has got 1 regular request parameter

Parameter Type Required Population
individualTaskId ID true request.params?.[“individualTaskId”]
individualTaskId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/individualtasks/:individualTaskId

  axios({
    method: 'DELETE',
    url: `/v1/individualtasks/${individualTaskId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "individualTask",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"individualTask": {
		"id": "ID",
		"taskAssignmentId": "ID",
		"assigneeUserId": "ID",
		"title": "String",
		"description": "Text",
		"status": "Enum",
		"status_idx": "Integer",
		"completedTime": "Date",
		"dueTime": "Date",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-leavemanagement-service

Version: 1.0.23

Handles employee leave/absence requests, review/approval workflows, and automatic integration with shift assignments, ensuring company data isolation and leave history access for employees and managers/admins.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the LeaveManagement Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our LeaveManagement Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the LeaveManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying LeaveManagement objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the LeaveManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the LeaveManagement service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the LeaveManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the LeaveManagement service.

This service is configured to listen for HTTP requests on port 3002, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the LeaveManagement service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The LeaveManagement service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the LeaveManagement service.

Multi Tenant Architecture

The LeaveManagement service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the LeaveManagement service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the LeaveManagement service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the LeaveManagement service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

LeaveManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

LeaveRequest resource

Resource Definition : Tracks employee leave/absence requests including period, type, status, reason, and approval state. Linked to a user and (optionally) department, with audit fields for request and approval. Company-tenant scoped. LeaveRequest Resource Properties

Name Type Required Default Definition
userId ID ID of employee/user requesting leave (auth:user.id)
departmentId ID Department (userGroup) id, for scoping leave if relevant
requestDate Date Datetime when leave requested
leaveType String Type of leave (e.g. vacation, sick, emergency).
startDate Date First day of leave (inclusive).
endDate Date Last day of leave (inclusive).
reason String Employee-provided reason/message for leave request
status Enum Leave request status (pending, approved, rejected, cancelled).
approverId ID UserId of manager/admin who approved/rejected/cancelled the request
approvedDate Date Date/time leave was approved/rejected/cancelled, if applicable.
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Leave request status (pending, approved, rejected, cancelled).Enum Options

Name Value Index
pending "pending"" 0
approved "approved"" 1
rejected "rejected"" 2
cancelled "cancelled"" 3

Business Api

Create Leaverequest API

[Default create API] — This is the designated default create API for the leaveRequest data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a new leave/absence request as an employee user. Sets status to pending. Only allowed if user is creating for themselves. Start and end date are both inclusive.

API Frontend Description By The Backend Architect

Rest Route

The createLeaveRequest API REST controller can be triggered via the following route:

/v1/leaverequests

Rest Request Parameters

The createLeaveRequest api has got 7 regular request parameters

Parameter Type Required Population
departmentId ID false request.body?.[“departmentId”]
leaveType String true request.body?.[“leaveType”]
startDate Date true request.body?.[“startDate”]
endDate Date true request.body?.[“endDate”]
reason String false request.body?.[“reason”]
approverId ID false request.body?.[“approverId”]
approvedDate Date false request.body?.[“approvedDate”]
departmentId : Department (userGroup) id, for scoping leave if relevant
leaveType : Type of leave (e.g. vacation, sick, emergency).
startDate : First day of leave (inclusive).
endDate : Last day of leave (inclusive).
reason : Employee-provided reason/message for leave request
approverId : UserId of manager/admin who approved/rejected/cancelled the request
approvedDate : Date/time leave was approved/rejected/cancelled, if applicable.

REST Request To access the api you can use the REST controller with the path POST /v1/leaverequests

  axios({
    method: 'POST',
    url: '/v1/leaverequests',
    data: {
            departmentId:"ID",  
            leaveType:"String",  
            startDate:"Date",  
            endDate:"Date",  
            reason:"String",  
            approverId:"ID",  
            approvedDate:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequest",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"leaveRequest": {
		"id": "ID",
		"userId": "ID",
		"departmentId": "ID",
		"requestDate": "Date",
		"leaveType": "String",
		"startDate": "Date",
		"endDate": "Date",
		"reason": "String",
		"status": "Enum",
		"status_idx": "Integer",
		"approverId": "ID",
		"approvedDate": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Leaverequest API

[Default update API] — This is the designated default update API for the leaveRequest data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update an existing leave request. Employee can only edit their own request if status is pending. Manager/admin may change status (approve/reject/cancel), set approver/approval date. On approval, will trigger automatic removal from overlapping shifts via scheduleManagement service.

API Frontend Description By The Backend Architect

Rest Route

The updateLeaveRequest API REST controller can be triggered via the following route:

/v1/leaverequests/:leaveRequestId

Rest Request Parameters

The updateLeaveRequest api has got 8 regular request parameters

Parameter Type Required Population
leaveRequestId ID true request.params?.[“leaveRequestId”]
departmentId ID false request.body?.[“departmentId”]
leaveType String false request.body?.[“leaveType”]
startDate Date false request.body?.[“startDate”]
endDate Date false request.body?.[“endDate”]
reason String false request.body?.[“reason”]
approverId ID false request.body?.[“approverId”]
approvedDate Date false request.body?.[“approvedDate”]
leaveRequestId : This id paremeter is used to select the required data object that will be updated
departmentId : Department (userGroup) id, for scoping leave if relevant
leaveType : Type of leave (e.g. vacation, sick, emergency).
startDate : First day of leave (inclusive).
endDate : Last day of leave (inclusive).
reason : Employee-provided reason/message for leave request
approverId : UserId of manager/admin who approved/rejected/cancelled the request
approvedDate : Date/time leave was approved/rejected/cancelled, if applicable.

REST Request To access the api you can use the REST controller with the path PATCH /v1/leaverequests/:leaveRequestId

  axios({
    method: 'PATCH',
    url: `/v1/leaverequests/${leaveRequestId}`,
    data: {
            departmentId:"ID",  
            leaveType:"String",  
            startDate:"Date",  
            endDate:"Date",  
            reason:"String",  
            approverId:"ID",  
            approvedDate:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequest",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"leaveRequest": {
		"id": "ID",
		"userId": "ID",
		"departmentId": "ID",
		"requestDate": "Date",
		"leaveType": "String",
		"startDate": "Date",
		"endDate": "Date",
		"reason": "String",
		"status": "Enum",
		"status_idx": "Integer",
		"approverId": "ID",
		"approvedDate": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Leaverequest API

[Default delete API] — This is the designated default delete API for the leaveRequest data object. Frontend generators and AI agents should use this API for standard CRUD operations. Delete (soft) a leave request. Only the owner (employee) can delete a pending request; manager/admin may delete any cancelable request. Deletion is soft for audit/history.

API Frontend Description By The Backend Architect

Rest Route

The deleteLeaveRequest API REST controller can be triggered via the following route:

/v1/leaverequests/:leaveRequestId

Rest Request Parameters

The deleteLeaveRequest api has got 1 regular request parameter

Parameter Type Required Population
leaveRequestId ID true request.params?.[“leaveRequestId”]
leaveRequestId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/leaverequests/:leaveRequestId

  axios({
    method: 'DELETE',
    url: `/v1/leaverequests/${leaveRequestId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequest",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"leaveRequest": {
		"id": "ID",
		"userId": "ID",
		"departmentId": "ID",
		"requestDate": "Date",
		"leaveType": "String",
		"startDate": "Date",
		"endDate": "Date",
		"reason": "String",
		"status": "Enum",
		"status_idx": "Integer",
		"approverId": "ID",
		"approvedDate": "Date",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Leaverequest API

[Default get API] — This is the designated default get API for the leaveRequest data object. Frontend generators and AI agents should use this API for standard CRUD operations. Retrieve the details of a single leave request record. Enriches with user and department data in response. Owner (employee) can always view own request; admin/manager can view all requests in their company.

API Frontend Description By The Backend Architect

Rest Route

The getLeaveRequest API REST controller can be triggered via the following route:

/v1/leaverequests/:leaveRequestId

Rest Request Parameters

The getLeaveRequest api has got 1 regular request parameter

Parameter Type Required Population
leaveRequestId ID true request.params?.[“leaveRequestId”]
leaveRequestId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/leaverequests/:leaveRequestId

  axios({
    method: 'GET',
    url: `/v1/leaverequests/${leaveRequestId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequest",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"leaveRequest": {
		"id": "ID",
		"userId": "ID",
		"departmentId": "ID",
		"requestDate": "Date",
		"leaveType": "String",
		"startDate": "Date",
		"endDate": "Date",
		"reason": "String",
		"status": "Enum",
		"status_idx": "Integer",
		"approverId": "ID",
		"approvedDate": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"user": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		},
		"approver": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		}
	}
}

List Leaverequests API

[Default list API] — This is the designated default list API for the leaveRequest data object. Frontend generators and AI agents should use this API for standard CRUD operations. List leave requests visible to the user. Employees see their own; managers/admins can filter by department, user, status, and date. Response includes enrichment joins for user, department, and approver.

API Frontend Description By The Backend Architect

Rest Route

The listLeaveRequests API REST controller can be triggered via the following route:

/v1/leaverequests

Rest Request Parameters

Filter Parameters

The listLeaveRequests api supports 6 optional filter parameters for filtering list results:

userId (ID): ID of employee/user requesting leave (auth:user.id)

departmentId (ID): Department (userGroup) id, for scoping leave if relevant

leaveType (String): Type of leave (e.g. vacation, sick, emergency).

startDate (Date): First day of leave (inclusive).

endDate (Date): Last day of leave (inclusive).

status (Enum): Leave request status (pending, approved, rejected, cancelled).

REST Request To access the api you can use the REST controller with the path GET /v1/leaverequests

  axios({
    method: 'GET',
    url: '/v1/leaverequests',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // departmentId: '<value>' // Filter by departmentId
        // leaveType: '<value>' // Filter by leaveType
        // startDate: '<value>' // Filter by startDate
        // endDate: '<value>' // Filter by endDate
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequests",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"leaveRequests": [
		{
			"id": "ID",
			"userId": "ID",
			"departmentId": "ID",
			"requestDate": "Date",
			"leaveType": "String",
			"startDate": "Date",
			"endDate": "Date",
			"reason": "String",
			"status": "Enum",
			"status_idx": "Integer",
			"approverId": "ID",
			"approvedDate": "Date",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"department": [
				null,
				null,
				null
			],
			"approver": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

List Myleaverequests API

List the currently logged-in user’s own leave requests. Always scoped to the authenticated user’s userId. Available to all roles.

API Frontend Description By The Backend Architect

Rest Route

The listMyLeaveRequests API REST controller can be triggered via the following route:

/v1/myleaverequests

Rest Request Parameters

Filter Parameters

The listMyLeaveRequests api supports 6 optional filter parameters for filtering list results:

userId (ID): ID of employee/user requesting leave (auth:user.id)

departmentId (ID): Department (userGroup) id, for scoping leave if relevant

leaveType (String): Type of leave (e.g. vacation, sick, emergency).

startDate (Date): First day of leave (inclusive).

endDate (Date): Last day of leave (inclusive).

status (Enum): Leave request status (pending, approved, rejected, cancelled).

REST Request To access the api you can use the REST controller with the path GET /v1/myleaverequests

  axios({
    method: 'GET',
    url: '/v1/myleaverequests',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // departmentId: '<value>' // Filter by departmentId
        // leaveType: '<value>' // Filter by leaveType
        // startDate: '<value>' // Filter by startDate
        // endDate: '<value>' // Filter by endDate
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequests",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"leaveRequests": [
		{
			"id": "ID",
			"userId": "ID",
			"departmentId": "ID",
			"requestDate": "Date",
			"leaveType": "String",
			"startDate": "Date",
			"endDate": "Date",
			"reason": "String",
			"status": "Enum",
			"status_idx": "Integer",
			"approverId": "ID",
			"approvedDate": "Date",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"department": [
				null,
				null,
				null
			],
			"approver": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Myleaverequest API

Retrieve the details of a single leave request by ID, scoped to the currently logged-in user. The user can only see their own leave request. Enriches response with user, department, and approver info.

API Frontend Description By The Backend Architect

Rest Route

The getMyLeaveRequest API REST controller can be triggered via the following route:

/v1/myleaverequest/:leaveRequestId

Rest Request Parameters

The getMyLeaveRequest api has got 1 regular request parameter

Parameter Type Required Population
leaveRequestId ID true request.params?.[“leaveRequestId”]
leaveRequestId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/myleaverequest/:leaveRequestId

  axios({
    method: 'GET',
    url: `/v1/myleaverequest/${leaveRequestId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "leaveRequest",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"leaveRequest": {
		"id": "ID",
		"userId": "ID",
		"departmentId": "ID",
		"requestDate": "Date",
		"leaveType": "String",
		"startDate": "Date",
		"endDate": "Date",
		"reason": "String",
		"status": "Enum",
		"status_idx": "Integer",
		"approverId": "ID",
		"approvedDate": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"user": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		},
		"approver": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		}
	}
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-payrollreporting-service

Version: 1.0.9

Handles payroll report records for employees based on calculated hours, overtime, absences from attendance/leave. Provides summary views by user/period/department, allows payment status entry (not processing). Employees can view their own reports. Company tenant scoped and RBAC-enforced.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the PayrollReporting Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our PayrollReporting Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the PayrollReporting Service via HTTP requests for purposes such as creating, updating, deleting and querying PayrollReporting objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the PayrollReporting Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the PayrollReporting service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the PayrollReporting service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the PayrollReporting service.

This service is configured to listen for HTTP requests on port 3006, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the PayrollReporting service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The PayrollReporting service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the PayrollReporting service.

Multi Tenant Architecture

The PayrollReporting service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the PayrollReporting service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the PayrollReporting service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the PayrollReporting service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

PayrollReporting service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

PayrollReport resource

Resource Definition : Represents a calculated payroll report for a single employee and pay period. Contains total hours worked, overtime, absences, calculated salary based on shift attendance, bonuses/deductions, and manual payment status (no actual payment processing). PayrollReport Resource Properties

Name Type Required Default Definition
userId ID Reference to the user/employee this report summarizes (auth:user.id).
periodStart Date Start date of reporting/payroll period (inclusive).
periodEnd Date End date of the reporting/payroll period (inclusive).
totalHoursWorked Double Total hours worked during this period (summed from attendance data, auto-calculated).
overtimeHours Double Total overtime hours for period (auto-calculated from attendance, company policy).
absenceDays Integer Total days absent during period (from leave & attendance). Auto-calculated.
bonus Double Manual bonus to add for this period (optional entry by admin/manager only).
deduction Double Manual deduction for this period (optional entry by admin/manager only).
salaryCalculated Double Auto-calculated salary for the period: base salary, hours, overtime, bonuses, and deductions. Always calculated, never direct entry.
paymentStatus Enum Manual entry tracking payment status for this period ('paid', 'unpaid', 'partial', 'pending').
paymentDate Date Manual entry of actual date payment was made for this period (optional, admins/managers only).
notes String Optional notes (manual, internal)—remark/history on payment changes, bonuses, or irregularities.
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

paymentStatus Enum Property

Property Definition : Manual entry tracking payment status for this period ('paid', 'unpaid', 'partial', 'pending').Enum Options

Name Value Index
paid "paid"" 0
unpaid "unpaid"" 1
partial "partial"" 2
pending "pending"" 3

Business Api

Create Payrollreport API

[Default create API] — This is the designated default create API for the payrollReport data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a payroll report for a user and period; auto-calculates hours, overtime, absences, salary from attendance/leave. Allowed for admins/managers. Enforces report uniqueness and ownership. Manual entry only allowed for paymentStatus/bonus/deduction/notes (not raw hours/salary).

API Frontend Description By The Backend Architect

This API creates a payroll report for the chosen employee for a pay period, auto-deriving all work hour data from canonical attendance and leave logs. Admins/managers may set payment status, bonus, deduction and notes upon creation, but all time fields are system-calculated. Creating a payroll report when one exists for user/period will update the report (idempotent).

Rest Route

The createPayrollReport API REST controller can be triggered via the following route:

/v1/payrollreports

Rest Request Parameters

The createPayrollReport api has got 8 regular request parameters

Parameter Type Required Population
userId ID true request.body?.[“userId”]
periodStart Date true request.body?.[“periodStart”]
periodEnd Date true request.body?.[“periodEnd”]
bonus Double false request.body?.[“bonus”]
deduction Double false request.body?.[“deduction”]
notes String false request.body?.[“notes”]
paymentStatus Enum false request.body?.[“paymentStatus”]
paymentDate Date false request.body?.[“paymentDate”]
userId : The userId for whom to generate the payroll report.
periodStart : Payroll period start date (inclusive).
periodEnd : Payroll period end date (inclusive).
bonus : Optional manual bonus.
deduction : Optional manual deduction.
notes : Notes for this payroll report.
paymentStatus : Manual status (paid, unpaid, partial, pending).
paymentDate : Manual date of payment, if any.

REST Request To access the api you can use the REST controller with the path POST /v1/payrollreports

  axios({
    method: 'POST',
    url: '/v1/payrollreports',
    data: {
            userId:"ID",  
            periodStart:"Date",  
            periodEnd:"Date",  
            bonus:"Double",  
            deduction:"Double",  
            notes:"String",  
            paymentStatus:"Enum",  
            paymentDate:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "payrollReport",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"payrollReport": {
		"user": {
			"fullname": "String",
			"avatar": "String"
		},
		"isActive": true
	}
}

Update Payrollreport API

[Default update API] — This is the designated default update API for the payrollReport data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update paymentStatus/paymentDate, bonus, deduction, or notes for a payroll report. All worked hours/absence/salary remain auto-calculated. Only payroll admins/managers allowed. All changes are logged for audit.

API Frontend Description By The Backend Architect

Allows admins/managers to update the payment status, payment date, bonus, deduction, and report notes for an existing payroll period for an employee. No update to hours, absences, or salary is accepted directly (these remain auto-calculated on update). All updates are logged for audit trail. Editing salary must trigger recalculation with new bonuses/deductions if provided.

Rest Route

The updatePayrollReport API REST controller can be triggered via the following route:

/v1/payrollReports/:payrollReportId

Rest Request Parameters

The updatePayrollReport api has got 6 regular request parameters

Parameter Type Required Population
payrollReportId ID true request.params?.[“payrollReportId”]
bonus Double false request.body?.[“bonus”]
deduction Double false request.body?.[“deduction”]
notes String false request.body?.[“notes”]
paymentStatus Enum false request.body?.[“paymentStatus”]
paymentDate Date false request.body?.[“paymentDate”]
payrollReportId : ID of payroll report to update.
bonus : Update bonus.
deduction : Update deduction.
notes : Update notes.
paymentStatus : Update payment status.
paymentDate : Update payment date.

REST Request To access the api you can use the REST controller with the path PATCH /v1/payrollReports/:payrollReportId

  axios({
    method: 'PATCH',
    url: `/v1/payrollReports/${payrollReportId}`,
    data: {
            bonus:"Double",  
            deduction:"Double",  
            notes:"String",  
            paymentStatus:"Enum",  
            paymentDate:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "payrollReport",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"payrollReport": {
		"user": {
			"fullname": "String",
			"avatar": "String"
		},
		"isActive": true
	}
}

Get Payrollreport API

[Default get API] — This is the designated default get API for the payrollReport data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get a specific payroll report and its calculated details for a pay period and employee. Employees may fetch only their own; admins/managers may fetch any for their company.

API Frontend Description By The Backend Architect

Fetches a payroll report for the given id. Enriches response with user (employee) summary, covering total hours, overtime, absences, salary, payment status and optional bonuses/deductions/notes. Employees can’t see reports not their own; admin/manager may fetch any within company.

Rest Route

The getPayrollReport API REST controller can be triggered via the following route:

/v1/payrollReports/:payrollReportId

Rest Request Parameters

The getPayrollReport api has got 1 regular request parameter

Parameter Type Required Population
payrollReportId ID true request.params?.[“payrollReportId”]
payrollReportId : ID of payroll report to fetch.

REST Request To access the api you can use the REST controller with the path GET /v1/payrollReports/:payrollReportId

  axios({
    method: 'GET',
    url: `/v1/payrollReports/${payrollReportId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "payrollReport",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"payrollReport": {
		"user": {
			"fullname": "String",
			"avatar": "String"
		},
		"isActive": true
	}
}

List Payrollreports API

[Default list API] — This is the designated default list API for the payrollReport data object. Frontend generators and AI agents should use this API for standard CRUD operations. List payroll reports for employees. Employees can view their own; managers/admins can filter and list by user/period/department for the company.

API Frontend Description By The Backend Architect

Lists all payroll reports accessible to the calling user in their company scope. Employees see only their own payroll history; company admins/managers can filter by user, payroll period, payment status for reporting or payroll review. Supports pagination and can be enriched per-user/department via selectJoin.

Rest Route

The listPayrollReports API REST controller can be triggered via the following route:

/v1/payrollreports

Rest Request Parameters

The listPayrollReports api has got 4 regular request parameters

Parameter Type Required Population
userId ID false request.query?.[“userId”]
periodStart Date false request.query?.[“periodStart”]
periodEnd Date false request.query?.[“periodEnd”]
paymentStatus Enum false request.query?.[“paymentStatus”]
userId : Filter by employee userId.
periodStart : Filter period - date on or after
periodEnd : Filter period - date on or before
paymentStatus : Filter by payment status.

REST Request To access the api you can use the REST controller with the path GET /v1/payrollreports

  axios({
    method: 'GET',
    url: '/v1/payrollreports',
    data: {
    
    },
    params: {
             userId:'"ID"',  
             periodStart:'"Date"',  
             periodEnd:'"Date"',  
             paymentStatus:'"Enum"',  
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "payrollReports",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"payrollReports": [
		{
			"user": [
				{
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-announcementmanagement-service

Version: 1.0.10

Handles company-wide and department-specific announcements, supporting scheduled or immediate delivery. Enables admins/managers to create, edit, and manage rich-text announcements, assign audience (all/company/department/users), and triggers events for notification delivery. Employees see relevant announcements in history/detail. Fully tenant-scoped.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the AnnouncementManagement Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our AnnouncementManagement Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the AnnouncementManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying AnnouncementManagement objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the AnnouncementManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the AnnouncementManagement service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the AnnouncementManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the AnnouncementManagement service.

This service is configured to listen for HTTP requests on port 3022, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the AnnouncementManagement service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The AnnouncementManagement service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the AnnouncementManagement service.

Multi Tenant Architecture

The AnnouncementManagement service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the AnnouncementManagement service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the AnnouncementManagement service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the AnnouncementManagement service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

AnnouncementManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

Announcement resource

Resource Definition : A company announcement created by admin/manager for company- or department-wide communication. Supports scheduled (future) or immediate send, rich-text content, explicit audience assignment, and visibility expiry. Announcement Resource Properties

Name Type Required Default Definition
creatorId ID auth:user.id - Creator of the announcement
title String Announcement subject/title (short display name).
body Text Announcement content body (markdown/HTML string).
targetDepartmentIds ID Department userGroup IDs (auth:userGroup.id) to target recipients. Null/empty means all departments. Used for scoping announcements to groups.
audienceUserIds ID Explicit user IDs (auth:user.id) to target (optional, null=all applicable). Used for targeting specific individuals only if needed. Supercedes departments if set.
sendTime Date Scheduled send time for the announcement (UTC). Immediate if now/past, future means scheduled/pending delivery. Used for status logic.
visibleUntil Date Optional. Announcements are visible until this date (expiry). If null, visible for a platform-defined default duration (e.g., 30/90 days, or forever).
status Enum Announcement status: scheduled (future, unsent); sent (visible/delivered); cancelled (withdrawn by admin/manager); status changes control delivery/event publishing.
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Announcement status: scheduled (future, unsent); sent (visible/delivered); cancelled (withdrawn by admin/manager); status changes control delivery/event publishing.Enum Options

Name Value Index
scheduled "scheduled"" 0
sent "sent"" 1
cancelled "cancelled"" 2

Business Api

Create Announcement API

[Default create API] — This is the designated default create API for the announcement data object. Frontend generators and AI agents should use this API for standard CRUD operations. Admins/managers create a new announcement for company or targeted audience. Supports scheduled and immediate announcements. Upon creation, if sendTime <= now and not cancelled, triggers event for notification delivery.

API Frontend Description By The Backend Architect

Rest Route

The createAnnouncement API REST controller can be triggered via the following route:

/v1/announcements

Rest Request Parameters

The createAnnouncement api has got 6 regular request parameters

Parameter Type Required Population
title String true request.body?.[“title”]
body Text true request.body?.[“body”]
targetDepartmentIds ID false request.body?.[“targetDepartmentIds”]
audienceUserIds ID false request.body?.[“audienceUserIds”]
sendTime Date true request.body?.[“sendTime”]
visibleUntil Date false request.body?.[“visibleUntil”]
title : Announcement subject/title (short display name).
body : Announcement content body (markdown/HTML string).
targetDepartmentIds : Department userGroup IDs (auth:userGroup.id) to target recipients. Null/empty means all departments. Used for scoping announcements to groups.
audienceUserIds : Explicit user IDs (auth:user.id) to target (optional, null=all applicable). Used for targeting specific individuals only if needed. Supercedes departments if set.
sendTime : Scheduled send time for the announcement (UTC). Immediate if now/past, future means scheduled/pending delivery. Used for status logic.
visibleUntil : Optional. Announcements are visible until this date (expiry). If null, visible for a platform-defined default duration (e.g., 30/90 days, or forever).

REST Request To access the api you can use the REST controller with the path POST /v1/announcements

  axios({
    method: 'POST',
    url: '/v1/announcements',
    data: {
            title:"String",  
            body:"Text",  
            targetDepartmentIds:"ID",  
            audienceUserIds:"ID",  
            sendTime:"Date",  
            visibleUntil:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "announcement",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"announcement": {
		"id": "ID",
		"creatorId": "ID",
		"title": "String",
		"body": "Text",
		"targetDepartmentIds": "ID",
		"audienceUserIds": "ID",
		"sendTime": "Date",
		"visibleUntil": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Announcement API

[Default update API] — This is the designated default update API for the announcement data object. Frontend generators and AI agents should use this API for standard CRUD operations. Admins/managers update a scheduled/cancelled announcement. Not allowed if already sent. If sendTime changes to now or past, triggers sent event and status update on save.

API Frontend Description By The Backend Architect

Rest Route

The updateAnnouncement API REST controller can be triggered via the following route:

/v1/announcements/:announcementId

Rest Request Parameters

The updateAnnouncement api has got 7 regular request parameters

Parameter Type Required Population
announcementId ID true request.params?.[“announcementId”]
title String false request.body?.[“title”]
body Text false request.body?.[“body”]
targetDepartmentIds ID false request.body?.[“targetDepartmentIds”]
audienceUserIds ID false request.body?.[“audienceUserIds”]
sendTime Date true request.body?.[“sendTime”]
visibleUntil Date false request.body?.[“visibleUntil”]
announcementId : This id paremeter is used to select the required data object that will be updated
title : Announcement subject/title (short display name).
body : Announcement content body (markdown/HTML string).
targetDepartmentIds : Department userGroup IDs (auth:userGroup.id) to target recipients. Null/empty means all departments. Used for scoping announcements to groups.
audienceUserIds : Explicit user IDs (auth:user.id) to target (optional, null=all applicable). Used for targeting specific individuals only if needed. Supercedes departments if set.
sendTime : Scheduled send time for the announcement (UTC). Immediate if now/past, future means scheduled/pending delivery. Used for status logic.
visibleUntil : Optional. Announcements are visible until this date (expiry). If null, visible for a platform-defined default duration (e.g., 30/90 days, or forever).

REST Request To access the api you can use the REST controller with the path PATCH /v1/announcements/:announcementId

  axios({
    method: 'PATCH',
    url: `/v1/announcements/${announcementId}`,
    data: {
            title:"String",  
            body:"Text",  
            targetDepartmentIds:"ID",  
            audienceUserIds:"ID",  
            sendTime:"Date",  
            visibleUntil:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "announcement",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"announcement": {
		"id": "ID",
		"creatorId": "ID",
		"title": "String",
		"body": "Text",
		"targetDepartmentIds": "ID",
		"audienceUserIds": "ID",
		"sendTime": "Date",
		"visibleUntil": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Announcement API

[Default delete API] — This is the designated default delete API for the announcement data object. Frontend generators and AI agents should use this API for standard CRUD operations. Soft delete (mark as cancelled) for scheduled/cancelled announcements. Sent announcements cannot be deleted.

API Frontend Description By The Backend Architect

Admins/managers can cancel (soft delete) announcements that have not been sent yet; sent announcements stay in history, cannot be deleted for auditability/accountability.

Rest Route

The deleteAnnouncement API REST controller can be triggered via the following route:

/v1/announcements/:announcementId

Rest Request Parameters

The deleteAnnouncement api has got 1 regular request parameter

Parameter Type Required Population
announcementId ID true request.params?.[“announcementId”]
announcementId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/announcements/:announcementId

  axios({
    method: 'DELETE',
    url: `/v1/announcements/${announcementId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "announcement",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"announcement": {
		"id": "ID",
		"creatorId": "ID",
		"title": "String",
		"body": "Text",
		"targetDepartmentIds": "ID",
		"audienceUserIds": "ID",
		"sendTime": "Date",
		"visibleUntil": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Announcement API

[Default get API] — This is the designated default get API for the announcement data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get details of a single announcement if user is within company and eligible audience. Employees see only those sent & visible; admins/managers see all for own company.

API Frontend Description By The Backend Architect

Rest Route

The getAnnouncement API REST controller can be triggered via the following route:

/v1/announcements/:announcementId

Rest Request Parameters

The getAnnouncement api has got 1 regular request parameter

Parameter Type Required Population
announcementId ID true request.params?.[“announcementId”]
announcementId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/announcements/:announcementId

  axios({
    method: 'GET',
    url: `/v1/announcements/${announcementId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "announcement",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"announcement": {
		"creator": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		},
		"departments": [
			null,
			null,
			null
		],
		"isActive": true
	}
}

List Announcements API

[Default list API] — This is the designated default list API for the announcement data object. Frontend generators and AI agents should use this API for standard CRUD operations. List announcements visible to user: employees get only those sent and addressed to their dept/user/all; admin/manager see all for their company; sorted by sendTime desc.

API Frontend Description By The Backend Architect

Rest Route

The listAnnouncements API REST controller can be triggered via the following route:

/v1/announcements

Rest Request Parameters The listAnnouncements api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/announcements

  axios({
    method: 'GET',
    url: '/v1/announcements',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "announcements",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"announcements": [
		{
			"creator": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"departments": [
				null,
				null,
				null
			],
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Process Scheduledannouncements API

Background job that runs every minute to check for scheduled announcements whose sendTime has passed and updates their status to ‘sent’. This triggers the announcement.sent event for notification delivery.

API Frontend Description By The Backend Architect

Internal cron job - no frontend endpoint. Runs automatically every minute to process scheduled announcements.

Rest Route

The processScheduledAnnouncements API REST controller can be triggered via the following route:

/v1/processscheduledannouncements

Rest Request Parameters

Filter Parameters

The processScheduledAnnouncements api supports 4 optional filter parameters for filtering list results:

creatorId (ID): auth:user.id - Creator of the announcement

title (String): Announcement subject/title (short display name).

sendTime (Date): Scheduled send time for the announcement (UTC). Immediate if now/past, future means scheduled/pending delivery. Used for status logic.

status (Enum): Announcement status: scheduled (future, unsent); sent (visible/delivered); cancelled (withdrawn by admin/manager); status changes control delivery/event publishing.

REST Request To access the api you can use the REST controller with the path GET /v1/processscheduledannouncements

  axios({
    method: 'GET',
    url: '/v1/processscheduledannouncements',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // creatorId: '<value>' // Filter by creatorId
        // title: '<value>' // Filter by title
        // sendTime: '<value>' // Filter by sendTime
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "announcements",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"announcements": [
		{
			"id": "ID",
			"creatorId": "ID",
			"title": "String",
			"body": "Text",
			"targetDepartmentIds": "ID",
			"audienceUserIds": "ID",
			"sendTime": "Date",
			"visibleUntil": "Date",
			"status": "Enum",
			"status_idx": "Integer",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-aiworkforceanalytics-service

Version: 1.0.134

Microservice for computing and delivering AI-powered workforce analytics (e.g., shift optimization, absenteeism insights, staffing trends) for eligible (subscribed) companies. Handles insight calculation, storage, and secure distribution to authorized users. Publishes insight alerts/events for notifications. Strictly enforces company data isolation and subscription gating on all features.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the AiWorkforceAnalytics Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our AiWorkforceAnalytics Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the AiWorkforceAnalytics Service via HTTP requests for purposes such as creating, updating, deleting and querying AiWorkforceAnalytics objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the AiWorkforceAnalytics Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the AiWorkforceAnalytics service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the AiWorkforceAnalytics service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the AiWorkforceAnalytics service.

This service is configured to listen for HTTP requests on port 3006, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the AiWorkforceAnalytics service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The AiWorkforceAnalytics service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the AiWorkforceAnalytics service.

Multi Tenant Architecture

The AiWorkforceAnalytics service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the AiWorkforceAnalytics service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the AiWorkforceAnalytics service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the AiWorkforceAnalytics service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

AiWorkforceAnalytics service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

AiInsight resource

Resource Definition : Represents an AI-generated insight, analytic, or tip for a company (and optionally individual user) for a specific period/type. Used for staffing recommendations, absenteeism patterns, productivity, and targeted advice. Stores computed detail as JSON and current delivery/processing status. AiInsight Resource Properties

Name Type Required Default Definition
insightType String Type/classification of the insight (e.g. 'staffingPrediction', 'absenteeismPattern', 'shiftAnomaly', 'productivityTip').
audienceUserId ID If present, insight is for a specific employee; otherwise company/manager-level.
applicablePeriod Object Date range period to which the insight applies (object: {startDate, endDate})
details Text JSON-stringified blob containing the AI result, message, chart data, or recommendation.
aiStatus Enum Status of the insight; pending (to deliver), delivered (published), error (AI-failed/delivery failed).
deliveredTime Date Actual delivery/publication time (set when status becomes 'delivered'); null when pending.
companyId ID An ID value to represent the tenant id of the company

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

aiStatus Enum Property

Property Definition : Status of the insight; pending (to deliver), delivered (published), error (AI-failed/delivery failed).Enum Options

Name Value Index
pending "pending"" 0
delivered "delivered"" 1
error "error"" 2

Business Api

Create Aiinsight API

[Default create API] — This is the designated default create API for the aiInsight data object. Frontend generators and AI agents should use this API for standard CRUD operations. Internal/system API to create a new AI insight record for a company and period (typically used by AI agents or cron jobs, not direct user input). Requires that company has an active AI subscription. Sets status to pending; downstream process delivers and updates status.

API Frontend Description By The Backend Architect

Not a user-facing API. Used by the platform for inserting new insight data for later dashboard/alert delivery.

Rest Route

The createAiInsight API REST controller can be triggered via the following route:

/v1/aiinsights

Rest Request Parameters

The createAiInsight api has got 6 regular request parameters

Parameter Type Required Population
insightType String true request.body?.[“insightType”]
audienceUserId ID false request.body?.[“audienceUserId”]
applicablePeriod Object true request.body?.[“applicablePeriod”]
details Text true request.body?.[“details”]
aiStatus Enum true request.body?.[“aiStatus”]
deliveredTime Date false request.body?.[“deliveredTime”]
insightType : Type/classification of the insight (e.g. ‘staffingPrediction’, ‘absenteeismPattern’, ‘shiftAnomaly’, ‘productivityTip’).
audienceUserId : If present, insight is for a specific employee; otherwise company/manager-level.
applicablePeriod : Date range period to which the insight applies (object: {startDate, endDate})
details : JSON-stringified blob containing the AI result, message, chart data, or recommendation.
aiStatus : Status of the insight; pending (to deliver), delivered (published), error (AI-failed/delivery failed).
deliveredTime : Actual delivery/publication time (set when status becomes ‘delivered’); null when pending.

REST Request To access the api you can use the REST controller with the path POST /v1/aiinsights

  axios({
    method: 'POST',
    url: '/v1/aiinsights',
    data: {
            insightType:"String",  
            audienceUserId:"ID",  
            applicablePeriod:"Object",  
            details:"Text",  
            aiStatus:"Enum",  
            deliveredTime:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "aiInsight",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"aiInsight": {
		"id": "ID",
		"insightType": "String",
		"audienceUserId": "ID",
		"applicablePeriod": "Object",
		"details": "Text",
		"aiStatus": "Enum",
		"aiStatus_idx": "Integer",
		"deliveredTime": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Aiinsight API

[Default get API] — This is the designated default get API for the aiInsight data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get a detailed AI insight for dashboards or notification rendering. Only accessible to: admin/manager of company, or employee for their tips (audienceUserId matches requester) AND company has active subscription.

API Frontend Description By The Backend Architect

FE must use this API to show a detailed AI insight. Employees may only see their own tips (if audienceUserId matches their userId), admin/managers may see all for their company.

Rest Route

The getAiInsight API REST controller can be triggered via the following route:

/v1/insights/:id

Rest Request Parameters

The getAiInsight api has got 2 regular request parameters

Parameter Type Required Population
aiInsightId ID true request.params?.[“aiInsightId”]
id String true request.params?.[“id”]
aiInsightId : This id paremeter is used to query the required data object.
id : This parameter will be used to select the data object that is queried

REST Request To access the api you can use the REST controller with the path GET /v1/insights/:id

  axios({
    method: 'GET',
    url: `/v1/insights/${id}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "aiInsight",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"aiInsight": {
		"audienceUser": {
			"email": "String",
			"fullname": "String",
			"avatar": "String"
		},
		"isActive": true
	}
}

List Aiinsights API

[Default list API] — This is the designated default list API for the aiInsight data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all accessible AI insights for dashboards or user tip listings, scoped by role and audienceUserId, and company subscription. Filter by type, status, period.

API Frontend Description By The Backend Architect

Use this API to build an AI insights dashboard for company (admin/manager: all insights; employee: only their own or broadcast tips). Use filters as appropriate for time/type/audience. UI must show no data if company is not subscribed.

Rest Route

The listAiInsights API REST controller can be triggered via the following route:

/v1/insights

Rest Request Parameters The listAiInsights api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/insights

  axios({
    method: 'GET',
    url: '/v1/insights',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

This route’s response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "aiInsights",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"aiInsights": [
		{
			"audienceUser": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			],
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Save Insight API

Saves an AI workforce insight from stream conversation to database for history tracking

Rest Route

The saveInsight API REST controller can be triggered via the following route:

/v1/saveinsight

Rest Request Parameters

The saveInsight api has got 13 regular request parameters

Parameter Type Required Population
title String true request.body?.[“title”]
summary String true request.body?.[“summary”]
insightType String true request.body?.[“insightType”]
audienceType String true request.body?.[“audienceType”]
chart Object false request.body?.[“chart”]
data Object false request.body?.[“data”]
suggestion String false request.body?.[“suggestion”]
period String false request.body?.[“period”]
audienceUserId String false request.body?.[“audienceUserId”]
applicablePeriod Object true request.body?.[“applicablePeriod”]
details Text true request.body?.[“details”]
aiStatus Enum true request.body?.[“aiStatus”]
deliveredTime Date false request.body?.[“deliveredTime”]
title : Insight title from AI stream
summary : Insight summary from AI stream
insightType : Type of insight (shift_optimization, absenteeism_alert, etc.)
audienceType : Target audience (admin, manager, employee, company)
chart : Optional chart data from AI
data : Additional data from AI insight
suggestion : AI suggestion/recommendation
period : Time period for the insight
audienceUserId : Specific user ID if personalized
applicablePeriod : Date range period to which the insight applies (object: {startDate, endDate})
details : JSON-stringified blob containing the AI result, message, chart data, or recommendation.
aiStatus : Status of the insight; pending (to deliver), delivered (published), error (AI-failed/delivery failed).
deliveredTime : Actual delivery/publication time (set when status becomes ‘delivered’); null when pending.

REST Request To access the api you can use the REST controller with the path POST /v1/saveinsight

  axios({
    method: 'POST',
    url: '/v1/saveinsight',
    data: {
            title:"String",  
            summary:"String",  
            insightType:"String",  
            audienceType:"String",  
            chart:"Object",  
            data:"Object",  
            suggestion:"String",  
            period:"String",  
            audienceUserId:"String",  
            applicablePeriod:"Object",  
            details:"Text",  
            aiStatus:"Enum",  
            deliveredTime:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "aiInsight",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"aiInsight": {
		"id": "ID",
		"insightType": "String",
		"audienceUserId": "ID",
		"applicablePeriod": "Object",
		"details": "Text",
		"aiStatus": "Enum",
		"aiStatus_idx": "Integer",
		"deliveredTime": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Save Aiinsight API

Saves an AI workforce insight from stream conversation to database for history tracking

Rest Route

The saveAiInsight API REST controller can be triggered via the following route:

/v1/save-insight

Rest Request Parameters

The saveAiInsight api has got 1 regular request parameter

Parameter Type Required Population
insightType String false request.body?.[“insightType”]
insightType : Type of insight (auto-detected by AI agent)

REST Request To access the api you can use the REST controller with the path POST /v1/save-insight

  axios({
    method: 'POST',
    url: '/v1/save-insight',
    data: {
            insightType:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "aiInsight",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"aiInsight": {
		"id": "ID",
		"insightType": "String",
		"audienceUserId": "ID",
		"applicablePeriod": "Object",
		"details": "Text",
		"aiStatus": "Enum",
		"aiStatus_idx": "Integer",
		"deliveredTime": "Date",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-subscriptionmanagement-service

Version: 1.0.26

Manages company AI subscriptions through Stripe payments. Companies must pay via Stripe to activate AI features—no manual subscription creation allowed. Handles the full Stripe payment lifecycle: checkout, payment confirmation, activation, and cancellation. The subscription status is entirely driven by Stripe webhook events. SuperAdmin/saasAdmin bypass payment for platform management.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the SubscriptionManagement Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our SubscriptionManagement Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the SubscriptionManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying SubscriptionManagement objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the SubscriptionManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the SubscriptionManagement service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the SubscriptionManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the SubscriptionManagement service.

This service is configured to listen for HTTP requests on port 3009, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the SubscriptionManagement service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The SubscriptionManagement service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the SubscriptionManagement service.

Multi Tenant Architecture

The SubscriptionManagement service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the SubscriptionManagement service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the SubscriptionManagement service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the SubscriptionManagement service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

SubscriptionManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

CompanySubscription resource

Resource Definition : Represents a company's active or inactive subscription record for feature gating (AI, analytics, etc.). Used to track activation/expiry, status, available features, and audit trail of renewals. 1 per company; used for entitlement checking. CompanySubscription Resource Properties

Name Type Required Default Definition
activationDate Date Start date/time when subscription is (re)activated.
expiryDate Date Planned end date/time of subscription validity (inclusive).
status Enum Subscription status: active, inactive, pending, or expired.
subscribedFeatures String Array of enabled feature flags for this company's subscription (e.g., aiAnalytics, reporting, notifications).
lastRenewedBy ID ID of user (admin/mod) who last renewed or updated the subscription record; for audit.
currency String ISO currency code for the subscription payment. Defaults to usd.
paymentStatus Enum Stripe payment status: pending (awaiting payment), paid (success), failed, canceled.
paymentStatusUpdatedAt Date Timestamp of the last payment status change from Stripe.
ownerId ID The user who initiated the subscription purchase. Used for Stripe payment ownership.
stripeSubscriptionId String Stripe subscription ID for recurring billing management. Set after successful payment.
amount Integer Subscription price in cents (e.g. 4999 = $49.99). Used by Stripe payment flow.
companyId ID An ID value to represent the tenant id of the company
paymentConfirmation Enum An automatic property that is used to check the confirmed status of the payment set by webhooks.

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

status Enum Property

Property Definition : Subscription status: active, inactive, pending, or expired.Enum Options

Name Value Index
active "active"" 0
inactive "inactive"" 1
pending "pending"" 2
expired "expired"" 3
paymentStatus Enum Property

Property Definition : Stripe payment status: pending (awaiting payment), paid (success), failed, canceled.Enum Options

Name Value Index
pending "pending"" 0
paid "paid"" 1
failed "failed"" 2
canceled "canceled"" 3
paymentConfirmation Enum Property

Property Definition : An automatic property that is used to check the confirmed status of the payment set by webhooks.Enum Options

Name Value Index
pending "pending"" 0
processing "processing"" 1
paid "paid"" 2
canceled "canceled"" 3

Sys_companySubscriptionPayment resource

Resource Definition : A payment storage object to store the payment life cyle of orders based on companySubscription object. It is autocreated based on the source object's checkout config Sys_companySubscriptionPayment Resource Properties

Name Type Required Default Definition
ownerId ID * An ID value to represent owner user who created the order*
orderId ID an ID value to represent the orderId which is the ID parameter of the source companySubscription object
paymentId String A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type
paymentStatus String A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.
statusLiteral String A string value to represent the logical payment status which belongs to the application lifecycle itself.
redirectUrl String A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.
companyId ID An ID value to represent the tenant id of the company

Sys_paymentCustomer resource

Resource Definition : A payment storage object to store the customer values of the payment platform Sys_paymentCustomer Resource Properties

Name Type Required Default Definition
userId ID * An ID value to represent the user who is created as a stripe customer*
customerId String A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway
platform String A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future.
companyId ID An ID value to represent the tenant id of the company

Sys_paymentMethod resource

Resource Definition : A payment storage object to store the payment methods of the platform customers Sys_paymentMethod Resource Properties

Name Type Required Default Definition
paymentMethodId String A string value to represent the id of the payment method on the payment platform.
userId ID * An ID value to represent the user who owns the payment method*
customerId String A string value to represent the customer id which is generated on the payment gateway.
cardHolderName String A string value to represent the name of the card holder. It can be different than the registered customer.
cardHolderZip String A string value to represent the zip code of the card holder. It is used for address verification in specific countries.
platform String A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future.
cardInfo Object A Json value to store the card details of the payment method.
companyId ID An ID value to represent the tenant id of the company

Business Api

Create Companysubscription API

[Default create API] — This is the designated default create API for the companySubscription data object. Frontend generators and AI agents should use this API for standard CRUD operations. Initiates a new subscription purchase for the company. Creates the record in pending state and triggers the Stripe payment flow. The frontend receives a Stripe checkout URL. Once payment succeeds, the edgeFunctionPaymentDone callback automatically activates the subscription. Only tenantOwner/tenantAdmin can initiate. Prevents duplicate active/pending subscriptions.

API Frontend Description By The Backend Architect

Company admins use this to start their AI subscription. After calling this API, the response includes a Stripe checkout URL. Redirect the user to that URL to complete payment. Once payment succeeds, the subscription becomes active automatically. Do NOT let users set status or dates—those are system-managed.

Rest Route

The createCompanySubscription API REST controller can be triggered via the following route:

/v1/companysubscriptions

Rest Request Parameters

The createCompanySubscription api has got 9 regular request parameters

Parameter Type Required Population
activationDate Date true request.body?.[“activationDate”]
expiryDate Date true request.body?.[“expiryDate”]
status Enum true request.body?.[“status”]
subscribedFeatures String false request.body?.[“subscribedFeatures”]
lastRenewedBy ID false request.body?.[“lastRenewedBy”]
currency String false request.body?.[“currency”]
paymentStatusUpdatedAt Date false request.body?.[“paymentStatusUpdatedAt”]
ownerId ID true request.body?.[“ownerId”]
stripeSubscriptionId String false request.body?.[“stripeSubscriptionId”]
activationDate : Start date/time when subscription is (re)activated.
expiryDate : Planned end date/time of subscription validity (inclusive).
status : Subscription status: active, inactive, pending, or expired.
subscribedFeatures : Array of enabled feature flags for this company’s subscription (e.g., aiAnalytics, reporting, notifications).
lastRenewedBy : ID of user (admin/mod) who last renewed or updated the subscription record; for audit.
currency : ISO currency code for the subscription payment. Defaults to usd.
paymentStatusUpdatedAt : Timestamp of the last payment status change from Stripe.
ownerId : The user who initiated the subscription purchase. Used for Stripe payment ownership.
stripeSubscriptionId : Stripe subscription ID for recurring billing management. Set after successful payment.

REST Request To access the api you can use the REST controller with the path POST /v1/companysubscriptions

  axios({
    method: 'POST',
    url: '/v1/companysubscriptions',
    data: {
            activationDate:"Date",  
            expiryDate:"Date",  
            status:"Enum",  
            subscribedFeatures:"String",  
            lastRenewedBy:"ID",  
            currency:"String",  
            paymentStatusUpdatedAt:"Date",  
            ownerId:"ID",  
            stripeSubscriptionId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Companysubscription API

[Default update API] — This is the designated default update API for the companySubscription data object. Frontend generators and AI agents should use this API for standard CRUD operations. Admin-only API for manually adjusting subscription records. Only superAdmin/saasAdmin may use. Company admins cannot manually change their subscription—all status changes are driven by Stripe payment events. Used for platform support cases only.

API Frontend Description By The Backend Architect

Only visible to SaaS/SuperAdmin in support dashboards. Company admins have no access. Use for manual corrections only.

Rest Route

The updateCompanySubscription API REST controller can be triggered via the following route:

/v1/companysubscriptions/:companySubscriptionId

Rest Request Parameters

The updateCompanySubscription api has got 8 regular request parameters

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
activationDate Date false request.body?.[“activationDate”]
expiryDate Date false request.body?.[“expiryDate”]
status Enum false request.body?.[“status”]
subscribedFeatures String false request.body?.[“subscribedFeatures”]
lastRenewedBy ID false request.body?.[“lastRenewedBy”]
paymentStatusUpdatedAt Date false request.body?.[“paymentStatusUpdatedAt”]
stripeSubscriptionId String false request.body?.[“stripeSubscriptionId”]
companySubscriptionId : This id paremeter is used to select the required data object that will be updated
activationDate : Start date/time when subscription is (re)activated.
expiryDate : Planned end date/time of subscription validity (inclusive).
status : Subscription status: active, inactive, pending, or expired.
subscribedFeatures : Array of enabled feature flags for this company’s subscription (e.g., aiAnalytics, reporting, notifications).
lastRenewedBy : ID of user (admin/mod) who last renewed or updated the subscription record; for audit.
paymentStatusUpdatedAt : Timestamp of the last payment status change from Stripe.
stripeSubscriptionId : Stripe subscription ID for recurring billing management. Set after successful payment.

REST Request To access the api you can use the REST controller with the path PATCH /v1/companysubscriptions/:companySubscriptionId

  axios({
    method: 'PATCH',
    url: `/v1/companysubscriptions/${companySubscriptionId}`,
    data: {
            activationDate:"Date",  
            expiryDate:"Date",  
            status:"Enum",  
            subscribedFeatures:"String",  
            lastRenewedBy:"ID",  
            paymentStatusUpdatedAt:"Date",  
            stripeSubscriptionId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Companysubscription API

[Default get API] — This is the designated default get API for the companySubscription data object. Frontend generators and AI agents should use this API for standard CRUD operations. Retrieves the subscription details for the session’s company (tenantOwner/tenantAdmin/tenantUser); SaaS/SuperAdmin can fetch for any company via SaaS-level mode. Used for frontend subscription status checks and for feature gating by other services.

API Frontend Description By The Backend Architect

Used by company admins and by microservices/clients to inspect current subscription and its status/features. Access is allowed only to admins of own company unless SaaS/SuperAdmin.

Rest Route

The getCompanySubscription API REST controller can be triggered via the following route:

/v1/companysubscriptions/:companySubscriptionId

Rest Request Parameters

The getCompanySubscription api has got 1 regular request parameter

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
companySubscriptionId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/companysubscriptions/:companySubscriptionId

  axios({
    method: 'GET',
    url: `/v1/companysubscriptions/${companySubscriptionId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Companysubscriptions API

[Default list API] — This is the designated default list API for the companySubscription data object. Frontend generators and AI agents should use this API for standard CRUD operations. Lists subscriptions. For admins, returns just their company’s; for superAdmin/saasAdmin, returns all companies. Useful for SaaS support dashboards or analytics.

API Frontend Description By The Backend Architect

Only visible to company admins or SaaS support/admins. Used to render support dashboards showing subscription status across companies or for monitoring purposes. Employees do not have access.

Rest Route

The listCompanySubscriptions API REST controller can be triggered via the following route:

/v1/companysubscriptions

Rest Request Parameters

Filter Parameters

The listCompanySubscriptions api supports 5 optional filter parameters for filtering list results:

activationDate (Date): Start date/time when subscription is (re)activated.

expiryDate (Date): Planned end date/time of subscription validity (inclusive).

status (Enum): Subscription status: active, inactive, pending, or expired.

paymentStatus (Enum): Stripe payment status: pending (awaiting payment), paid (success), failed, canceled.

paymentConfirmation (Enum): An automatic property that is used to check the confirmed status of the payment set by webhooks.

REST Request To access the api you can use the REST controller with the path GET /v1/companysubscriptions

  axios({
    method: 'GET',
    url: '/v1/companysubscriptions',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // activationDate: '<value>' // Filter by activationDate
        // expiryDate: '<value>' // Filter by expiryDate
        // status: '<value>' // Filter by status
        // paymentStatus: '<value>' // Filter by paymentStatus
        // paymentConfirmation: '<value>' // Filter by paymentConfirmation
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscriptions",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"companySubscriptions": [
		{
			"id": "ID",
			"activationDate": "Date",
			"expiryDate": "Date",
			"status": "Enum",
			"status_idx": "Integer",
			"subscribedFeatures": "String",
			"lastRenewedBy": "ID",
			"currency": "String",
			"paymentStatus": "Enum",
			"paymentStatus_idx": "Integer",
			"paymentStatusUpdatedAt": "Date",
			"ownerId": "ID",
			"stripeSubscriptionId": "String",
			"amount": "Integer",
			"companyId": "ID",
			"paymentConfirmation": "Enum",
			"paymentConfirmation_idx": "Integer",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Delete Companysubscription API

[Default delete API] — This is the designated default delete API for the companySubscription data object. Frontend generators and AI agents should use this API for standard CRUD operations. Hard or soft deletes a company’s subscription record. Only superAdmin/saasAdmin may use. Should only be used for manual cleanup, not normal workflows (expired/inactive should be handled by update).

API Frontend Description By The Backend Architect

Visible only to SaaS/SuperAdmin for data cleanup. Not normally exposed in UI; used for extreme cases or accident cleanup. Company admins cannot delete; must mark as inactive/expired by update instead.

Rest Route

The deleteCompanySubscription API REST controller can be triggered via the following route:

/v1/companysubscriptions/:companySubscriptionId

Rest Request Parameters

The deleteCompanySubscription api has got 1 regular request parameter

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
companySubscriptionId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/companysubscriptions/:companySubscriptionId

  axios({
    method: 'DELETE',
    url: `/v1/companysubscriptions/${companySubscriptionId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Cancel Companysubscription API

Cancels a company’s active subscription. Calls Stripe to cancel the subscription, then updates the local record to canceled status. Only tenantOwner/tenantAdmin of the owning company or superAdmin/saasAdmin can cancel.

API Frontend Description By The Backend Architect

Company admins use this to cancel their AI subscription. The Stripe subscription is canceled and the local record is updated. After cancellation, AI features are immediately blocked.

Rest Route

The cancelCompanySubscription API REST controller can be triggered via the following route:

/v1/cancelcompanysubscription/:companySubscriptionId

Rest Request Parameters

The cancelCompanySubscription api has got 8 regular request parameters

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
activationDate Date false request.body?.[“activationDate”]
expiryDate Date false request.body?.[“expiryDate”]
status Enum false request.body?.[“status”]
subscribedFeatures String false request.body?.[“subscribedFeatures”]
lastRenewedBy ID false request.body?.[“lastRenewedBy”]
paymentStatusUpdatedAt Date false request.body?.[“paymentStatusUpdatedAt”]
stripeSubscriptionId String false request.body?.[“stripeSubscriptionId”]
companySubscriptionId : This id paremeter is used to select the required data object that will be updated
activationDate : Start date/time when subscription is (re)activated.
expiryDate : Planned end date/time of subscription validity (inclusive).
status : Subscription status: active, inactive, pending, or expired.
subscribedFeatures : Array of enabled feature flags for this company’s subscription (e.g., aiAnalytics, reporting, notifications).
lastRenewedBy : ID of user (admin/mod) who last renewed or updated the subscription record; for audit.
paymentStatusUpdatedAt : Timestamp of the last payment status change from Stripe.
stripeSubscriptionId : Stripe subscription ID for recurring billing management. Set after successful payment.

REST Request To access the api you can use the REST controller with the path PATCH /v1/cancelcompanysubscription/:companySubscriptionId

  axios({
    method: 'PATCH',
    url: `/v1/cancelcompanysubscription/${companySubscriptionId}`,
    data: {
            activationDate:"Date",  
            expiryDate:"Date",  
            status:"Enum",  
            subscribedFeatures:"String",  
            lastRenewedBy:"ID",  
            paymentStatusUpdatedAt:"Date",  
            stripeSubscriptionId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Companysubscriptionpayment API

This route is used to get the payment information by ID.

Rest Route

The getCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/companysubscriptionpayment/:sys_companySubscriptionPaymentId

Rest Request Parameters

The getCompanySubscriptionPayment api has got 1 regular request parameter

Parameter Type Required Population
sys_companySubscriptionPaymentId ID true request.params?.[“sys_companySubscriptionPaymentId”]
sys_companySubscriptionPaymentId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/companysubscriptionpayment/:sys_companySubscriptionPaymentId

  axios({
    method: 'GET',
    url: `/v1/companysubscriptionpayment/${sys_companySubscriptionPaymentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_companySubscriptionPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Companysubscriptionpayments API

This route is used to list all payments.

Rest Route

The listCompanySubscriptionPayments API REST controller can be triggered via the following route:

/v1/companysubscriptionpayments

Rest Request Parameters

Filter Parameters

The listCompanySubscriptionPayments api supports 6 optional filter parameters for filtering list results:

ownerId (ID): An ID value to represent owner user who created the order

orderId (ID): an ID value to represent the orderId which is the ID parameter of the source companySubscription object

paymentId (String): A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type

paymentStatus (String): A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.

statusLiteral (String): A string value to represent the logical payment status which belongs to the application lifecycle itself.

redirectUrl (String): A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

REST Request To access the api you can use the REST controller with the path GET /v1/companysubscriptionpayments

  axios({
    method: 'GET',
    url: '/v1/companysubscriptionpayments',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // ownerId: '<value>' // Filter by ownerId
        // orderId: '<value>' // Filter by orderId
        // paymentId: '<value>' // Filter by paymentId
        // paymentStatus: '<value>' // Filter by paymentStatus
        // statusLiteral: '<value>' // Filter by statusLiteral
        // redirectUrl: '<value>' // Filter by redirectUrl
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayments",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_companySubscriptionPayments": [
		{
			"id": "ID",
			"ownerId": "ID",
			"orderId": "ID",
			"paymentId": "String",
			"paymentStatus": "String",
			"statusLiteral": "String",
			"redirectUrl": "String",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Create Companysubscriptionpayment API

This route is used to create a new payment.

Rest Route

The createCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/companysubscriptionpayment

Rest Request Parameters

The createCompanySubscriptionPayment api has got 4 regular request parameters

Parameter Type Required Population
orderId ID true request.body?.[“orderId”]
paymentId String true request.body?.[“paymentId”]
paymentStatus String true request.body?.[“paymentStatus”]
redirectUrl String false request.body?.[“redirectUrl”]
orderId : an ID value to represent the orderId which is the ID parameter of the source companySubscription object
paymentId : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type
paymentStatus : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.
redirectUrl : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

REST Request To access the api you can use the REST controller with the path POST /v1/companysubscriptionpayment

  axios({
    method: 'POST',
    url: '/v1/companysubscriptionpayment',
    data: {
            orderId:"ID",  
            paymentId:"String",  
            paymentStatus:"String",  
            redirectUrl:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayment",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_companySubscriptionPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Update Companysubscriptionpayment API

This route is used to update an existing payment.

Rest Route

The updateCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/companysubscriptionpayment/:sys_companySubscriptionPaymentId

Rest Request Parameters

The updateCompanySubscriptionPayment api has got 4 regular request parameters

Parameter Type Required Population
sys_companySubscriptionPaymentId ID true request.params?.[“sys_companySubscriptionPaymentId”]
paymentId String false request.body?.[“paymentId”]
paymentStatus String false request.body?.[“paymentStatus”]
redirectUrl String false request.body?.[“redirectUrl”]
sys_companySubscriptionPaymentId : This id paremeter is used to select the required data object that will be updated
paymentId : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type
paymentStatus : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.
redirectUrl : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

REST Request To access the api you can use the REST controller with the path PATCH /v1/companysubscriptionpayment/:sys_companySubscriptionPaymentId

  axios({
    method: 'PATCH',
    url: `/v1/companysubscriptionpayment/${sys_companySubscriptionPaymentId}`,
    data: {
            paymentId:"String",  
            paymentStatus:"String",  
            redirectUrl:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayment",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_companySubscriptionPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Delete Companysubscriptionpayment API

This route is used to delete a payment.

Rest Route

The deleteCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/companysubscriptionpayment/:sys_companySubscriptionPaymentId

Rest Request Parameters

The deleteCompanySubscriptionPayment api has got 1 regular request parameter

Parameter Type Required Population
sys_companySubscriptionPaymentId ID true request.params?.[“sys_companySubscriptionPaymentId”]
sys_companySubscriptionPaymentId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/companysubscriptionpayment/:sys_companySubscriptionPaymentId

  axios({
    method: 'DELETE',
    url: `/v1/companysubscriptionpayment/${sys_companySubscriptionPaymentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayment",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_companySubscriptionPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"companyId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Companysubscriptionpaymentbyorderid API

This route is used to get the payment information by order id.

Rest Route

The getCompanySubscriptionPaymentByOrderId API REST controller can be triggered via the following route:

/v1/companySubscriptionpaymentbyorderid/:orderId

Rest Request Parameters

The getCompanySubscriptionPaymentByOrderId api has got 1 regular request parameter

Parameter Type Required Population
orderId ID true request.params?.[“orderId”]
orderId : an ID value to represent the orderId which is the ID parameter of the source companySubscription object. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/companySubscriptionpaymentbyorderid/:orderId

  axios({
    method: 'GET',
    url: `/v1/companySubscriptionpaymentbyorderid/${orderId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_companySubscriptionPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Get Companysubscriptionpaymentbypaymentid API

This route is used to get the payment information by payment id.

Rest Route

The getCompanySubscriptionPaymentByPaymentId API REST controller can be triggered via the following route:

/v1/companySubscriptionpaymentbypaymentid/:paymentId

Rest Request Parameters

The getCompanySubscriptionPaymentByPaymentId api has got 1 regular request parameter

Parameter Type Required Population
paymentId String true request.params?.[“paymentId”]
paymentId : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/companySubscriptionpaymentbypaymentid/:paymentId

  axios({
    method: 'GET',
    url: `/v1/companySubscriptionpaymentbypaymentid/${paymentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_companySubscriptionPayment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_companySubscriptionPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Start Companysubscriptionpayment API

Start payment for companySubscription

Rest Route

The startCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/startcompanysubscriptionpayment/:companySubscriptionId

Rest Request Parameters

The startCompanySubscriptionPayment api has got 2 regular request parameters

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
paymentUserParams Object true request.body?.[“paymentUserParams”]
companySubscriptionId : This id paremeter is used to select the required data object that will be updated
paymentUserParams : The user parameters that should be defined to start a stripe payment process. Must include paymentMethodId.

REST Request To access the api you can use the REST controller with the path PATCH /v1/startcompanysubscriptionpayment/:companySubscriptionId

  axios({
    method: 'PATCH',
    url: `/v1/startcompanysubscriptionpayment/${companySubscriptionId}`,
    data: {
            paymentUserParams:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

Refresh Companysubscriptionpayment API

Refresh payment info for companySubscription from Stripe

Rest Route

The refreshCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/refreshcompanysubscriptionpayment/:companySubscriptionId

Rest Request Parameters

The refreshCompanySubscriptionPayment api has got 2 regular request parameters

Parameter Type Required Population
companySubscriptionId ID true request.params?.[“companySubscriptionId”]
paymentUserParams Object false request.body?.[“paymentUserParams”]
companySubscriptionId : This id paremeter is used to select the required data object that will be updated
paymentUserParams : The user parameters that should be defined to refresh a stripe payment process

REST Request To access the api you can use the REST controller with the path PATCH /v1/refreshcompanysubscriptionpayment/:companySubscriptionId

  axios({
    method: 'PATCH',
    url: `/v1/refreshcompanysubscriptionpayment/${companySubscriptionId}`,
    data: {
            paymentUserParams:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

Callback Companysubscriptionpayment API

Refresh payment values by gateway webhook call for companySubscription

Rest Route

The callbackCompanySubscriptionPayment API REST controller can be triggered via the following route:

/v1/callbackcompanysubscriptionpayment

Rest Request Parameters

The callbackCompanySubscriptionPayment api has got 2 regular request parameters

Parameter Type Required Population
companySubscriptionId ID false request.body?.[“companySubscriptionId”]
companyId String false request.body?.[“companyId”]
companySubscriptionId : The order id parameter that will be read from webhook callback params
companyId : The companyId parameter that will be read from webhook callback params metadata

REST Request To access the api you can use the REST controller with the path POST /v1/callbackcompanysubscriptionpayment

  axios({
    method: 'POST',
    url: '/v1/callbackcompanysubscriptionpayment',
    data: {
            companySubscriptionId:"ID",  
            companyId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "companySubscription",
	"method": "POST",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"companySubscription": {
		"id": "ID",
		"activationDate": "Date",
		"expiryDate": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"subscribedFeatures": "String",
		"lastRenewedBy": "ID",
		"currency": "String",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"paymentStatusUpdatedAt": "Date",
		"ownerId": "ID",
		"stripeSubscriptionId": "String",
		"amount": "Integer",
		"companyId": "ID",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

Get Paymentcustomerbyuserid API

This route is used to get the payment customer information by user id.

Rest Route

The getPaymentCustomerByUserId API REST controller can be triggered via the following route:

/v1/paymentcustomers/:userId

Rest Request Parameters

The getPaymentCustomerByUserId api has got 1 regular request parameter

Parameter Type Required Population
userId ID true request.params?.[“userId”]
userId : An ID value to represent the user who is created as a stripe customer. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/paymentcustomers/:userId

  axios({
    method: 'GET',
    url: `/v1/paymentcustomers/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_paymentCustomer",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_paymentCustomer": {
		"id": "ID",
		"userId": "ID",
		"customerId": "String",
		"platform": "String",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

List Paymentcustomers API

This route is used to list all payment customers.

Rest Route

The listPaymentCustomers API REST controller can be triggered via the following route:

/v1/paymentcustomers

Rest Request Parameters

Filter Parameters

The listPaymentCustomers api supports 3 optional filter parameters for filtering list results:

userId (ID): An ID value to represent the user who is created as a stripe customer

customerId (String): A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway

platform (String): A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future.

REST Request To access the api you can use the REST controller with the path GET /v1/paymentcustomers

  axios({
    method: 'GET',
    url: '/v1/paymentcustomers',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // customerId: '<value>' // Filter by customerId
        // platform: '<value>' // Filter by platform
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_paymentCustomers",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_paymentCustomers": [
		{
			"id": "ID",
			"userId": "ID",
			"customerId": "String",
			"platform": "String",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

List Paymentcustomermethods API

This route is used to list all payment customer methods.

Rest Route

The listPaymentCustomerMethods API REST controller can be triggered via the following route:

/v1/paymentcustomermethods/:userId

Rest Request Parameters

The listPaymentCustomerMethods api has got 1 regular request parameter

Parameter Type Required Population
userId ID true request.params?.[“userId”]
userId : An ID value to represent the user who owns the payment method. The parameter is used to query data.

Filter Parameters

The listPaymentCustomerMethods api supports 6 optional filter parameters for filtering list results:

paymentMethodId (String): A string value to represent the id of the payment method on the payment platform.

customerId (String): A string value to represent the customer id which is generated on the payment gateway.

cardHolderName (String): A string value to represent the name of the card holder. It can be different than the registered customer.

cardHolderZip (String): A string value to represent the zip code of the card holder. It is used for address verification in specific countries.

platform (String): A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future.

cardInfo (Object): A Json value to store the card details of the payment method.

REST Request To access the api you can use the REST controller with the path GET /v1/paymentcustomermethods/:userId

  axios({
    method: 'GET',
    url: `/v1/paymentcustomermethods/${userId}`,
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // paymentMethodId: '<value>' // Filter by paymentMethodId
        // customerId: '<value>' // Filter by customerId
        // cardHolderName: '<value>' // Filter by cardHolderName
        // cardHolderZip: '<value>' // Filter by cardHolderZip
        // platform: '<value>' // Filter by platform
        // cardInfo: '<value>' // Filter by cardInfo
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_paymentMethods",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_paymentMethods": [
		{
			"id": "ID",
			"paymentMethodId": "String",
			"userId": "ID",
			"customerId": "String",
			"cardHolderName": "String",
			"cardHolderZip": "String",
			"platform": "String",
			"cardInfo": "Object",
			"companyId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

workforceos-agenthub-service

Version: 1.0.0

AI Agent Hub

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the AgentHub Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our AgentHub Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the AgentHub Service via HTTP requests for purposes such as creating, updating, deleting and querying AgentHub objects.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST It’s important to note that the AgentHub Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Authentication And Authorization

To ensure secure access to the AgentHub service’s protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it’s important to note that access control varies across different routes:

Protected API: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected.

**Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token.

Token Locations

When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters.

Location Token Name / Param Name
Query access_token
Authorization Header Bearer
Header workforceos-access-token
Header workforceos-access-token-{companyCodename}
Cookie workforceos-access-token-{companyCodename}

Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies.

Api Definitions

This section outlines the API endpoints available within the AgentHub service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It’s important to understand the flexibility in how parameters can be included in requests to effectively interact with the AgentHub service.

This service is configured to listen for HTTP requests on port 3006, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

This service is accessible via the following environment-specific URLs:

Parameter Inclusion Methods: Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests:

Query Parameters: Included directly in the URL’s query string.

Path Parameters: Embedded within the URL’s path.

Body Parameters: Sent within the JSON body of the request.

Session Parameters: Automatically read from the session object. This method is used for parameters that are intrinsic to the user’s session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request.

Note on Session Parameters: Session parameters represent a unique method of parameter inclusion, relying on the context of the user’s session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request.

By adhering to the specified parameter inclusion methods, you can effectively utilize the AgentHub service’s API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below.

Common Parameters

The AgentHub service’s business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL.

Supported Common Parameters:

By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the AgentHub service.

Multi Tenant Architecture

The AgentHub service operates within a multi tenant architecture. The service is designed to support multiple tenants, each with its distinct data and configuration. This architecture ensures that data is securely isolated between tenants, preventing unauthorized access and maintaining data integrity. The service tenant is called company and identified as companyId. Other than platform users like superAdmin, saasAdmin and saasUser that belong to the root tenant, the tenant creators(owners) and users will all be associated with an company tenant. When users login their scope will be isolated only to include one tenant data they below. So user may acces only this logined tennat through out the session. After loging in to e specific tenant, users should include the tenant id in their request to access the tenant data. In each request they may access different tenant data if they belong them.

Key Points:

Implementation:

When the user logins there may be few ways for Mindbricks to recognize and set the tenant id in the session.

  1. Mindbricks will check the url of the login request if it matches tenant url.
  2. Mindbricks will check the `` has the tenant id.
  3. Mindbricks will check if the user is associated with a company in the data model. After you login a tenant successfully, ensure that your requests accurately target objects that fall within the tenant scope set during the login session. Ensure your requests are correctly formatted to include the domain sandbox information in the header. This enables the AgentHub service to accurately identify the domain context, facilitating proper access control and data management based on the user’s permissions and the specified domain.
axios({
  method: 'GET',
  headers: {
    '': 'Your-companyId-here'
  }
  url: "/someroutepath",
  data: {
    "someData":"someData"
  },
  params: {
    "aParam":"aParam"
  }
});

By adhering to this domain sandbox model, the AgentHub service maintains a secure and organized structure for handling requests across different domains, ensuring that operations are performed within the correct contextual boundaries.

Error Response

If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity:

Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Object Structure of a Successfull Response

When the AgentHub service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client.

Key Characteristics of the Response Envelope:

Design Considerations: The structure of a API’s response data is meticulously crafted during the service’s architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information.

Brief Data: Certain API’s return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect.

API Response Structure

The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response.

HTTP Status Codes:

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling the successful execution of the request. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

Handling Errors:

For details on handling error scenarios and understanding the structure of error responses, please refer to the “Error Response” section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages.

Resources

AgentHub service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service.

Sys_agentOverride resource

Resource Definition : Runtime overrides for design-time agents. Null fields use the design default. Sys_agentOverride Resource Properties

Name Type Required Default Definition
agentName String Design-time agent name this override applies to.
provider String Override AI provider (e.g., openai, anthropic).
model String Override model name.
systemPrompt Text Override system prompt.
temperature Double Override temperature (0-2).
maxTokens Integer Override max tokens.
responseFormat String Override response format (text/json).
selectedTools Object Array of tool names from the catalog that this agent can use.
guardrails Object Override guardrails: { maxToolCalls, timeout, maxTokenBudget }.
enabled Boolean Enable or disable this agent.
updatedBy ID User who last updated this override.

Sys_agentExecution resource

Resource Definition : Agent execution log. Records each agent invocation with input, output, and performance metrics. Sys_agentExecution Resource Properties

Name Type Required Default Definition
agentName String Agent that was executed.
agentType Enum Whether this was a design-time or dynamic agent.
source Enum How the agent was triggered.
userId ID User who triggered the execution.
input Object Request input (truncated for large payloads).
output Object Response output (truncated for large payloads).
toolCalls Integer Number of tool calls made during execution.
tokenUsage Object Token usage: { prompt, completion, total }.
durationMs Integer Execution time in milliseconds.
status Enum Execution status.
error Text Error message if execution failed.

Enum Properties

Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer.

agentType Enum Property

Property Definition : Whether this was a design-time or dynamic agent.Enum Options

Name Value Index
design "design"" 0
dynamic "dynamic"" 1
source Enum Property

Property Definition : How the agent was triggered.Enum Options

Name Value Index
rest "rest"" 0
sse "sse"" 1
kafka "kafka"" 2
agent "agent"" 3
status Enum Property

Property Definition : Execution status.Enum Options

Name Value Index
success "success"" 0
error "error"" 1
timeout "timeout"" 2

Sys_toolCatalog resource

Resource Definition : Cached tool catalog discovered from project services. Refreshed periodically. Sys_toolCatalog Resource Properties

Name Type Required Default Definition
toolName String Full tool name (e.g., service:apiName).
serviceName String Source service name.
description Text Tool description.
parameters Object JSON Schema of tool parameters.
lastRefreshed Date When this tool was last discovered/refreshed.

Business Api

Get Agentoverride API

[Default get API] — This is the designated default get API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride/:sys_agentOverrideId

Rest Request Parameters

The getAgentOverride api has got 1 regular request parameter

Parameter Type Required Population
sys_agentOverrideId ID true request.params?.[“sys_agentOverrideId”]
sys_agentOverrideId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/agentoverride/:sys_agentOverrideId

  axios({
    method: 'GET',
    url: `/v1/agentoverride/${sys_agentOverrideId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

List Agentoverrides API

[Default list API] — This is the designated default list API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listAgentOverrides API REST controller can be triggered via the following route:

/v1/agentoverrides

Rest Request Parameters The listAgentOverrides api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/agentoverrides

  axios({
    method: 'GET',
    url: '/v1/agentoverrides',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverrides",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_agentOverrides": [
		{
			"id": "ID",
			"agentName": "String",
			"provider": "String",
			"model": "String",
			"systemPrompt": "Text",
			"temperature": "Double",
			"maxTokens": "Integer",
			"responseFormat": "String",
			"selectedTools": "Object",
			"guardrails": "Object",
			"enabled": "Boolean",
			"updatedBy": "ID",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Update Agentoverride API

[Default update API] — This is the designated default update API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The updateAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride/:sys_agentOverrideId

Rest Request Parameters

The updateAgentOverride api has got 9 regular request parameters

Parameter Type Required Population
sys_agentOverrideId ID true request.params?.[“sys_agentOverrideId”]
provider String request.body?.[“provider”]
model String request.body?.[“model”]
systemPrompt Text request.body?.[“systemPrompt”]
temperature Double request.body?.[“temperature”]
maxTokens Integer request.body?.[“maxTokens”]
responseFormat String request.body?.[“responseFormat”]
selectedTools Object request.body?.[“selectedTools”]
guardrails Object request.body?.[“guardrails”]
sys_agentOverrideId : This id paremeter is used to select the required data object that will be updated
provider : Override AI provider (e.g., openai, anthropic).
model : Override model name.
systemPrompt : Override system prompt.
temperature : Override temperature (0-2).
maxTokens : Override max tokens.
responseFormat : Override response format (text/json).
selectedTools : Array of tool names from the catalog that this agent can use.
guardrails : Override guardrails: { maxToolCalls, timeout, maxTokenBudget }.

REST Request To access the api you can use the REST controller with the path PATCH /v1/agentoverride/:sys_agentOverrideId

  axios({
    method: 'PATCH',
    url: `/v1/agentoverride/${sys_agentOverrideId}`,
    data: {
            provider:"String",  
            model:"String",  
            systemPrompt:"Text",  
            temperature:"Double",  
            maxTokens:"Integer",  
            responseFormat:"String",  
            selectedTools:"Object",  
            guardrails:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

Create Agentoverride API

[Default create API] — This is the designated default create API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The createAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride

Rest Request Parameters

The createAgentOverride api has got 9 regular request parameters

Parameter Type Required Population
agentName String true request.body?.[“agentName”]
provider String false request.body?.[“provider”]
model String false request.body?.[“model”]
systemPrompt Text false request.body?.[“systemPrompt”]
temperature Double false request.body?.[“temperature”]
maxTokens Integer false request.body?.[“maxTokens”]
responseFormat String false request.body?.[“responseFormat”]
selectedTools Object false request.body?.[“selectedTools”]
guardrails Object false request.body?.[“guardrails”]
agentName : Design-time agent name this override applies to.
provider : Override AI provider (e.g., openai, anthropic).
model : Override model name.
systemPrompt : Override system prompt.
temperature : Override temperature (0-2).
maxTokens : Override max tokens.
responseFormat : Override response format (text/json).
selectedTools : Array of tool names from the catalog that this agent can use.
guardrails : Override guardrails: { maxToolCalls, timeout, maxTokenBudget }.

REST Request To access the api you can use the REST controller with the path POST /v1/agentoverride

  axios({
    method: 'POST',
    url: '/v1/agentoverride',
    data: {
            agentName:"String",  
            provider:"String",  
            model:"String",  
            systemPrompt:"Text",  
            temperature:"Double",  
            maxTokens:"Integer",  
            responseFormat:"String",  
            selectedTools:"Object",  
            guardrails:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

Delete Agentoverride API

[Default delete API] — This is the designated default delete API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The deleteAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride/:sys_agentOverrideId

Rest Request Parameters

The deleteAgentOverride api has got 1 regular request parameter

Parameter Type Required Population
sys_agentOverrideId ID true request.params?.[“sys_agentOverrideId”]
sys_agentOverrideId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/agentoverride/:sys_agentOverrideId

  axios({
    method: 'DELETE',
    url: `/v1/agentoverride/${sys_agentOverrideId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": false
	}
}

List Toolcatalog API

[Default list API] — This is the designated default list API for the sys_toolCatalog data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listToolCatalog API REST controller can be triggered via the following route:

/v1/toolcatalog

Rest Request Parameters

Filter Parameters

The listToolCatalog api supports 1 optional filter parameter for filtering list results:

serviceName (String): Source service name.

REST Request To access the api you can use the REST controller with the path GET /v1/toolcatalog

  axios({
    method: 'GET',
    url: '/v1/toolcatalog',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // serviceName: '<value>' // Filter by serviceName
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_toolCatalogs",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_toolCatalogs": [
		{
			"id": "ID",
			"toolName": "String",
			"serviceName": "String",
			"description": "Text",
			"parameters": "Object",
			"lastRefreshed": "Date",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Toolcatalogentry API

[Default get API] — This is the designated default get API for the sys_toolCatalog data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getToolCatalogEntry API REST controller can be triggered via the following route:

/v1/toolcatalogentry/:sys_toolCatalogId

Rest Request Parameters

The getToolCatalogEntry api has got 1 regular request parameter

Parameter Type Required Population
sys_toolCatalogId ID true request.params?.[“sys_toolCatalogId”]
sys_toolCatalogId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/toolcatalogentry/:sys_toolCatalogId

  axios({
    method: 'GET',
    url: `/v1/toolcatalogentry/${sys_toolCatalogId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_toolCatalog",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_toolCatalog": {
		"id": "ID",
		"toolName": "String",
		"serviceName": "String",
		"description": "Text",
		"parameters": "Object",
		"lastRefreshed": "Date",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

List Agentexecutions API

[Default list API] — This is the designated default list API for the sys_agentExecution data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listAgentExecutions API REST controller can be triggered via the following route:

/v1/agentexecutions

Rest Request Parameters

Filter Parameters

The listAgentExecutions api supports 5 optional filter parameters for filtering list results:

agentName (String): Agent that was executed.

agentType (Enum): Whether this was a design-time or dynamic agent.

source (Enum): How the agent was triggered.

userId (ID): User who triggered the execution.

status (Enum): Execution status.

REST Request To access the api you can use the REST controller with the path GET /v1/agentexecutions

  axios({
    method: 'GET',
    url: '/v1/agentexecutions',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // agentName: '<value>' // Filter by agentName
        // agentType: '<value>' // Filter by agentType
        // source: '<value>' // Filter by source
        // userId: '<value>' // Filter by userId
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentExecutions",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_agentExecutions": [
		{
			"id": "ID",
			"agentName": "String",
			"agentType": "Enum",
			"agentType_idx": "Integer",
			"source": "Enum",
			"source_idx": "Integer",
			"userId": "ID",
			"input": "Object",
			"output": "Object",
			"toolCalls": "Integer",
			"tokenUsage": "Object",
			"durationMs": "Integer",
			"status": "Enum",
			"status_idx": "Integer",
			"error": "Text",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Get Agentexecution API

[Default get API] — This is the designated default get API for the sys_agentExecution data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getAgentExecution API REST controller can be triggered via the following route:

/v1/agentexecution/:sys_agentExecutionId

Rest Request Parameters

The getAgentExecution api has got 1 regular request parameter

Parameter Type Required Population
sys_agentExecutionId ID true request.params?.[“sys_agentExecutionId”]
sys_agentExecutionId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/agentexecution/:sys_agentExecutionId

  axios({
    method: 'GET',
    url: `/v1/agentexecution/${sys_agentExecutionId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentExecution",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentExecution": {
		"id": "ID",
		"agentName": "String",
		"agentType": "Enum",
		"agentType_idx": "Integer",
		"source": "Enum",
		"source_idx": "Integer",
		"userId": "ID",
		"input": "Object",
		"output": "Object",
		"toolCalls": "Integer",
		"tokenUsage": "Object",
		"durationMs": "Integer",
		"status": "Enum",
		"status_idx": "Integer",
		"error": "Text",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

Authentication Specific Routes

Common Routes

Route: currentuser

Route Definition: Retrieves the currently authenticated user’s session information.

Route Type: sessionInfo

Access Route: GET /currentuser

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /currentuser call
axios.get("/currentuser", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response Returns the session object, including user-related data and token information.

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  ...
}

Error Response 401 Unauthorized: No active session found.

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Route: permissions

*Route Definition*: Retrieves all effective permission records assigned to the currently authenticated user.

*Route Type*: permissionFetch

Access Route: GET /permissions

Parameters

This route does not require any request parameters.

Behavior

// Sample GET /permissions call
axios.get("/permissions", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

Returns an array of permission objects.

[
  {
    "id": "perm1",
    "permissionName": "adminPanel.access",
    "roleId": "admin",
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  },
  {
    "id": "perm2",
    "permissionName": "orders.manage",
    "roleId": null,
    "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
    "subjectUserGroupId": null,
    "objectId": null,
    "canDo": true,
    "tenantCodename": "store123"
  }
]

Each object reflects a single permission grant, aligned with the givenPermissions model:

Error Responses

{
  "status": "ERR",
  "message": "No login found"
}

Notes

Tip: Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations.

Route: permissions/:permissionName

Route Definition: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions.

Route Type: permissionScopeCheck

Access Route: GET /permissions/:permissionName

Parameters

Parameter Type Required Population
permissionName String Yes request.params.permissionName

Behavior

// Sample GET /permissions/orders.manage
axios.get("/permissions/orders.manage", {
  headers: {
    "Authorization": "Bearer your-jwt-token"
  }
});

Success Response

{
  "canDo": true,
  "exceptions": [
    "a1f2e3d4-xxxx-yyyy-zzzz-object1",
    "b2c3d4e5-xxxx-yyyy-zzzz-object2"
  ]
}

Copyright

All sources, documents and other digital materials are copyright of .

About Us

For more information please visit our website: .

. .

REST API GUIDE

BFF SERVICE

Version: 1.0.21

BFF service is a microservice that acts as a bridge between the client and the backend services. It provides a unified API for the client to interact with multiple backend services, simplifying the communication process and improving performance.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to.
For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the BFF Service’s REST API. This document is designed to provide a comprehensive guide to interfacing with our BFF Service exclusively through RESTful API endpoints.

Intended Audience

This documentation is intended for developers and integrators who are looking to interact with the BFF Service via HTTP requests for purposes such as listing, filtering, and searching data.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST
It’s important to note that the BFF Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Resources

Elastic Index Resource

Resource Definition: A virtual resource representing dynamic search data from a specified index.

Route: List Records

Route Definition: Returns a paginated list from the elastic index. Route Type: list
Default access route: POST /:indexName/list

Parameters

Parameter Type Required Population
indexName String Yes path.param
page Number No query.page
limit Number No query.limit
sortBy String No query.sortBy
sortOrder String No query.sortOrder
q String No query.q
filters Object Yes body 
axios({
  method: "POST",
  url: `/${indexName}/list`,
  data: {
    filters: "Object"
  },
  params: {
    page: "Number",
    limit: "Number",
    sortBy: "String",
    sortOrder: "String",
    q: "String"
  }
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property.

---

Default access route: GET /:indexName/list

Parameters

Parameter Type Required Population
indexName String Yes path.param
page Number No query.page
limit Number No query.limit
sortBy String No query.sortBy
sortOrder String No query.sortOrder
q String No query.q 
axios({
  method: "GET",
  url: `/${indexName}/list`,
  data:{},
  params: {
    page: "Number",
    limit: "Number",
    sortBy: "String",
    sortOrder: "String",
    q: "String"
  }
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

Route: Count Records

Route Definition: Counts matching documents in the elastic index. Route Type: count
Default access route: POST /:indexName/count

Parameters

Parameter Type Required Population
indexName String Yes path.param
q String No query.q
filters Object Yes body 
axios({
  method: "POST",
  url: `/${indexName}/count`,
  data: {
    filters: "Object"
  },
  params: {
    q: "String"
  }
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

Default access route: GET /:indexName/count

Parameters

Parameter Type Required Population
indexName String Yes path.param
q String No query.q 
axios({
  method: "GET",
  url: `/${indexName}/count`,
  data:{},
  params: {
    q: "String"
  }
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

Route: Get Index Schema

Route Definition: Returns the schema for the elastic index. Route Type: get
Default access route: GET /:indexName/schema

Parameters

Parameter Type Required Population
indexName String Yes path.param 
axios({
  method: "GET",
  url: `/${indexName}/schema`,
  data:{},
  params: {}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

Route: Filters

GET /:indexName/filters

Route Type: get

Parameters

Parameter Type Required Population
indexName String Yes path.param
page Number No query.page
limit Number No query.limit 
axios({
  method: "GET",
  url: `/${indexName}/filters`,
  data:{},
  params: {
    page: "Number",
    limit: "Number"
  }
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

POST /:indexName/filters

Route Type: create

Parameters

Parameter Type Required Population
indexName String Yes path.param
filters Object Yes body 
axios({
  method: "POST",
  url: `/${indexName}/filters`,
  data: {
    filterName: "String",
    conditions: "Object"
  },
  params: {}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

DELETE /:indexName/filters/:filterId

Route Type: delete

Parameters

Parameter Type Required Population
indexName String Yes path.param
filterId String Yes path.param 
axios({
  method: "DELETE",
  url: `/${indexName}/filters/${filterId}`,
  data:{},
  params: {}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

Route: Get One Record

Route Type: get
Default access route: GET /:indexName/:id

Parameters

Parameter Type Required Population
indexName String Yes path.param
id ID Yes path.param 
axios({
  method: "GET",
  url: `/${indexName}/${id}`,
  data:{},
  params: {}

});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a “status”: “OK” property.

REST API GUIDE

NOTIFICATION SERVICE

Version: 1.0.7

The Notification service is a microservice that allows sending notifications through SMS, Email, and Push channels. Providers can be configured dynamically through the .env file.

Architectural Design Credit and Contact Information

The architectural design of this microservice is credited to.
For inquiries, feedback, or further information regarding the architecture, please direct your communication to:

Email:

We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice.

Documentation Scope

Welcome to the official documentation for the Notification Service REST API. This document provides a comprehensive overview of the available endpoints, how they work, and how to use them efficiently.

Intended Audience
This documentation is intended for developers, architects, and system administrators involved in the design, implementation, and maintenance of the Notification Service. It assumes familiarity with microservices architecture and RESTful APIs.

Overview

Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases.

Beyond REST
It’s important to note that the Notification Service also supports alternative methods of interaction, such as messaging via a Kafka message broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation.

Routes

Route: Register Device

Route Definition: Registers a device for a user.
Route Type: create
Default access route: POST /devices/register

Parameters

Parameter Type Required Population
device Object Yes body
userId ID Yes req.userId 
axios({
  method: "POST",
  url: `/devices/register`,
  data: {
    device:"Object"
  },
  params:{}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. Any validation errors will return status code 400 with an error message.

Route: Unregister Device

Route Definition: Removes a registered device.
Route Type: delete
Default access route: DELETE /devices/unregister/:deviceId

Parameters

Parameter Type Required Population
deviceId ID Yes path.param
userId ID Yes req.userId 
axios({
  method: "DELETE",
  url: `/devices/unregister/${deviceId}`,
  data:{},
  params:{}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. Any validation errors will return status code 400 with an error message.

Route: Get Notifications

Route Definition: Retrieves a paginated list of notifications.
Route Type: get
Default access route: GET /notifications

Parameters

Parameter Type Required Population
page Number No query.page
limit Number No query.limit
sortBy String No query.sortBy
userId ID Yes req.userId 
axios({
  method: "GET",
  url: `/notifications`,
  data:{},
  params: {
    page: "Number",
    limit: "Number",
    sortBy: "String"
  }
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. Any validation errors will return status code 400 with an error message.

Route: Send Notification

Route Definition: Sends a notification to specified recipients.
Route Type: create
Default access route: POST /notifications

Parameters

Parameter Type Required Population
notification Object Yes body 
axios({
  method: "POST",
  url: `/notifications`,
  data: {
    notification:"Object"
  },
  params:{}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. Any validation errors will return status code 400 with an error message.

Route: Mark Notifications as Seen

Route Definition: Marks selected notifications as seen.
Route Type: update
Default access route: POST /notifications/seen

Parameters

Parameter Type Required Population
notificationIds Array Yes body
userId ID Yes req.userId 
axios({
  method: "POST",
  url: `/notifications/seen`,
  data: {
    notificationIds:"Object"
  },
  params:{}
});

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. Any validation errors will return status code 400 with an error message.

Generated by Mindbricks Genesis Engine