MCP API Reference | FlowyTeam

Code	Meaning
`200`	Success
`401`	Unauthenticated — missing or invalid Bearer token
`403`	Forbidden — authenticated but lacks permission
`404`	Resource not found
`422`	Validation error — check the `errors` object in the response
`429`	Too many requests — rate limit exceeded
`500`	Server error

Auth Register

PUBLIC POST

Create a new FlowyTeam company account. Only call this tool when the user explicitly requests account creation and provides all required details. Requires MCP registration to be enabled by the platform administrator. Password is optional — if omitted, a secure temporary password is generated and included in the verification email. A verification email with a 6-digit code is sent — ask the user to share the code, then call auth_verify_email to activate the account and receive the api_token immediately. Alternatively the user can click the verification link in the email to activate via the browser, then copy the api_token from FlowyTeam Settings → MCP & AI Integration.

Parameters

Name	Type	Description
`name`	string	Full name of the admin user.
`email`	string	Email address. Used as login credential.
`password`	string	Optional. If omitted, a secure temporary password is generated and included in the verification email. The user can change it after first login.
`company_name`	string	Name of the company / organisation.
`phone`	string	Phone number (optional).

POST Auth Register

Request

{
    "name": "Alice Smith",
    "email": "[email protected]",
    "company_name": "Acme Corp"
}

Response

{
    "status": "pending_verification",
    "message": "Account created. A verification email has been sent to [email protected]. To activate, choose one of these options: (A) Check your email for the 6-digit verification code and paste it here. (B) Click the verification link in your email to activate via the browser.",
    "user_id": 42,
    "company_id": 7,
    "email": "[email protected]"
}

Auth Verify Email

PUBLIC POST

Activate a newly registered FlowyTeam account and receive the api_token. Call this after auth_register once the user shares the 6-digit code from their verification email. Also accepts the long token from the verification link URL as a fallback. On success, the account is activated and an api_token is returned — use it as the Bearer token and reconfigure the MCP connection.

Parameters

Name	Type	Description
`verification_code`	string	The 6-digit code from the verification email body, OR the long token from the verification link URL.

POST Auth Verify Email

Request

{
    "verification_code": "123456"
}

Response

{
    "status": "success",
    "message": "Email verified. Account is now active.",
    "api_token": "abc123...",
    "user_id": 42,
    "company_id": 7,
    "name": "Alice Smith",
    "email": "[email protected]"
}

Auth Login

PUBLIC POST

Retrieve the api_token for an existing FlowyTeam account using email and password. Only call this tool when the user explicitly provides their credentials and requests a login — never proactively. Note: for new accounts use auth_register + auth_verify_email instead. Existing users can also copy their token directly from FlowyTeam Settings → MCP & AI Integration. Returns an api_token — reconfigure the MCP connection with it as the Bearer token.

Parameters

Name	Type	Description
`email`	string	Registered email address.
`password`	string	Account password.

POST Auth Login

Request

{
    "email": "[email protected]",
    "password": "••••••••"
}

Response

{
    "status": "success",
    "message": "Login successful.",
    "api_token": "abc123...",
    "user_id": 42,
    "name": "Alice Smith"
}

Tasks

GET POST PUT DELETE

Manage tasks: list, create, update, delete, mark complete. Filter by status, priority, project, assignee, due date.

Parameters

Name	Type	Description
`id`	string	Task ID — or use "heading"/"title" to look up by name
`heading`	string	Task title (required for POST; also used to look up task by name for PUT/DELETE)
`title`	string	Alias for heading
`description`	string	—
`status`	string	Filter (GET) or new status (PUT)
`priority`	string	—
`project_id`	string	Project ID to link or filter by
`assigned_to`	string	User ID or name to assign to, or filter by (admin only for others)
`user_id`	string	Alias for assigned_to
`due_date`	string	Due date (Y-m-d)
`start_date`	string	Start date (Y-m-d). Defaults to today.
`task_category_id`	string	Task category ID
`search`	string	Search in task heading
`employee_access`	array	Array of user IDs to grant view/edit access to this task (in addition to creator and assignee).

GET Tasks

Request

{
    "status": "incomplete",
    "project_id": 12
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 101,
            "heading": "Design landing page",
            "status": "incomplete",
            "priority": "high",
            "due_date": "2026-05-01",
            "assigned_to": 7
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.
`403`	This action is unauthorized.

POST Tasks

Request

{
    "heading": "Write API docs",
    "project_id": 12,
    "due_date": "2026-05-10",
    "priority": "medium",
    "assigned_to": 7
}

Response

{
    "status": "success",
    "message": "Task created successfully.",
    "id": 102
}

Errors

HTTP Code	Message
`422`	The heading field is required.
`401`	Unauthenticated.

PUT Tasks

Request

{
    "id": 101,
    "status": "complete",
    "priority": "low"
}

Response

{
    "status": "success",
    "message": "Task updated successfully."
}

Errors

HTTP Code	Message
`404`	Task not found.
`422`	The id field is required.

DELETE Tasks

Request

{
    "id": 101
}

Response

{
    "status": "success",
    "message": "Task deleted successfully."
}

Errors

HTTP Code	Message
`404`	Task not found.

Projects

GET POST PUT DELETE

Manage projects and their sub-resources (milestones, members, categories, files). Set resource=project (default), milestone, member, category, or file. All lookups are name-based — no IDs needed. Admins have full access. Members can view/update their own projects, and perform full CRUD on milestones, members, and files.

Parameters

Name	Type	Description
`action`	string	Special action on the project resource. "duplicate" — clones an existing project (members + milestones + tasks all copied, tasks reset to incomplete). "stats" — returns project statistics: total count, by-status breakdown, overdue count, budget total. When action=duplicate: provide project_name to identify the project to clone. When action=stats: no extra params needed (use method=GET).
`resource`	string	Sub-resource to manage. Defaults to "project". Use "milestone" for milestones, "member" to add/remove members, "category" to manage categories (admin only for create/update/delete), "file" to list or delete project files.
`project_name`	string	Project name. Used as lookup key for GET (single), PUT, DELETE, and to scope milestones/members. Partial match.
`new_project_name`	string	New project name — only used when renaming a project via PUT.
`search`	string	Partial name search for list (GET) operations.
`status`	string	Project status. Defaults to "not started" on create.
`start_date`	string	Project start date (Y-m-d). Required for POST.
`deadline`	string	Project deadline (Y-m-d). Required for POST unless without_deadline=true.
`without_deadline`	boolean	Set true to create/update a project with no deadline.
`project_summary`	string	Short project description / summary.
`notes`	string	Internal project notes.
`feedback`	string	Client feedback field. Used on update only.
`client_name`	string	Client company or user name to assign to the project. Looked up by partial match.
`category_name`	string	The CURRENT/EXISTING category name — used as a lookup key (partial match). When assigning a project to a category, provide the existing category name here. When resource=category: PUT (rename) → provide the CURRENT name here and the NEW name in new_category_name. POST (create) → provide the new category name here. DELETE → provide the name of the category to delete here. NEVER put the new/desired name in this field for rename operations.
`new_category_name`	string	New category name — only used when renaming a category via PUT (resource=category).
`project_budget`	number	Project budget amount.
`hours_allocated`	number	Total hours budget allocated to this project.
`completion_percent`	integer	Manual completion percentage (0–100). Update only.
`client_view_task`	string	Allow client to view tasks.
`allow_client_notification`	string	Send client notifications for task updates. Only effective when client_view_task=enable.
`manual_timelog`	string	Allow manual time log entries on this project.
`milestone_title`	string	Milestone title. Required for POST (resource=milestone). Used as lookup key for PUT/DELETE.
`new_milestone_title`	string	New milestone title — only used when renaming a milestone via PUT.
`milestone_summary`	string	Milestone description/summary. Required for POST (resource=milestone).
`milestone_status`	string	Milestone completion status. Defaults to "incomplete" on create.
`milestone_cost`	number	Milestone cost amount. Defaults to 0.
`member_name`	string	Employee name to add or remove as a project member. Partial match.
`file_name`	string	Filename (partial match) for file operations (resource=file). Used for DELETE.
`filter_status`	string	Filter project list by status.
`filter_client`	string	Filter project list by client name (partial match).
`filter_category`	string	Filter project list by category name (partial match).

GET Projects

Request

{
    "status": "not started",
    "search": "website"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 12,
            "project_name": "Website Redesign",
            "status": "not started",
            "start_date": "2026-05-01",
            "deadline": "2026-07-31",
            "client_id": 3
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Projects

Request

{
    "project_name": "Mobile App v2",
    "start_date": "2026-06-01",
    "deadline": "2026-09-30",
    "client_id": 3
}

Response

{
    "status": "success",
    "message": "Project created successfully.",
    "id": 13
}

Errors

HTTP Code	Message
`422`	The project name field is required.

PUT Projects

Request

{
    "id": 12,
    "status": "in progress"
}

Response

{
    "status": "success",
    "message": "Project updated successfully."
}

Errors

HTTP Code	Message
`404`	Project not found.

DELETE Projects

Request

{
    "id": 12
}

Response

{
    "status": "success",
    "message": "Project deleted successfully."
}

Errors

HTTP Code	Message
`404`	Project not found.

Task Category

GET POST PUT DELETE

Manage task categories: list, create, update, delete. Lookup by ID or category name.

Parameters

Name	Type	Description
`id`	string	Category ID. For PUT/DELETE you may also supply category_name instead of id for name-based lookup.
`category_name`	string	Category name (required for POST; used as lookup key for PUT/DELETE when id is omitted).
`search`	string	Partial name search for GET.

GET Task Category

Request

{
    "search": "bug"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "category_name": "Bug Fix"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Task Category

Request

{
    "category_name": "Feature Request"
}

Response

{
    "status": "success",
    "message": "Category created successfully.",
    "id": 2
}

Errors

HTTP Code	Message
`422`	The category name field is required.

PUT Task Category

Request

{
    "id": 1,
    "category_name": "Critical Bug Fix"
}

Response

{
    "status": "success",
    "message": "Category updated successfully."
}

Errors

HTTP Code	Message
`404`	Category not found.

DELETE Task Category

Request

{
    "id": 1
}

Response

{
    "status": "success",
    "message": "Category deleted successfully."
}

Errors

HTTP Code	Message
`404`	Category not found.

Leave

GET POST PUT DELETE

Manage employee leave requests: list, create, approve, reject, cancel. Filter by status, employee, date range.

Parameters

Name	Type	Description
`id`	string	Leave ID — or use "name" + "leave_date" to look up by employee name and date instead
`name`	string	Employee name — used together with "leave_date" to look up a leave request without an id
`leave_type_id`	string	Leave type ID (use leave_type_name instead if you do not know the ID)
`leave_type_name`	string	Leave type name (e.g. "Annual Leave", "Sick Leave") — resolved to leave_type_id automatically
`employee_name`	string	Employee name — admin can set this to create a leave on behalf of that employee (resolved to user_id)
`user_id`	string	Employee user ID (admin only; use employee_name if ID is unknown)
`userId`	string	Filter by employee (GET)
`leave_date`	string	Leave start date (Y-m-d, required for POST; also used as a lookup key with "name")
`duration`	string	"full day", "half day", or "multiple"
`status`	string	—
`reason`	string	—
`multi_date`	string	Comma-separated dates for multiple duration
`startDate`	string	Filter from date (Y-m-d)
`endDate`	string	Filter to date (Y-m-d)
`sort_direction`	string	—
`per_page`	integer	—

GET Leave

Request

{
    "userId": 7,
    "status": "pending"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 88,
            "user_id": 7,
            "leave_type_id": 1,
            "leave_date": "2026-05-15",
            "duration": "full day",
            "status": "pending",
            "reason": "Family event"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Leave

Request

{
    "user_id": 7,
    "leave_type_id": 1,
    "leave_date": "2026-05-15",
    "duration": "full day",
    "reason": "Family event"
}

Response

{
    "status": "success",
    "message": "Leave request submitted.",
    "id": 89
}

Errors

HTTP Code	Message
`422`	The leave date field is required.

PUT Leave

Request

{
    "id": 88,
    "status": "approved"
}

Response

{
    "status": "success",
    "message": "Leave updated successfully."
}

Errors

HTTP Code	Message
`404`	Leave record not found.

DELETE Leave

Request

{
    "id": 88
}

Response

{
    "status": "success",
    "message": "Leave deleted successfully."
}

Errors

HTTP Code	Message
`404`	Leave record not found.

Leave Type

GET POST PUT DELETE

Manage leave types (annual, sick, etc.): list, create, update, delete. Admin-only for write operations.

Parameters

Name	Type	Description
`id`	string	Leave type ID — or use type_name to look up by name
`type_name`	string	Leave type name (e.g. Annual Leave, Sick Leave) — required for POST, or use to look up for PUT/DELETE
`color`	string	Color code (e.g. #FF0000)
`no_of_leaves`	number	Number of allowed leaves per year
`status`	string	Status of the leave type
`search`	string	Search by type name

GET Leave Type

Request

[]

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "type_name": "Annual Leave",
            "days": 14,
            "is_paid": true,
            "color": "#4CAF50"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Leave Type

Request

{
    "type_name": "Maternity Leave",
    "days": 90,
    "is_paid": true
}

Response

{
    "status": "success",
    "message": "Leave type 'Maternity Leave' created.",
    "data": {
        "id": 4,
        "type_name": "Maternity Leave",
        "days": 90
    }
}

Errors

HTTP Code	Message
`422`	The type name field is required.

PUT Leave Type

Request

{
    "type_name": "Annual Leave",
    "days": 16
}

Response

{
    "status": "success",
    "message": "Leave type 'Annual Leave' updated."
}

Errors

HTTP Code	Message
`404`	Leave type not found.

DELETE Leave Type

Request

{
    "id": "1"
}

Response

{
    "status": "success",
    "message": "Leave type 'Annual Leave' deleted."
}

Errors

HTTP Code	Message
`404`	Leave type not found.

Attendance

GET POST PUT

Manage attendance: clock-in, clock-out, list records. Filter by employee, date, month, year.

Parameters

Name	Type	Description
`method`	string	GET = list/view attendance records; POST = clock IN (start of shift, beginning of work day); PUT = clock OUT (end of shift, leaving work). Use PUT for any "clock out", "check out", or "end shift" request.
`id`	string	Attendance record ID — used on PUT to target a specific record directly (admin)
`employee_id`	string	User ID to filter (GET) or clock in/out for (admin only)
`employee_name`	string	Employee name to look up — admin only
`date`	string	Specific date filter Y-m-d (GET)
`month`	string	Month number 1-12 filter (GET)
`year`	string	Year e.g. 2026 filter (GET)
`today`	boolean \| string	If true, return only today's records (GET)
`clock_in_datetime`	string	Admin only: explicit clock-in datetime (Y-m-d H:i:s or H:i)
`clock_out_datetime`	string	Admin only: explicit clock-out datetime (Y-m-d H:i:s or H:i)
`working_from`	string	Where the employee is working from
`late`	string	Admin only: override late flag
`half_day`	string	Admin only: override half-day flag

GET Attendance

Request

{
    "today": true
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 300,
            "employee_id": 7,
            "date": "2026-05-07",
            "clock_in_time": "08:55:00",
            "clock_out_time": null,
            "working_from": "office"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Attendance

Request

{
    "employee_id": 7,
    "working_from": "office"
}

Response

{
    "status": "success",
    "message": "Clocked in successfully.",
    "id": 300
}

Errors

HTTP Code	Message
`422`	Already clocked in today.

PUT Attendance

Request

{
    "id": 300
}

Response

{
    "status": "success",
    "message": "Clocked out successfully."
}

Errors

HTTP Code	Message
`404`	Attendance record not found.

Employees

GET POST PUT DELETE

Manage employees: list, show full profile, create, update (profile/department/designation/status/skills), deactivate/delete. Always resolve by name or email — never require an ID from the user.

Parameters

Name	Type	Description
`name`	string	Employee full name (partial match). Used to look up for GET detail, PUT, DELETE.
`email`	string	Employee email (exact). Alternative lookup for PUT/DELETE.
`search`	string	Search employees by name or email (GET list).
`status`	string	Filter/set employee status. Use "active" for active employees, "deactive" for inactive/deactivated employees. The tool also accepts "inactive" or "deactivated" and normalizes them automatically.
`department_name`	string	Primary department name (partial match). Resolved to department_id.
`designation_name`	string	Designation/position name (partial match). Resolved to designation_id.
`with_details`	boolean	Include full profile details in GET. Default false (summary only).
`role`	string	Filter list by role name (partial match, e.g. "ticket manager", "admin", "employee"). Leave blank to show all employees.
`new_name`	string	Full name for new employee (POST) or rename existing (PUT).
`new_email`	string	Email for new employee (POST) or change email (PUT).
`password`	string	Password (POST/PUT). Default: Welcome@123.
`mobile`	string	Mobile / phone number.
`gender`	string	Gender.
`timezone`	string	User timezone (e.g. Asia/Jakarta, UTC, America/New_York). Stored on the user account.
`login`	string	Whether the employee can log in. Default enable.
`employee_id`	string	Custom employee/staff ID (e.g. EMP-001).
`preferred_name`	string	Preferred display name.
`joining_date`	string	Joining date (Y-m-d or natural language like "today").
`last_date`	string	Last working date (Y-m-d). Set when offboarding.
`birthday`	string	Date of birth (Y-m-d).
`address`	string	Home address.
`hourly_rate`	string	Hourly rate (numeric).
`slack_username`	string	Slack username.
`manager`	string	Whether this employee is a manager.
`marital_status`	string	Marital status.
`nationality`	string	Nationality (e.g. Indonesia, Malaysian, Filipino).
`location`	string	Work location / branch.
`employment_type`	string	Employment type (e.g. full-time, part-time, contract).
`attendance`	string	Attendance tracking mode. "active" = tracking enabled, "deactive" = disabled.
`subsidiary`	string	Subsidiary / branch name.
`highest_qualification`	string	Highest educational qualification.
`show_organizational_chart`	string	Show in org chart.
`nric`	string	National ID / NRIC number.
`passport`	string	Passport number.
`resident`	string	Residency status.
`work_permit_no`	string	Work permit number.
`work_permit_expiry_date`	string	Work permit expiry date (Y-m-d).
`amount_of_children`	string	Number of children.
`spouse_working`	string	Whether spouse is working.
`disabled_person`	string	Employee is a disabled person.
`disabled_spouse`	string	Spouse is a disabled person.
`disabled_children`	string	Has disabled children.
`next_of_kin_full_name`	string	Next of kin full name.
`next_of_kin_phone_number`	string	Next of kin phone number.
`next_of_kin_relationship`	string	Relationship to next of kin (e.g. spouse, parent).
`salary`	string	Salary amount (numeric).
`salary_type`	string	Salary type.
`salary_currency`	string	Currency code for salary (e.g. IDR, MYR, USD).
`payment_method`	string	Payment method (e.g. bank transfer, cash).
`bank_name`	string	Bank name.
`bank_account_no`	string	Bank account number.
`bank_account_name`	string	Bank account holder name.
`bank_account_type`	string	Bank account type (e.g. savings, current).
`employee_type_name`	string	Employee type name (partial match, e.g. Full Time, Part Time, Intern). Resolved to employee_type_id.
`reports_to_name`	string	Manager/supervisor name (partial match). Resolved to reports_to field.
`skills`	string	Comma-separated skill names to assign (replaces existing).
`reports_to_since`	string	Date since employee reports to current manager (Y-m-d).
`employment_status_effective_from`	string	Employment status effective from date (Y-m-d).
`employment_status_effective_to`	string	Employment status effective to date (Y-m-d).

GET Employees

Request

{
    "department_id": 4,
    "status": "active"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 7,
            "name": "Sarah Lee",
            "email": "[email protected]",
            "department_id": 4,
            "designation_id": 2,
            "status": "active",
            "joining_date": "2024-01-15"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Employees

Request

{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "secret123",
    "department_id": 4,
    "designation_id": 2,
    "joining_date": "2026-06-01"
}

Response

{
    "status": "success",
    "message": "Employee created successfully.",
    "id": 8
}

Errors

HTTP Code	Message
`422`	The email has already been taken.

PUT Employees

Request

{
    "id": 7,
    "status": "inactive"
}

Response

{
    "status": "success",
    "message": "Employee updated successfully."
}

Errors

HTTP Code	Message
`404`	Employee not found.

DELETE Employees

Request

{
    "id": 7
}

Response

{
    "status": "success",
    "message": "Employee deleted successfully."
}

Errors

HTTP Code	Message
`404`	Employee not found.

Department

GET POST PUT DELETE

Manage departments/teams: list, show details with members, create, update, delete, add/remove members. Always resolve by name — never require an ID from the user.

Parameters

Name	Type	Description
`name`	string	Department name (partial match for lookup on GET/PUT/DELETE). Never ask the user for an ID — use this.
`team_name`	string	Alias for name. New name when creating/renaming.
`new_name`	string	New department name when renaming an existing department (PUT).
`description`	string	Department description.
`parent_name`	string	Parent department name (partial match). Used for hierarchical setup.
`leader_name`	string	Full name of the department leader/manager (partial match on employee name).
`action`	string	Member action: "add_member", "remove_member", "add_associate", "remove_associate". Use with employee_name.
`employee_name`	string	Employee full name (partial match) for member actions.
`search`	string	Search departments by name (GET).
`with_members`	boolean	Include members list in GET response. Default false.

GET Department

Request

{
    "search": "marketing"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 4,
            "team_name": "Digital Marketing",
            "name": "Digital Marketing",
            "description": "Handles all digital channels",
            "parent_id": null
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Department

Request

{
    "team_name": "Product Design",
    "description": "UI\/UX and product design team"
}

Response

{
    "status": "success",
    "message": "Department created successfully.",
    "id": 5
}

Errors

HTTP Code	Message
`422`	The team name field is required.

PUT Department

Request

{
    "id": 4,
    "team_name": "Digital Marketing & SEO"
}

Response

{
    "status": "success",
    "message": "Department updated successfully."
}

Errors

HTTP Code	Message
`404`	Department not found.

DELETE Department

Request

{
    "id": 4
}

Response

{
    "status": "success",
    "message": "Department deleted successfully."
}

Errors

HTTP Code	Message
`404`	Department not found.

Designation

GET POST PUT DELETE

Manage job designations/positions: list (with member counts), create, update, delete. Always resolve by name — never require an ID from the user.

Parameters

Name	Type	Description
`name`	string	Designation name for lookup (partial match). Used for GET detail, PUT, DELETE. Never ask the user for an ID.
`search`	string	Partial name search for GET list.
`new_name`	string	New designation name when renaming an existing one (PUT). Use `name` to identify which designation to rename.
`description`	string	Optional description of the designation/position.
`with_members`	boolean	Include list of members holding this designation in GET response. Default false.

GET Designation

Request

{
    "search": "engineer"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 2,
            "name": "Senior Software Engineer"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Designation

Request

{
    "name": "DevOps Engineer"
}

Response

{
    "status": "success",
    "message": "Designation created successfully.",
    "id": 3
}

Errors

HTTP Code	Message
`422`	The name field is required.

PUT Designation

Request

{
    "id": 2,
    "name": "Principal Software Engineer"
}

Response

{
    "status": "success",
    "message": "Designation updated successfully."
}

Errors

HTTP Code	Message
`404`	Designation not found.

DELETE Designation

Request

{
    "id": 2
}

Response

{
    "status": "success",
    "message": "Designation deleted successfully."
}

Errors

HTTP Code	Message
`404`	Designation not found.

Clients

GET POST PUT DELETE

Manage clients: list, create, update, delete. Filter by name, company.

Parameters

Name	Type	Description
`id`	string	Client user ID — or use "company_name" or "name" to look up by name instead
`search`	string	Search by name or company
`company_name`	string	Company name (also used to look up client for PUT/DELETE)
`name`	string	Contact person name (also used to look up client for PUT/DELETE)
`email`	string	—
`mobile`	string	—
`website`	string	—
`address`	string	—
`note`	string	—

GET Clients

Request

{
    "search": "acme"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 3,
            "name": "Bob Smith",
            "company_name": "Acme Corp",
            "email": "[email protected]",
            "mobile": "+1234567890",
            "website": "https:\/\/acme.com"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Clients

Request

{
    "name": "Alice Johnson",
    "email": "[email protected]",
    "company_name": "New Client Ltd",
    "mobile": "+0987654321",
    "send_email": "yes"
}

Response

{
    "status": "success",
    "message": "Client created successfully.",
    "id": 4
}

Errors

HTTP Code	Message
`422`	The email has already been taken.

PUT Clients

Request

{
    "id": 3,
    "website": "https:\/\/acme-new.com"
}

Response

{
    "status": "success",
    "message": "Client updated successfully."
}

Errors

HTTP Code	Message
`404`	Client not found.

DELETE Clients

Request

{
    "id": 3
}

Response

{
    "status": "success",
    "message": "Client deleted successfully."
}

Errors

HTTP Code	Message
`404`	Client not found.

Tickets

GET POST PUT DELETE

Manage support tickets and their conversation replies. Supports full CRUD (list, create, update, delete), reply/conversation management (resource=reply), ticket statistics (action=stats), and close/reopen actions. Name-based lookups for agent, requester, type, and channel. Admins and privileged members have full access. Regular members can manage their own tickets (create, view, reply, close, reopen).

Parameters

Name	Type	Description
`resource`	string	Sub-resource to manage. Defaults to "ticket". Use "reply" to list (GET) or add (POST) replies to a ticket conversation.
`action`	string	Special action on a ticket. "close" — set status to closed and add a system reply. Provide id or subject to identify the ticket. "reopen" — reopen a closed ticket (open if no agent, pending if agent assigned). "stats" — return ticket counts by status (open, pending, resolved, closed, total). No other params needed.
`id`	string	Ticket ID (numeric). Preferred for PUT/DELETE/reply to pinpoint a specific ticket.
`subject`	string	Ticket subject. Required for POST (create ticket). Also used as a partial-match fallback lookup when id is not provided (PUT/DELETE).
`search`	string	Search/filter ticket list by subject substring (GET only).
`description`	string	Ticket body — the initial message. Required for POST (create). Stored as the first reply in the conversation thread (not on the ticket record itself).
`message`	string	Reply text to append to the ticket conversation. Use on PUT (update) to add a reply while also updating other fields. Use with resource=reply, method=POST to add a standalone reply.
`status`	string	Ticket status. Defaults to "open" on create. Prefer action=close / action=reopen for status transitions.
`priority`	string	Ticket priority. Defaults to "medium" on create.
`due_date`	string	Expected resolution date (Y-m-d). Admin/privileged members only.
`tags`	string	Comma-separated tags to attach to the ticket (e.g. "billing,urgent,vip"). Replaces existing tags. Admin/privileged members only.
`agent_name`	string	Name of the support agent to assign (partial match). Resolved to agent_id automatically. When agent is reassigned, they are notified. Admin/privileged members only.
`requester_name`	string	Name of the ticket requester/submitter (partial match). Resolved to user_id. Admin/privileged use only — creates ticket on behalf of that user.
`type_name`	string	Ticket type name (partial match, e.g. "bug", "feature request"). Resolved to type_id automatically.
`channel_name`	string	Ticket channel name (partial match, e.g. "email", "chat", "phone"). Resolved to channel_id automatically.
`filter_status`	string	Filter ticket list by status (GET only).
`filter_priority`	string	Filter ticket list by priority (GET only).
`filter_agent`	string	Filter ticket list by agent name (partial match, GET only).
`filter_requester`	string	Filter ticket list by requester/submitter name (partial match, GET only, admin only).

GET Tickets

Request

{
    "status": "open",
    "priority": "high"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 500,
            "subject": "Login not working",
            "status": "open",
            "priority": "high",
            "agent_id": 7,
            "type_id": 1,
            "channel_id": 2
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Tickets

Request

{
    "subject": "Cannot export report",
    "description": "Export button not responding",
    "priority": "medium",
    "type_id": 1,
    "channel_id": 2,
    "user_id": 7
}

Response

{
    "status": "success",
    "message": "Ticket created successfully.",
    "id": 501
}

Errors

HTTP Code	Message
`422`	The subject field is required.

PUT Tickets

Request

{
    "id": 500,
    "status": "resolved",
    "agent_id": 8
}

Response

{
    "status": "success",
    "message": "Ticket updated successfully."
}

Errors

HTTP Code	Message
`404`	Ticket not found.

DELETE Tickets

Request

{
    "id": 500
}

Response

{
    "status": "success",
    "message": "Ticket deleted successfully."
}

Errors

HTTP Code	Message
`404`	Ticket not found.

Ticket Type

GET POST PUT DELETE

Manage ticket types/classifications: list, create, update, delete. Lookup by name or ID.

Parameters

Name	Type	Description
`id`	string	Ticket type ID. For PUT/DELETE you may also supply `type` or `name` to look up by name instead.
`type`	string	Ticket type name (required for POST; used as name-based lookup key for PUT/DELETE when id is omitted).
`name`	string	Alias for `type`. Used as name-based lookup key for PUT/DELETE when id is omitted.
`search`	string	Search ticket types by name (GET).

GET Ticket Type

Request

{
    "search": "bug"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "type": "Bug Report"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Ticket Type

Request

{
    "type": "Feature Request"
}

Response

{
    "status": "success",
    "message": "Ticket type created successfully.",
    "id": 2
}

Errors

HTTP Code	Message
`422`	The type field is required.

PUT Ticket Type

Request

{
    "id": 1,
    "type": "Critical Bug"
}

Response

{
    "status": "success",
    "message": "Ticket type updated successfully."
}

Errors

HTTP Code	Message
`404`	Ticket type not found.

DELETE Ticket Type

Request

{
    "id": 1
}

Response

{
    "status": "success",
    "message": "Ticket type deleted successfully."
}

Errors

HTTP Code	Message
`404`	Ticket type not found.

Ticket Channel

GET POST PUT DELETE

Manage ticket channels (e.g. email, phone, chat): list, create, update, delete. Requires the tickets module.

Parameters

Name	Type	Description
`id`	string	Channel ID. For PUT/DELETE you may supply id OR channel_name/name instead.
`channel_name`	string	Channel name (required for POST; used as lookup key for PUT/DELETE when id is omitted).
`name`	string	Alias for channel_name — can be used as a lookup key for PUT/DELETE.
`search`	string	Search substring within channel_name.

GET Ticket Channel

Request

[]

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "channel_name": "Email"
        },
        {
            "id": 2,
            "channel_name": "Live Chat"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Ticket Channel

Request

{
    "channel_name": "WhatsApp"
}

Response

{
    "status": "success",
    "message": "Channel created successfully.",
    "id": 3
}

Errors

HTTP Code	Message
`422`	The channel name field is required.

PUT Ticket Channel

Request

{
    "id": 1,
    "channel_name": "Email Support"
}

Response

{
    "status": "success",
    "message": "Channel updated successfully."
}

Errors

HTTP Code	Message
`404`	Channel not found.

DELETE Ticket Channel

Request

{
    "id": 1
}

Response

{
    "status": "success",
    "message": "Channel deleted successfully."
}

Errors

HTTP Code	Message
`404`	Channel not found.

Ticket Agent

GET

List ticket agents and their assigned groups.

GET Ticket Agent

Request

[]

Response

{
    "status": "success",
    "data": [
        {
            "id": 7,
            "name": "Sarah Lee",
            "email": "[email protected]",
            "group": "Technical Support"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

Objectives

GET POST PUT DELETE

Manage OKR objectives: list, create, update, delete. Filter by cycle, type (company/team/personal), status.

Parameters

Name	Type	Description
`id`	string	Objective ID. For PUT/DELETE you may omit and supply title for name-based lookup.
`title`	string	Objective title (required for POST; used as lookup key for PUT/DELETE when id omitted).
`description`	string	—
`objective_type`	string	"company", "team", or "personal". Defaults to "personal" for members, "company" for admins.
`cycle_id`	string	Performance cycle ID. Uses active cycle if omitted.
`cycle_name`	string	Filter by cycle name (partial match). Used when cycle_id is unknown.
`team_id`	string	Team/department ID. Use to filter team objectives by exact ID.
`team_name`	string	Team/department name (partial match). Used when team_id is unknown.
`employee_id`	string	EmployeeDetails ID. Use to filter personal objectives by exact ID.
`employee_name`	string	Employee full name (partial match). Used when employee_id is unknown.
`started_at`	string	Start date (Y-m-d). Uses cycle start if omitted.
`finished_at`	string	End date (Y-m-d). Uses cycle end if omitted.
`weight`	string	Objective weight 1-100. Default 1.
`confidence`	string	Confidence score 0-10. Default 0.
`search`	string	Search in objective title.

GET Objectives

Request

{
    "cycle_id": 3,
    "level": "company"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 20,
            "heading": "Grow ARR by 40%",
            "level": "company",
            "status": "on track",
            "cycle_id": 3,
            "description": "Increase annual recurring revenue"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Objectives

Request

{
    "heading": "Improve NPS Score",
    "level": "company",
    "cycle_id": 3,
    "type": "qualitative"
}

Response

{
    "status": "success",
    "message": "Objective created successfully.",
    "id": 21
}

Errors

HTTP Code	Message
`422`	The heading field is required.

PUT Objectives

Request

{
    "id": 20,
    "status": "at risk"
}

Response

{
    "status": "success",
    "message": "Objective updated successfully."
}

Errors

HTTP Code	Message
`404`	Objective not found.

DELETE Objectives

Request

{
    "id": 20
}

Response

{
    "status": "success",
    "message": "Objective deleted successfully."
}

Errors

HTTP Code	Message
`404`	Objective not found.

Key Result

GET POST PUT DELETE

Manage OKR key results: list, create, update, delete, update progress. Link to objectives.

Parameters

Name	Type	Description
`id`	string	Key result ID for PUT/DELETE. If omitted, lookup is attempted by title.
`objective_id`	string	Parent objective ID. Use this when you know the exact ID, otherwise use objective_title + context filters.
`objective_title`	string	Parent objective title (partial match). Combine with team_name or employee_name to narrow down.
`objective_type`	string	Objective owner type: "company", "team", or "personal". Helps narrow lookup.
`team_name`	string	Team name (partial match). Used to find the objective when objective_type=team.
`employee_name`	string	Employee full name (partial match). Used to find the objective when objective_type=personal.
`cycle_name`	string	Performance cycle name (partial match, e.g. "Q2 2026"). Used to narrow objective lookup.
`cycle_id`	string	Performance cycle ID. Alternative to cycle_name.
`title`	string	Key result title (required for POST, used as name-based lookup for PUT/DELETE)
`description`	string	—
`initial_value`	string	Start value. Default 0.
`target_value`	string	Target value. Default 100.
`current_value`	string	Current progress value. Default equals initial_value.
`weight`	string	Weight 1–100. Default 100.
`unit_value`	string	Unit label (e.g. %, $, units). Default: %.
`confidence`	string	Confidence level 0–10.
`leader_id`	string	EmployeeDetails ID of the key result owner.
`remarks`	string	Check-in remarks / notes for this update.

GET Key Result

Request

{
    "objective_id": 20
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 30,
            "krs_title": "Sign 50 new enterprise clients",
            "krs_init": 0,
            "krs_tar": 50,
            "krs_now": 18,
            "krs_weight": 100,
            "krs_unit": "%",
            "objective_id": 20
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Key Result

Request

{
    "krs_owner": 20,
    "krs_title": "Reduce churn to < 5%",
    "krs_init": 8,
    "krs_tar": 5,
    "krs_now": 8,
    "krs_weight": 100,
    "krs_unit": "%"
}

Response

{
    "status": "success",
    "message": "Key result created successfully.",
    "id": 31
}

Errors

HTTP Code	Message
`422`	The krs owner field is required.

PUT Key Result

Request

{
    "id": 30,
    "krs_now": 24
}

Response

{
    "status": "success",
    "message": "Key result updated successfully."
}

Errors

HTTP Code	Message
`404`	Key result not found.

DELETE Key Result

Request

{
    "id": 30
}

Response

{
    "status": "success",
    "message": "Key result deleted successfully."
}

Errors

HTTP Code	Message
`404`	Key result not found.

Indicators

GET POST PUT DELETE

Manage KPI indicators: list, create, update, delete. Filter by category, employee. Lookup by title or ID.

Parameters

Name	Type	Description
`id`	string	Indicator ID. For PUT/DELETE, name-based lookup also supported via `title`.
`title`	string	Indicator title (required for POST; used for name-based lookup on PUT/DELETE)
`category_id`	string	Indicator type/category ID (use category_name if ID unknown)
`category_name`	string	Indicator category name — resolved to category_id automatically
`employee_id`	string	Employee user ID to filter or assign (use employee_name if ID unknown)
`employee_name`	string	Employee name — resolved to employee_id automatically for filter or assign
`target_value`	number \| string	Target value for the indicator
`unit_value`	string	Unit of measurement (e.g. %, $, units)
`occurance`	string	"daily", "weekly", "monthly", "quarterly", or "yearly"
`description`	string	Description or notes for the indicator
`search`	string	Search indicators by title

GET Indicators

Request

{
    "employee_id": 7,
    "frequency": "monthly"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 40,
            "name": "Monthly Sales Revenue",
            "target": 100000,
            "unit": "USD",
            "frequency": "monthly",
            "employee_id": 7,
            "category_id": 2
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Indicators

Request

{
    "name": "Customer Satisfaction Score",
    "target": 90,
    "unit": "%",
    "frequency": "monthly",
    "employee_id": 7,
    "category_id": 2
}

Response

{
    "status": "success",
    "message": "KPI created successfully.",
    "id": 41
}

Errors

HTTP Code	Message
`422`	The name field is required.

PUT Indicators

Request

{
    "id": 40,
    "target": 120000
}

Response

{
    "status": "success",
    "message": "KPI updated successfully."
}

Errors

HTTP Code	Message
`404`	KPI not found.

DELETE Indicators

Request

{
    "id": 40
}

Response

{
    "status": "success",
    "message": "KPI deleted successfully."
}

Errors

HTTP Code	Message
`404`	KPI not found.

Indicator Category

GET POST PUT DELETE

Manage KPI indicator categories/types: list, create, update, delete. Lookup by name or ID.

Parameters

Name	Type	Description
`id`	string	Category ID for PUT/DELETE. If omitted, lookup falls back to indicator_type_name or name.
`indicator_type_name`	string	Category name (required for POST; used as name-based lookup key for PUT/DELETE).
`name`	string	Alias for indicator_type_name. Can be used for lookup in PUT/DELETE.
`search`	string	Partial name search for GET.
`status`	string	Optional status filter.

GET Indicator Category

Request

{
    "all": true
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "indicator_type_name": "Sales"
        },
        {
            "id": 2,
            "indicator_type_name": "Customer Success"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Indicator Category

Request

{
    "indicator_type_name": "Engineering"
}

Response

{
    "status": "success",
    "message": "Category created successfully.",
    "id": 3
}

Errors

HTTP Code	Message
`422`	The indicator type name field is required.

PUT Indicator Category

Request

{
    "id": 1,
    "indicator_type_name": "Revenue & Sales"
}

Response

{
    "status": "success",
    "message": "Category updated successfully."
}

Errors

HTTP Code	Message
`404`	Category not found.

DELETE Indicator Category

Request

{
    "id": 1
}

Response

{
    "status": "success",
    "message": "Category deleted successfully."
}

Errors

HTTP Code	Message
`404`	Category not found.

Indicator Record

GET POST DELETE

Manage KPI indicator records (actual values per period): list, add, delete. Lookup by indicator_id + period_key.

Parameters

Name	Type	Description
`id`	string	Record ID (for single GET or DELETE)
`indicator_id`	string	KPI indicator ID (required for GET list and POST)
`period_key`	string	Period date in Y-m-d format (required for POST; used with indicator_id as unique lookup key)
`current_value`	number \| string	Actual value for the period
`target_value`	number \| string	Target value for the period
`remark`	string	Optional remark / notes for the record
`updated_by`	string	User ID of who updated this record
`start_date`	string	Filter records from this date (Y-m-d)
`end_date`	string	Filter records to this date (Y-m-d)
`month`	string	Filter by month number (1-12)
`year`	string	Filter by 4-digit year

GET Indicator Record

Request

{
    "indicator_id": 40,
    "month": 5,
    "year": 2026
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 200,
            "indicator_id": 40,
            "period_key": "01-5-2026",
            "current_value": 95000,
            "target_value": 100000,
            "score": 95,
            "remark": "On track"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Indicator Record

Request

{
    "indicator_id": 40,
    "period_key": "01-6-2026",
    "current_value": 112000,
    "target_value": 100000,
    "remark": "Exceeded target"
}

Response

{
    "status": "success",
    "message": "Record updated successfully."
}

Errors

HTTP Code	Message
`422`	The indicator id field is required.

DELETE Indicator Record

Request

{
    "id": 200
}

Response

{
    "status": "success",
    "message": "Record deleted successfully."
}

Errors

HTTP Code	Message
`404`	Record not found.

Performance Cycle

GET POST PUT DELETE

Manage OKR performance cycles: list, create, update, delete. Lookup by name or ID.

Parameters

Name	Type	Description
`id`	string	Cycle ID for PUT/DELETE. If omitted, lookup is attempted by name.
`name`	string	Cycle name (required for POST; used as fallback lookup key for PUT/DELETE).
`cycle_type`	string	Cycle type (e.g. quarterly, annual, monthly).
`started_at`	string	Start date (Y-m-d).
`finished_at`	string	End date (Y-m-d).
`search`	string	Search cycles by name (GET).
`show_employee_status`	boolean	When true (GET), returns performance review status for all employees instead of listing cycles. Use cycle_id to filter by a specific cycle.
`cycle_id`	string	Filter employee performance status by this cycle ID (used with show_employee_status).

GET Performance Cycle

Request

{
    "per_page": 10,
    "page": 1
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 3,
            "name": "Q2 2026",
            "cycle_type": "quarterly",
            "started_at": "2026-04-01",
            "finished_at": "2026-06-30"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Performance Cycle

Request

{
    "name": "Q3 2026",
    "cycle_type": "quarterly",
    "started_at": "2026-07-01",
    "finished_at": "2026-09-30"
}

Response

{
    "status": "success",
    "message": "Performance cycle created successfully.",
    "id": 4
}

Errors

HTTP Code	Message
`422`	The name field is required.

PUT Performance Cycle

Request

{
    "id": 3,
    "name": "Q2 2026 Updated"
}

Response

{
    "status": "success",
    "message": "Cycle updated successfully."
}

Errors

HTTP Code	Message
`404`	Cycle not found.

DELETE Performance Cycle

Request

{
    "id": 3
}

Response

{
    "status": "success",
    "message": "Cycle deleted successfully."
}

Errors

HTTP Code	Message
`404`	Cycle not found.

Holiday

GET POST PUT DELETE

Manage company holidays: list, create, update, delete. Filter by year, upcoming/past. Lookup by ID or holiday name.

Parameters

Name	Type	Description
`id`	string	Holiday ID. For PUT/DELETE you may also use `occassion` or `name` for name-based lookup instead.
`occassion`	string	Holiday occasion/name (required for POST; used as name-based lookup key for PUT/DELETE).
`name`	string	Alias for `occassion`. Used for name-based lookup on PUT/DELETE.
`date`	string	Holiday date in Y-m-d format (required for POST; optional for PUT).
`year`	string	Filter list results by year (GET only).
`status`	string	"upcoming" returns holidays on or after today; "past" returns holidays before today (GET only).
`search`	string	Partial name search against the occasion field (GET only).

GET Holiday

Request

{
    "year": 2026,
    "status": "upcoming"
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 10,
            "occasion": "Independence Day",
            "date": "17\/08\/2026"
        },
        {
            "id": 11,
            "occasion": "Christmas Day",
            "date": "25\/12\/2026"
        }
    ]
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Holiday

Request

{
    "occasion": "New Year's Day",
    "date": "01\/01\/2027"
}

Response

{
    "status": "success",
    "message": "Holiday created successfully.",
    "id": 12
}

Errors

HTTP Code	Message
`422`	The date field is required.

PUT Holiday

Request

{
    "id": 10,
    "occasion": "National Independence Day"
}

Response

{
    "status": "success",
    "message": "Holiday updated successfully."
}

Errors

HTTP Code	Message
`404`	Holiday not found.

DELETE Holiday

Request

{
    "id": 10
}

Response

{
    "status": "success",
    "message": "Holiday deleted successfully."
}

Errors

HTTP Code	Message
`404`	Holiday not found.

Leads

GET POST PUT DELETE

Manage sales leads: list, create, update, delete. Filter by status, agent, date range.

Parameters

Name	Type	Description
`id`	string	Lead ID — or use "client_name" to look up by name instead
`client_name`	string	Lead contact name (required for POST; also used to look up lead for PUT/DELETE)
`company_name`	string	—
`email`	string	—
`mobile`	string	—
`website`	string	—
`address`	string	—
`note`	string	—
`agent_id`	string	Agent user ID (use agent_name if ID unknown)
`agent_name`	string	Agent name — resolved to agent_id automatically
`status_id`	string	Lead status ID (use status_name if ID unknown)
`status_name`	string	Lead status name (e.g. "New", "In Progress") — resolved to status_id automatically
`source_id`	string	Lead source ID (use source_name if ID unknown)
`source_name`	string	Lead source name (e.g. "Website", "Referral") — resolved to source_id automatically
`next_follow_up`	string	Whether a follow-up is scheduled (yes/no). Default: yes
`next_follow_up_date`	string	Follow-up date (Y-m-d) — stored as a follow-up record, not on the lead directly
`startDate`	string	Filter from date
`endDate`	string	Filter to date
`search`	string	—

GET Leads

Request

{
    "client": "lead",
    "per_page": 20,
    "page": 1
}

Response

{
    "status": "success",
    "data": [
        {
            "id": 55,
            "client_name": "PT Maju Jaya",
            "email": "[email protected]",
            "mobile": "+6281234567890",
            "status_id": 2,
            "agent_id": 7
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Leads

Request

{
    "client_name": "PT Maju Jaya",
    "email": "[email protected]",
    "mobile": "+6281234567890",
    "status_id": 1,
    "agent_id": 7
}

Response

{
    "status": "success",
    "message": "Lead created successfully.",
    "id": 56
}

Errors

HTTP Code	Message
`422`	The client name field is required.

PUT Leads

Request

{
    "id": 55,
    "status": 3,
    "note": "Proposal sent"
}

Response

{
    "status": "success",
    "message": "Lead updated successfully."
}

Errors

HTTP Code	Message
`404`	Lead not found.

DELETE Leads

Request

{
    "id": 55
}

Response

{
    "status": "success",
    "message": "Lead deleted successfully."
}

Errors

HTTP Code	Message
`404`	Lead not found.

Invoices

GET POST PUT DELETE

Manage client invoices: list, create, update status, delete. Filter by client, status, date range.

Parameters

Name	Type	Description
`id`	string	Invoice ID — or use invoice_number to look up
`invoice_number`	string	Invoice number to look up (e.g. INV#0001) for PUT/DELETE
`client_name`	string	Client company name or contact name to filter or use for create
`client_id`	string	—
`project_id`	string	—
`issue_date`	string	Issue date (Y-m-d, defaults to today)
`due_date`	string	Due date (Y-m-d)
`sub_total`	number	Subtotal amount
`total`	number	Total amount (required for POST)
`currency_id`	string	—
`note`	string	—
`status`	string	Filter invoices by status (GET) or update status (PUT)
`search`	string	Search in invoice number or client name
`startDate`	string	—
`endDate`	string	—

GET Invoices

Request

{
    "client_name": "Acme Corp"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 1,
            "invoice_number": 1,
            "client_id": 3,
            "total": 5000,
            "issue_date": "2026-05-01",
            "due_date": "2026-05-31"
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Invoices

Request

{
    "client_name": "Acme Corp",
    "total": 5000,
    "issue_date": "2026-05-01",
    "due_date": "2026-05-31"
}

Response

{
    "success": true,
    "message": "Invoice created for client #3 with total 5000."
}

Errors

HTTP Code	Message
`422`	"total" is required to create an invoice.

PUT Invoices

Request

{
    "invoice_number": "INV#0001",
    "due_date": "2026-06-15"
}

Response

{
    "success": true,
    "message": "Invoice #1 updated."
}

Errors

HTTP Code	Message
`404`	Invoice not found.

DELETE Invoices

Request

{
    "invoice_number": "INV#0001"
}

Response

{
    "success": true,
    "message": "Invoice #1 deleted."
}

Errors

HTTP Code	Message
`404`	Invoice not found.

Estimates

GET POST PUT DELETE

Manage client estimates/quotes: list, create, update, delete. Filter by client, status, date.

Parameters

Name	Type	Description
`id`	string	Estimate ID — or use estimate_number to look up
`estimate_number`	string	Estimate number for lookup (PUT/DELETE), e.g. EST#0001
`client_name`	string	Client company name or contact name for create/filter
`client_id`	string	—
`valid_till`	string	Expiry date (Y-m-d)
`sub_total`	number	—
`total`	number	Total amount (required for POST)
`discount`	number	—
`discount_type`	string	percent or fixed
`currency_id`	string	—
`note`	string	—
`status`	string	draft/sent/declined/accepted — filter (GET) or update (PUT)
`search`	string	—
`startDate`	string	—
`endDate`	string	—

GET Estimates

Request

{
    "status": "draft"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 1,
            "estimate_number": 1,
            "client_id": 3,
            "total": 12000,
            "valid_till": "2026-06-30",
            "status": "draft"
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Estimates

Request

{
    "client_name": "Acme Corp",
    "total": 12000,
    "valid_till": "2026-06-30",
    "status": "draft"
}

Response

{
    "success": true,
    "message": "Estimate created with total 12000 for client #3."
}

Errors

HTTP Code	Message
`422`	"total" is required to create an estimate.

PUT Estimates

Request

{
    "estimate_number": "EST#0001",
    "status": "sent"
}

Response

{
    "success": true,
    "message": "Estimate #1 updated."
}

Errors

HTTP Code	Message
`404`	Estimate not found.

DELETE Estimates

Request

{
    "estimate_number": "EST#0001"
}

Response

{
    "success": true,
    "message": "Estimate #1 deleted."
}

Errors

HTTP Code	Message
`404`	Estimate not found.

Events

GET POST PUT DELETE

Manage company events/calendar: list, create, update, delete. Filter by month, year, date range.

Parameters

Name	Type	Description
`id`	string	Event ID — or use event_name to look up by name
`event_name`	string	Event name (required for POST, or use to look up for PUT/DELETE)
`where`	string	Event location
`description`	string	—
`start_date_time`	string	Start date/time (Y-m-d H:i or Y-m-d, required for POST)
`end_date_time`	string	End date/time (Y-m-d H:i or Y-m-d, required for POST)
`repeat`	string	Whether the event repeats. Default: no
`repeat_every`	integer	Repeat interval (e.g. every 2 weeks)
`repeat_cycles`	integer	Number of times the event repeats
`repeat_type`	string	Repeat frequency unit
`label_color`	string	Bootstrap color class or hex color (default: bg-info)
`month`	string	Filter list by month number (1–12)
`year`	string	Filter list by 4-digit year
`startDate`	string	Filter events starting on or after this date (Y-m-d)
`endDate`	string	Filter events starting on or before this date (Y-m-d)
`search`	string	Partial name search against event_name
`upcoming`	boolean	When true (default), only return events whose start_date_time is today or in the future. Pass false to include past events.

GET Events

Request

{
    "month": "6",
    "year": "2026"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 15,
            "event_name": "Q2 All-Hands Meeting",
            "where": "Main Conference Room",
            "start_date_time": "2026-06-15 09:00:00",
            "end_date_time": "2026-06-15 11:00:00",
            "repeat": "no"
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Events

Request

{
    "event_name": "Q2 All-Hands Meeting",
    "start_date_time": "2026-06-15 09:00",
    "end_date_time": "2026-06-15 11:00",
    "where": "Main Conference Room"
}

Response

{
    "success": true,
    "message": "Event 'Q2 All-Hands Meeting' created on 2026-06-15."
}

Errors

HTTP Code	Message
`422`	"event_name" is required to create an event.

PUT Events

Request

{
    "event_name": "Q2 All-Hands Meeting",
    "where": "Zoom"
}

Response

{
    "success": true,
    "message": "Event 'Q2 All-Hands Meeting' updated."
}

Errors

HTTP Code	Message
`404`	Event not found.

DELETE Events

Request

{
    "id": "15"
}

Response

{
    "success": true,
    "message": "Event 'Q2 All-Hands Meeting' deleted."
}

Errors

HTTP Code	Message
`404`	Event not found.

Expenses

GET POST PUT DELETE

Manage expenses and claims: list, create, update status (approve/reject), delete. Filter by employee, category, status, date range.

Parameters

Name	Type	Description
`id`	string	Expense ID — or use item_name to look up by name
`item_name`	string	Expense item name (required for POST, or use to look up for PUT/DELETE)
`purchase_date`	string	Purchase date (Y-m-d, required for POST)
`purchase_from`	string	Where it was purchased from
`price`	number	Expense amount (required for POST)
`currency_id`	string	Currency ID (defaults to company currency if omitted)
`expense_category_id`	string	Expense category ID (use expense_category_name if ID unknown)
`expense_category_name`	string	Expense category name — resolved to expense_category_id automatically
`employee_name`	string	Filter by employee name (GET) or look up user to assign (POST)
`user_id`	string	Employee user ID (admin can specify; defaults to self)
`project_id`	string	Link expense to a project (optional)
`description`	string	Additional notes about the expense
`status`	string	Filter (GET) or update status (PUT)
`can_claim`	integer \| boolean	1 = claim reimbursement request, 0 = regular expense
`startDate`	string	Filter expenses from this purchase date (Y-m-d)
`endDate`	string	Filter expenses up to this purchase date (Y-m-d)

GET Expenses

Request

{
    "status": "pending"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 99,
            "item_name": "Team Lunch",
            "purchase_date": "2026-05-10",
            "price": 250,
            "status": "pending",
            "can_claim": 1,
            "user_id": 7
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Expenses

Request

{
    "item_name": "Team Lunch",
    "purchase_date": "2026-05-10",
    "price": 250,
    "can_claim": 1
}

Response

{
    "success": true,
    "message": "Expense 'Team Lunch' created (ID #99)."
}

Errors

HTTP Code	Message
`422`	'item_name' is required.

PUT Expenses

Request

{
    "id": "99",
    "status": "approved"
}

Response

{
    "success": true,
    "message": "Expense 'Team Lunch' updated."
}

Errors

HTTP Code	Message
`404`	Expense not found.

DELETE Expenses

Request

{
    "id": "99"
}

Response

{
    "success": true,
    "message": "Expense 'Team Lunch' (ID #99) deleted."
}

Errors

HTTP Code	Message
`403`	Only admins can delete expenses.

Expense Category

GET POST PUT DELETE

Manage expense categories: list, create, update, delete. Admin-only for write operations.

Parameters

Name	Type	Description
`id`	string	Category ID — or use category_name to look up by name instead
`category_name`	string	Category name (required for POST; also used to look up for PUT/DELETE)
`search`	string	Partial name search against category_name (GET only)

GET Expense Category

Request

[]

Response

{
    "success": true,
    "data": [
        {
            "id": 1,
            "category_name": "Travel & Accommodation"
        },
        {
            "id": 2,
            "category_name": "Office Supplies"
        }
    ],
    "total": 2
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Expense Category

Request

{
    "category_name": "Marketing"
}

Response

{
    "success": true,
    "message": "Expense category 'Marketing' created."
}

Errors

HTTP Code	Message
`422`	"category_name" is required.

PUT Expense Category

Request

{
    "category_name": "Travel & Accommodation"
}

Response

{
    "success": true,
    "message": "Expense category 'Travel & Accommodation' updated."
}

Errors

HTTP Code	Message
`404`	Expense category not found.

DELETE Expense Category

Request

{
    "id": "1"
}

Response

{
    "success": true,
    "message": "Expense category 'Travel & Accommodation' deleted."
}

Errors

HTTP Code	Message
`403`	Only admins can delete expense categories.

Notices

GET POST PUT DELETE

Manage notice board: list, create, update, delete. Filter by date range or audience (all/employee/client).

Parameters

Name	Type	Description
`id`	string	Notice ID — or use heading to look up by title
`heading`	string	Notice title (required for POST, or use to look up for PUT/DELETE)
`description`	string	Notice content body (required for POST)
`to`	string	Target audience (default: all)
`search`	string	Search keyword matched against notice heading
`startDate`	string	Filter notices created on or after this date (Y-m-d)
`endDate`	string	Filter notices created on or before this date (Y-m-d)

GET Notices

Request

{
    "to": "employee"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 12,
            "heading": "Office Closed on Friday",
            "description": "The office will be closed this Friday for maintenance.",
            "to": "all",
            "created_at": "2026-05-08T10:00:00Z"
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Notices

Request

{
    "heading": "Office Closed on Friday",
    "description": "The office will be closed this Friday for maintenance.",
    "to": "all"
}

Response

{
    "success": true,
    "message": "Notice 'Office Closed on Friday' created (ID #12)."
}

Errors

HTTP Code	Message
`422`	'heading' is required.

PUT Notices

Request

{
    "heading": "Office Closed on Friday",
    "description": "Updated: Office closed Friday AND Monday."
}

Response

{
    "success": true,
    "message": "Notice 'Office Closed on Friday' updated."
}

Errors

HTTP Code	Message
`404`	Notice not found.

DELETE Notices

Request

{
    "id": "12"
}

Response

{
    "success": true,
    "message": "Notice 'Office Closed on Friday' (ID #12) deleted."
}

Errors

HTTP Code	Message
`403`	Only admins can delete notices.

Contracts

GET POST PUT DELETE

Manage client contracts: list, create, update, delete. Filter by client, status, date range.

Parameters

Name	Type	Description
`id`	string	Contract ID — or use subject to look up by title
`subject`	string	Contract title (required for POST, or use to look up for PUT/DELETE)
`client_name`	string	Client company name to find client user ID (used for create or filter)
`client_id`	string	Client user ID (alternative to client_name)
`contract_type_id`	string	Contract type ID (auto-resolved from contract_type_name if omitted)
`contract_type_name`	string	Contract type name (e.g. "Service Agreement") — resolved to contract_type_id
`start_date`	string	Contract start date (Y-m-d)
`end_date`	string	Contract end date (Y-m-d)
`description`	string	Contract description or notes
`amount`	number	Contract monetary value
`search`	string	Search keyword matched against contract subject
`startDate`	string	Filter contracts with start_date on or after this date (Y-m-d)
`endDate`	string	Filter contracts with end_date on or before this date (Y-m-d)

GET Contracts

Request

{
    "client_name": "Acme Corp"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 7,
            "subject": "Annual Support Contract",
            "client_id": 3,
            "amount": 24000,
            "start_date": "2026-01-01",
            "end_date": "2026-12-31"
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Contracts

Request

{
    "subject": "Annual Support Contract",
    "client_name": "Acme Corp",
    "start_date": "2026-01-01",
    "end_date": "2026-12-31",
    "amount": 24000
}

Response

{
    "success": true,
    "message": "Contract 'Annual Support Contract' created (ID #7)."
}

Errors

HTTP Code	Message
`422`	'subject' is required.

PUT Contracts

Request

{
    "subject": "Annual Support Contract",
    "amount": 30000
}

Response

{
    "success": true,
    "message": "Contract 'Annual Support Contract' updated."
}

Errors

HTTP Code	Message
`404`	Contract not found.

DELETE Contracts

Request

{
    "id": "7"
}

Response

{
    "success": true,
    "message": "Contract 'Annual Support Contract' (ID #7) deleted."
}

Errors

HTTP Code	Message
`404`	Contract not found.

Timelogs

GET POST PUT DELETE

Manage project/task time logs: list, create (start timer), update (stop timer/edit), delete. Filter by project, employee, date.

Parameters

Name	Type	Description
`id`	string	Time log ID (required for DELETE; used for PUT when provided)
`project_name`	string	Project name — resolved to project_id automatically
`project_id`	string	Project ID (alternative to project_name)
`task_name`	string	Task heading — resolved to task_id automatically
`task_id`	string	Task ID (alternative to task_name)
`employee_name`	string	Employee name — resolved to user_id for filtering or creating
`user_id`	string	Employee user ID (admin can specify; defaults to self)
`start_time`	string	Start datetime (Y-m-d H:i or Y-m-d H:i:s). Defaults to now() on POST.
`end_time`	string	End datetime — provide on PUT to stop a running timer; omit to keep timer running
`memo`	string	Optional note or description for the time log entry
`date`	string	Filter by specific date (Y-m-d)
`month`	string	Filter by month number (1–12)
`year`	string	Filter by year (e.g. 2025)
`active_only`	boolean \| string	If true, return only running timers (no end_time)

GET Timelogs

Request

{
    "month": "5",
    "year": "2026"
}

Response

{
    "success": true,
    "data": [
        {
            "id": 88,
            "user_id": 7,
            "project_id": 12,
            "task_id": 101,
            "start_time": "2026-05-10 09:00:00",
            "end_time": "2026-05-10 17:30:00",
            "total_hours": 8.5,
            "total_minutes": 510,
            "memo": "Working on hero section"
        }
    ],
    "total": 1
}

Errors

HTTP Code	Message
`401`	Unauthenticated.

POST Timelogs

Request

{
    "project_name": "Mobile App v2",
    "task_name": "Design landing page",
    "memo": "Working on hero section"
}

Response

{
    "success": true,
    "message": "Timer started for project ID #12, task ID #101 (log ID #88)."
}

Errors

HTTP Code	Message
`422`	Failed to start timer.

PUT Timelogs

Request

{
    "id": "88",
    "end_time": "2026-05-10 17:30"
}

Response

{
    "success": true,
    "message": "Time log #88 updated (timer stopped). Total logged: 8h 30m."
}

Errors

HTTP Code	Message
`404`	Time log not found or no active timer running.

DELETE Timelogs

Request

{
    "id": "88"
}

Response

{
    "success": true,
    "message": "Time log #88 deleted."
}

Errors

HTTP Code	Message
`403`	Only admins can delete time logs.

MCP API Reference FlowyTeam

Claude Code Only — Claude Desktop Not Supported

Start building with FlowyTeam MCP