{ "openapi": "3.1.0", "info": { "title": "Growee API", "version": "2026.07.14", "description": "The Growee REST API gives you programmatic access to your workspace: employees, leave, time tracking, projects, clients, invoicing, CRM, performance and more.\n\n## Authentication\n\nCreate an API key in Growee under **Settings → Integrations → API Keys** and send it with every request:\n\n```\nAuthorization: Bearer \n```\n\nEach key carries a set of **permission scopes** chosen at creation time and can optionally be restricted to an **IP allowlist**. A key can never do more than the user who created it.\n\n## Workspace (tenant)\n\nRequests are scoped to a workspace through the subdomain: `https://.growee.net/api/restify/...`. If you cannot use the subdomain, add `?tenant=` to the request URL instead.\n\n## Conventions\n\n- IDs are **ULIDs** (26-character strings).\n- Lists are paginated with `page` and `perPage`; responses include `meta` and `links`.\n- Filter with the documented per-endpoint query parameters (e.g. `employees?status=active`), search with `search`, sort with `sort=field` or `sort=-field`, and eager-load relationships with `related=`.\n- Dates are ISO 8601 strings in UTC unless documented otherwise.\n- The API is built on the open-source [Laravel Restify](https://laravel-restify.com/) framework; its documentation covers the shared query language in depth.\n\n## Field visibility\n\nThis reference documents the **full superset** of fields. Fields gated by a permission (noted in their descriptions) are omitted from responses when the API key or its user lacks that permission.\n\n## Rate limits\n\nAPI-key traffic is limited to **60 requests/minute per key** (and 180 requests/minute per user overall). When you exceed a limit the API responds `429 Too Many Requests` with a `Retry-After` header.", "contact": { "name": "Growee Support", "email": "support@growee.ai", "url": "https://growee.ai/developer" } }, "servers": [ { "url": "https://{tenant}.growee.net/api/restify", "description": "Your Growee workspace", "variables": { "tenant": { "default": "your-company", "description": "Your Growee workspace subdomain (the part before .growee.net in the URL you use to sign in)." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Employees", "description": "Employee profiles: personal and company details, contracts, positions and reporting lines." }, { "name": "Organization", "description": "Company structure reference data: departments, positions, levels, directions, work locations, contract types and evaluation types." }, { "name": "Benefits", "description": "Employee benefits: the tenant benefits catalog and per-employee benefit assignments." }, { "name": "Leave", "description": "Leave management: holiday requests, per-employee balances and the policies that accrue them." }, { "name": "Time Tracking", "description": "Time logging: timesheet entries per employee/project/task, timers, grouping-based reports and submission workflows." }, { "name": "Projects", "description": "Projects, their tasks and employee assignments (rates, capacities)." }, { "name": "Clients", "description": "Clients you bill and their contact people." }, { "name": "Invoicing", "description": "Invoices and invoice lines generated from tracked time or created manually." }, { "name": "Expenses", "description": "Expense tracking: submitted expenses and their categories, flowing through an approval workflow." }, { "name": "Hiring", "description": "Recruitment: published jobs, candidates and pipeline stages." }, { "name": "Leads", "description": "Sales pipeline: leads, their stages, logged activities and meetings." }, { "name": "Tickets", "description": "Support tickets: durable customer conversations and their kanban stages." }, { "name": "Offers", "description": "Commercial offers and quotes sent to leads and clients." }, { "name": "Documents", "description": "Employee documents and document types, including template-generated files." }, { "name": "Performance", "description": "Performance management: evaluations, goals and 360 feedback." }, { "name": "Assets", "description": "Company assets assigned to employees (laptops, licenses, equipment)." }, { "name": "Knowledge Base", "description": "Knowledge base pages and teamspaces." }, { "name": "Custom Fields", "description": "Tenant-defined custom field definitions for leads, clients, client contacts and employees. Values are read and written through the `custom_fields` attribute on those records." }, { "name": "API Keys", "description": "Inspect the API keys used to authenticate against this API. Keys are created, regenerated and revoked in Growee under **Settings → Integrations → API Keys** - for security, requests authenticated with an API key can only read key metadata, never manage keys." }, { "name": "People Reports", "description": "Workforce analytics: headcount and HR KPIs, per-employee capacity and performance evaluation analytics." }, { "name": "Time Reports", "description": "Time and attendance reporting: timesheet reports, presence sheet exports and weekly approval status." }, { "name": "Finance Reports", "description": "Financial analytics: invoicing totals and time series, expense analytics and statistics." }, { "name": "Project Reports", "description": "Profitability analytics: project margins, portfolio overview, team economics and per-client profitability." }, { "name": "CRM Reports", "description": "Sales analytics: pipeline overview, funnel, forecast, sources, lost reasons, team performance and exports." } ], "x-tagGroups": [ { "name": "Human Resources", "tags": [ "Employees", "Organization", "Benefits", "Leave", "Time Tracking", "Performance", "Hiring", "Assets" ] }, { "name": "Work Management", "tags": [ "Projects", "Clients", "Documents" ] }, { "name": "Finance", "tags": [ "Invoicing", "Expenses" ] }, { "name": "Sales", "tags": [ "Leads", "Tickets", "Offers" ] }, { "name": "Reports & Analytics", "tags": [ "People Reports", "Time Reports", "Finance Reports", "Project Reports", "CRM Reports" ] }, { "name": "Platform", "tags": [ "Knowledge Base", "Custom Fields", "API Keys" ] } ], "paths": { "/employees": { "get": { "operationId": "employees-index", "summary": "List employees", "description": "This repository manages employees, the people who work at the tenant (company) stored in the employees table. Each employee is the HR profile for a team member and is optionally linked to a login user (relation \"user\"), a manager (self relation), a position, level, direction/department, contract type, work locations and tags. It is the backbone the rest of Growee references: timesheets, holidays, projects, evaluations, salaries, documents and benefits all belong to an employee. Use this tool to look up, search, filter and manage team members; use the sibling employee-benefits and salary-history repositories for a person's benefits and pay history, and the projects/documents repositories for their assignments and files.", "tags": [ "Employees" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of employees per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- user (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- manager (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- managedEmployees (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- documents (fields: client_id, content, created_at, description, documentable_type, employee_id, end_date, file_name, id, is_signed, name, path, signature_count, size, start_date, status, type_id)\n- contractType (fields: heading, id, name)\n- holidayBalances (fields: balance, deleted_at, employee_id, holiday_policy_id, initial_balance, year)\n- position (fields: department_id, description, id, is_used, name)\n- level (fields: created_at, description, id, is_used, name)\n- projects (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- archiver (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- direction (fields: department_id, description, is_used, name)\n- workLocations (fields: description, is_used, name)\n- tags (fields: color, name, type)\n- feedback (fields: audio_file, audio_file_name, created_by, created_by_employee_id, feedback_request_id, feedbackable_id, feedbackable_type, file, file_name, given_at, id, is_visible_to_employee, notes, transcription, transcription_status, type)\n- salaryHistory (fields: amount, employee_id, end_date, is_demo, notes, start_date, type)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=user,manager (include all fields)\n- include=user[archived_at,avatar] (selective fields with comma syntax)\n- include=user[archived_at|avatar] (selective fields with pipe syntax)\n- include=user.posts (nested relationship - all fields)\n- include=user[name].posts[title] (nested with field selection at each level)\n- include=user[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=user.posts[title],user.comments[body] (multiple nested from same parent)\n- include=user[name],manager[id] (multiple relationships with field selection)\n- include=user[email|name].posts[title],manager[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter employees by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the employees. Available options: id, email, first_name, last_name, status, start_date, termination_date (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "position_id", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for position_id (e.g., position_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -position_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "direction_id", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for direction_id (e.g., direction_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -direction_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "work_location_ids", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for work_location_ids (e.g., work_location_ids=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -work_location_ids=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "level_id", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for level_id (e.g., level_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -level_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "manager_employee_id", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for manager_employee_id (e.g., manager_employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -manager_employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "position_name", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for position_name (e.g., position_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -position_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "permissions", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for permissions (e.g., permissions=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -permissions=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "department", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for department (e.g., department=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -department=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for direction (e.g., direction=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -direction=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for email (e.g., email=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -email=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "first_name", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for first_name (e.g., first_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -first_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "last_name", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for last_name (e.g., last_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -last_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "contract_type", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for contract_type (e.g., contract_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -contract_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "identity_card_number", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for identity_card_number (e.g., identity_card_number=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -identity_card_number=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a date match for start_date (e.g., start_date=YYYY-MM-DD or start_date=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -start_date=YYYY-MM-DD or -start_date=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "termination_date", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a date match for termination_date (e.g., termination_date=YYYY-MM-DD or termination_date=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -termination_date=YYYY-MM-DD or -termination_date=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for archived (e.g., archived=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -archived=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for project_id (e.g., project_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -project_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "superiors", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for superiors (e.g., superiors=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -superiors=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "archived_at", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a range match for archived_at (e.g., archived_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -archived_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "required": false, "description": "Filter employees resource. Description: This is a exact match for tags (e.g., tags=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -tags=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 33, "path": "https://demo.growee.test/api/restify/employees", "per_page": 1, "to": 1, "total": 33 }, "links": { "first": "https://demo.growee.test/api/restify/employees?page=1", "next": "https://demo.growee.test/api/restify/employees?page=2", "path": "https://demo.growee.test/api/restify/employees", "prev": null, "filters": "/api/restify/employees/filters" }, "data": [ { "id": "01kwt1xs130rkwxme6vdnrf488", "type": "employees", "attributes": { "position_id": "01kwt1xn9azx7jvjfj9hm16r1p", "work_location_ids": [], "manager_employee_id": "01kwt1xnqv7p381zpjvz91q739", "level_id": "01kwt1xna13rc582cm7g2mf7bw", "role_id": "01kdj6d45rb3t2ad19k8fyv2tc", "email": "paul.whitfield@demo.com", "avatar": "https://randomuser.me/api/portraits/men/29.jpg", "avatar_name": "29.jpg", "status": "draft", "first_name": "Paul", "name": "Paul Whitfield", "last_name": "Whitfield", "phone": "+40-733-833-934", "birth_date": "1985-05-20T00:00:00.000000Z", "identity_card_number": "548144", "personal_identification_number": "1924821432874", "address": { "city": "București", "state": "Sector 3", "street": "Calea Turzii 12", "country": "Romania", "zip_code": "592271" }, "timezone": "Europe/Bucharest", "invite_immediately": false, "contract_type": "employment_contract", "company_position": "Junior Developer", "company_name": "Demo Company", "company_identifier": "DEMO4088", "company_address": { "city": "București", "state": "Sector 3", "street": "Strada Dorobanților 71", "country": "Romania", "zip_code": "409786" }, "contract_bank_name": "Banca Transilvania", "contract_bank_swift": "INGBROBUXXX", "contract_bank_account": "RO49BTRL391970330", "start_date": "2026-07-26T00:00:00.000000Z", "salary_type": "monthly", "salary_currency": "EUR", "salary": 2550, "weekly_hours_capacity": 40, "initial_vacation_balance": 0, "technical_evaluation_assignees": [], "salary_evaluation_assignees": [], "billed_rate": 0, "internal_cost_hourly_rate": 0, "gender": "male", "custom_fields": { "custom-field-select": "Option 1" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "employees-store", "summary": "Create an employee", "tags": [ "Employees" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "position_id": { "description": "The position of the employee. Optional but recommended when creating a new employee. It must be a valid position ID. You can identify it using the positions tool.", "type": "string" }, "direction_id": { "description": "The direction/department the employee belongs to. Optional field. Must be a valid direction ID if provided.", "type": "number" }, "manager_employee_id": { "description": "The ID of the employee's manager. Optional field. Must be a valid employee ID from the same tenant if provided.", "type": "string" }, "level_id": { "description": "The level/seniority of the employee. Optional field. Must be a valid level ID if provided.", "type": "string" }, "email": { "description": "The employee's work email address. Required when creating a new employee. Must be unique and a valid email format.", "type": "string" }, "avatar": { "description": "The employee's profile picture. Optional field. Must be a string absolute image path.", "type": "string" }, "avatar_name": { "description": "The original filename of the employee's avatar. Automatically stored when an avatar is uploaded.", "type": "string" }, "default_signature_id": { "description": "The ID of the default signature to use for this employee when signing documents.", "type": "string" }, "status": { "description": "The employment status of the employee (e.g., active, inactive). This field is typically managed by the system.", "type": "string" }, "personal_email": { "description": "The employee's personal email address. Optional field. Must be a valid email format if provided.", "type": "string" }, "first_name": { "description": "The employee's first name. Required when creating a new employee.", "type": "string" }, "last_name": { "description": "The employee's last name. Required when creating a new employee.", "type": "string" }, "general_information": { "description": "General information or notes about the employee. Optional text field.", "type": "string" }, "phone": { "description": "The employee's phone number. Optional field.", "type": "string" }, "birth_date": { "description": "The employee's date of birth. Optional field. Must be a valid date format if provided.", "type": "string" }, "identity_card_number": { "description": "The employee's identity card or passport number. Optional field for identification purposes.", "type": "string" }, "personal_identification_number": { "description": "The employee's national identification number (e.g., SSN, CNP). Optional field.", "type": "string" }, "address": { "description": "The employee's residential address. Optional field.", "type": "object" }, "timezone": { "description": "The employee's timezone. Optional field. Must be a valid timezone identifier if provided.", "type": "string" }, "about": { "description": "A brief description or bio about the employee. Optional text field.", "type": "string" }, "quote": { "description": "A favorite quote or motto of the employee. Optional field with maximum 500 characters.", "type": "string" }, "invite_immediately": { "description": "Whether to send an invitation email to the employee immediately upon creation. Boolean field.", "type": "boolean" }, "contract_type": { "description": "The type of employment contract. Available values:{\"employment_contract\":\"Used when the employee is hired under a standard employment contract. Usually offers full labor rights, paid holidays and benefits.\",\"internship\":\"Used for temporary training positions, often for students or recent graduates. May have limited benefits and a fixed duration.\",\"b2b_unpaid_holidays\":\"Used for contractors or freelancers working under a business-to-business agreement without paid holiday entitlements.\",\"b2b_paid_holidays\":\"Used for contractors or freelancers working under a business-to-business agreement with paid holiday entitlements.\"}", "enum": [ "employment_contract", "internship", "b2b_unpaid_holidays", "b2b_paid_holidays" ], "type": "string" }, "company_position": { "description": "The official position title in the employee's company (for contractors). Optional field.", "type": "string" }, "company_name": { "description": "The name of the employee's company (for contractors). Optional field.", "type": "string" }, "company_vat": { "description": "The VAT number of the employee's company (for contractors). Optional field.", "type": "string" }, "company_identifier": { "description": "The registration number or identifier of the employee's company (for contractors). Optional field.", "type": "string" }, "company_address": { "description": "The address of the employee's company (for contractors). Optional field.", "type": "object" }, "contract_bank_name": { "description": "The name of the bank for contract payments. Optional field.", "type": "string" }, "contract_bank_swift": { "description": "The SWIFT/BIC code of the bank for contract payments. Optional field.", "type": "string" }, "contract_bank_account": { "description": "The bank account number for contract payments. Optional field.", "type": "string" }, "start_date": { "description": "The employee's start date. Required when creating a new employee. Must be a valid date format.", "type": "string" }, "termination_date": { "description": "The employee's termination date. Optional field. Must be after the start date if provided.", "type": "string" }, "salary_type": { "description": "The type of salary payment (e.g., monthly, hourly). Visible only to users with manage salaries permission. Available values: {\"hourly\":\"Hourly\",\"monthly\":\"Monthly\"}", "type": "string" }, "salary_currency": { "description": "The currency code for the salary (e.g., USD, EUR, RON). Visible only to users with manage salaries permission. Must be a 3-character currency code.", "type": "string" }, "salary": { "description": "The employee's salary amount. Visible only to users with manage salaries permission. Must be a positive number if provided.", "type": "integer" }, "sensitive_information": { "description": "Sensitive or confidential information about the employee. Optional text field with restricted access.", "type": "string" }, "weekly_hours_capacity": { "description": "The employee's weekly working hours capacity. Optional field. Must be between 0 and 168 hours if provided. Use 0 for overtime-only tracking (no expected weekly hours).", "minimum": 0, "maximum": 168, "type": "integer" }, "initial_vacation_balance": { "description": "The initial vacation days balance for the employee. Optional field. Must be a positive number if provided.", "type": "integer" }, "technical_evaluation_assignees": { "description": "Array of employee IDs who are assigned to perform technical evaluations for this employee. Optional field. All IDs must be valid employees from the same tenant.", "type": "array" }, "salary_evaluation_assignees": { "description": "Array of employee IDs who are assigned to perform salary evaluations for this employee. Optional field. All IDs must be valid employees from the same tenant.", "type": "array" }, "billed_rate": { "description": "The hourly rate at which the employee is billed to clients. Visible only to users with manage employees permission. Must be a positive number if provided.", "type": "integer" }, "internal_cost_hourly_rate": { "description": "The internal hourly cost rate for the employee. Visible only to users with manage employees permission. Must be a positive number if provided.", "type": "integer" }, "internal_cost_type": { "description": "The unit used to express the internal cost rate. Available values: hourly, monthly. Null is treated as hourly. Visible only to users with manage employees permission.", "type": "string" }, "internal_cost_monthly_rate": { "description": "The internal monthly cost for the employee, converted to an hourly equivalent using the weekly hours capacity. Required when internal_cost_type is monthly. Visible only to users with manage employees permission.", "minimum": 0, "type": "number" }, "position_code": { "description": "An internal code or reference for the employee's position. Optional field with maximum 50 characters.", "type": "string" }, "gender": { "description": "The employee's gender. Optional field.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" } }, "required": [ "email", "first_name", "last_name", "start_date" ] }, "example": { "position_id": "01kwt1xn9azx7jvjfj9hm16r1p", "manager_employee_id": "01kwt1xnqv7p381zpjvz91q739", "level_id": "01kwt1xna13rc582cm7g2mf7bw", "email": "paul.whitfield@demo.com", "avatar": "https://randomuser.me/api/portraits/men/29.jpg", "avatar_name": "29.jpg", "status": "draft", "first_name": "Paul", "last_name": "Whitfield", "phone": "+40-733-833-934", "birth_date": "1985-05-20T00:00:00.000000Z", "identity_card_number": "548144", "personal_identification_number": "1924821432874", "address": { "city": "București", "state": "Sector 3", "street": "Calea Turzii 12", "country": "Romania", "zip_code": "592271" }, "timezone": "Europe/Bucharest", "invite_immediately": false, "contract_type": "employment_contract", "company_position": "Junior Developer", "company_name": "Demo Company", "company_identifier": "DEMO4088", "company_address": { "city": "București", "state": "Sector 3", "street": "Strada Dorobanților 71", "country": "Romania", "zip_code": "409786" }, "contract_bank_name": "Banca Transilvania", "contract_bank_swift": "INGBROBUXXX", "contract_bank_account": "RO49BTRL391970330", "start_date": "2026-07-26T00:00:00.000000Z", "salary_type": "monthly", "salary_currency": "EUR", "salary": 2550, "weekly_hours_capacity": 40, "initial_vacation_balance": 0, "technical_evaluation_assignees": [], "salary_evaluation_assignees": [], "billed_rate": 0, "internal_cost_hourly_rate": 0, "gender": "male", "custom_fields": { "custom-field-select": "Option 1" } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmployeeResource" } } }, "example": { "data": { "id": "01kwt1xs130rkwxme6vdnrf488", "type": "employees", "attributes": { "position_id": "01kwt1xn9azx7jvjfj9hm16r1p", "work_location_ids": [], "manager_employee_id": "01kwt1xnqv7p381zpjvz91q739", "level_id": "01kwt1xna13rc582cm7g2mf7bw", "role_id": "01kdj6d45rb3t2ad19k8fyv2tc", "email": "paul.whitfield@demo.com", "avatar": "https://randomuser.me/api/portraits/men/29.jpg", "avatar_name": "29.jpg", "status": "draft", "first_name": "Paul", "name": "Paul Whitfield", "last_name": "Whitfield", "phone": "+40-733-833-934", "birth_date": "1985-05-20T00:00:00.000000Z", "identity_card_number": "548144", "personal_identification_number": "1924821432874", "address": { "city": "București", "state": "Sector 3", "street": "Calea Turzii 12", "country": "Romania", "zip_code": "592271" }, "timezone": "Europe/Bucharest", "invite_immediately": false, "contract_type": "employment_contract", "company_position": "Junior Developer", "company_name": "Demo Company", "company_identifier": "DEMO4088", "company_address": { "city": "București", "state": "Sector 3", "street": "Strada Dorobanților 71", "country": "Romania", "zip_code": "409786" }, "contract_bank_name": "Banca Transilvania", "contract_bank_swift": "INGBROBUXXX", "contract_bank_account": "RO49BTRL391970330", "start_date": "2026-07-26T00:00:00.000000Z", "salary_type": "monthly", "salary_currency": "EUR", "salary": 2550, "weekly_hours_capacity": 40, "initial_vacation_balance": 0, "technical_evaluation_assignees": [], "salary_evaluation_assignees": [], "billed_rate": 0, "internal_cost_hourly_rate": 0, "gender": "male", "custom_fields": { "custom-field-select": "Option 1" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/employees/{id}": { "get": { "operationId": "employees-show", "summary": "Retrieve an employee", "tags": [ "Employees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmployeeResource" } } }, "example": { "data": { "id": "01kwt1xs130rkwxme6vdnrf488", "type": "employees", "attributes": { "position_id": "01kwt1xn9azx7jvjfj9hm16r1p", "work_location_ids": [], "manager_employee_id": "01kwt1xnqv7p381zpjvz91q739", "level_id": "01kwt1xna13rc582cm7g2mf7bw", "role_id": "01kdj6d45rb3t2ad19k8fyv2tc", "email": "paul.whitfield@demo.com", "avatar": "https://randomuser.me/api/portraits/men/29.jpg", "avatar_name": "29.jpg", "status": "draft", "first_name": "Paul", "name": "Paul Whitfield", "last_name": "Whitfield", "phone": "+40-733-833-934", "birth_date": "1985-05-20T00:00:00.000000Z", "identity_card_number": "548144", "personal_identification_number": "1924821432874", "address": { "city": "București", "state": "Sector 3", "street": "Calea Turzii 12", "country": "Romania", "zip_code": "592271" }, "timezone": "Europe/Bucharest", "invite_immediately": false, "contract_type": "employment_contract", "company_position": "Junior Developer", "company_name": "Demo Company", "company_identifier": "DEMO4088", "company_address": { "city": "București", "state": "Sector 3", "street": "Strada Dorobanților 71", "country": "Romania", "zip_code": "409786" }, "contract_bank_name": "Banca Transilvania", "contract_bank_swift": "INGBROBUXXX", "contract_bank_account": "RO49BTRL391970330", "start_date": "2026-07-26T00:00:00.000000Z", "salary_type": "monthly", "salary_currency": "EUR", "salary": 2550, "weekly_hours_capacity": 40, "initial_vacation_balance": 0, "technical_evaluation_assignees": [], "salary_evaluation_assignees": [], "billed_rate": 0, "internal_cost_hourly_rate": 0, "gender": "male", "custom_fields": { "custom-field-select": "Option 1" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "employees-update", "summary": "Update an employee", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Employees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "position_id": { "description": "The position of the employee. Optional but recommended when creating a new employee. It must be a valid position ID. You can identify it using the positions tool.", "type": "string" }, "direction_id": { "description": "The direction/department the employee belongs to. Optional field. Must be a valid direction ID if provided.", "type": "number" }, "manager_employee_id": { "description": "The ID of the employee's manager. Optional field. Must be a valid employee ID from the same tenant if provided.", "type": "string" }, "level_id": { "description": "The level/seniority of the employee. Optional field. Must be a valid level ID if provided.", "type": "string" }, "email": { "description": "The employee's work email address. Required when creating a new employee. Must be unique and a valid email format.", "type": "string" }, "avatar": { "description": "The employee's profile picture. Optional field. Must be a string absolute image path.", "type": "string" }, "avatar_name": { "description": "The original filename of the employee's avatar. Automatically stored when an avatar is uploaded.", "type": "string" }, "default_signature_id": { "description": "The ID of the default signature to use for this employee when signing documents.", "type": "string" }, "status": { "description": "The employment status of the employee (e.g., active, inactive). This field is typically managed by the system.", "type": "string" }, "personal_email": { "description": "The employee's personal email address. Optional field. Must be a valid email format if provided.", "type": "string" }, "first_name": { "description": "The employee's first name. Required when creating a new employee.", "type": "string" }, "last_name": { "description": "The employee's last name. Required when creating a new employee.", "type": "string" }, "general_information": { "description": "General information or notes about the employee. Optional text field.", "type": "string" }, "phone": { "description": "The employee's phone number. Optional field.", "type": "string" }, "birth_date": { "description": "The employee's date of birth. Optional field. Must be a valid date format if provided.", "type": "string" }, "identity_card_number": { "description": "The employee's identity card or passport number. Optional field for identification purposes.", "type": "string" }, "personal_identification_number": { "description": "The employee's national identification number (e.g., SSN, CNP). Optional field.", "type": "string" }, "address": { "description": "The employee's residential address. Optional field.", "type": "object" }, "timezone": { "description": "The employee's timezone. Optional field. Must be a valid timezone identifier if provided.", "type": "string" }, "about": { "description": "A brief description or bio about the employee. Optional text field.", "type": "string" }, "quote": { "description": "A favorite quote or motto of the employee. Optional field with maximum 500 characters.", "type": "string" }, "invite_immediately": { "description": "Whether to send an invitation email to the employee immediately upon creation. Boolean field.", "type": "boolean" }, "contract_type": { "description": "The type of employment contract. Available values:{\"employment_contract\":\"Used when the employee is hired under a standard employment contract. Usually offers full labor rights, paid holidays and benefits.\",\"internship\":\"Used for temporary training positions, often for students or recent graduates. May have limited benefits and a fixed duration.\",\"b2b_unpaid_holidays\":\"Used for contractors or freelancers working under a business-to-business agreement without paid holiday entitlements.\",\"b2b_paid_holidays\":\"Used for contractors or freelancers working under a business-to-business agreement with paid holiday entitlements.\"}", "type": "string" }, "company_position": { "description": "The official position title in the employee's company (for contractors). Optional field.", "type": "string" }, "company_name": { "description": "The name of the employee's company (for contractors). Optional field.", "type": "string" }, "company_vat": { "description": "The VAT number of the employee's company (for contractors). Optional field.", "type": "string" }, "company_identifier": { "description": "The registration number or identifier of the employee's company (for contractors). Optional field.", "type": "string" }, "company_address": { "description": "The address of the employee's company (for contractors). Optional field.", "type": "object" }, "contract_bank_name": { "description": "The name of the bank for contract payments. Optional field.", "type": "string" }, "contract_bank_swift": { "description": "The SWIFT/BIC code of the bank for contract payments. Optional field.", "type": "string" }, "contract_bank_account": { "description": "The bank account number for contract payments. Optional field.", "type": "string" }, "start_date": { "description": "The employee's start date. Required when creating a new employee. Must be a valid date format.", "type": "string" }, "termination_date": { "description": "The employee's termination date. Optional field. Must be after the start date if provided.", "type": "string" }, "salary_type": { "description": "The type of salary payment (e.g., monthly, hourly). Visible only to users with manage salaries permission. Available values: {\"hourly\":\"Hourly\",\"monthly\":\"Monthly\"}", "type": "string" }, "salary_currency": { "description": "The currency code for the salary (e.g., USD, EUR, RON). Visible only to users with manage salaries permission. Must be a 3-character currency code.", "type": "string" }, "salary": { "description": "The employee's salary amount. Visible only to users with manage salaries permission. Must be a positive number if provided.", "type": "integer" }, "sensitive_information": { "description": "Sensitive or confidential information about the employee. Optional text field with restricted access.", "type": "string" }, "weekly_hours_capacity": { "description": "The employee's weekly working hours capacity. Optional field. Must be between 0 and 168 hours if provided. Use 0 for overtime-only tracking (no expected weekly hours).", "minimum": 0, "maximum": 168, "type": "integer" }, "initial_vacation_balance": { "description": "The initial vacation days balance for the employee. Optional field. Must be a positive number if provided.", "type": "integer" }, "technical_evaluation_assignees": { "description": "Array of employee IDs who are assigned to perform technical evaluations for this employee. Optional field. All IDs must be valid employees from the same tenant.", "type": "array" }, "salary_evaluation_assignees": { "description": "Array of employee IDs who are assigned to perform salary evaluations for this employee. Optional field. All IDs must be valid employees from the same tenant.", "type": "array" }, "billed_rate": { "description": "The hourly rate at which the employee is billed to clients. Visible only to users with manage employees permission. Must be a positive number if provided.", "type": "integer" }, "internal_cost_hourly_rate": { "description": "The internal hourly cost rate for the employee. Visible only to users with manage employees permission. Must be a positive number if provided.", "type": "integer" }, "internal_cost_type": { "description": "The unit used to express the internal cost rate. Available values: hourly, monthly. Null is treated as hourly. Visible only to users with manage employees permission.", "type": "string" }, "internal_cost_monthly_rate": { "description": "The internal monthly cost for the employee, converted to an hourly equivalent using the weekly hours capacity. Required when internal_cost_type is monthly. Visible only to users with manage employees permission.", "minimum": 0, "type": "number" }, "position_code": { "description": "An internal code or reference for the employee's position. Optional field with maximum 50 characters.", "type": "string" }, "gender": { "description": "The employee's gender. Optional field.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmployeeResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "employees-destroy", "summary": "Delete an employee", "tags": [ "Employees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/employees/getters/export": { "get": { "operationId": "employees-getter-export", "summary": "Export", "description": "Export the monthly presence (timesheet) report as an Excel or CSV file. Returns a temporary signed download URL valid for 30 minutes that can be passed to email or chat tools. Defaults to the previous full month when no date range is provided. Requires the manageEmployees permission.", "tags": [ "Time Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/employees/getters/employee-capacity": { "get": { "operationId": "employees-getter-employee-capacity", "summary": "Employee capacity", "description": "Compute working-capacity numbers for employees over a date range: total workdays, days off (holidays), weekly capacity and available hours, accounting for national holidays. Payload: start_date and end_date (required dates), optional employee_ids (array of employee ULIDs to limit the calculation) and optional project_id (ULID) to scope capacity to the members of a project. Use to plan availability and staffing, e.g. how many hours a team can deliver in a period.", "tags": [ "People Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/employees/getters/timesheet": { "get": { "operationId": "employees-getter-timesheet", "summary": "Timesheet", "description": "Return a per-employee timesheet report for a period: each active employee with worked hours/minutes, available (expected) hours, billed rate and profitability. Payload: date (optional \"YYYY-MM-DD,YYYY-MM-DD\" start,end range, defaulting to the current month), optional client_id (ULID) to restrict worked time to a single client, and page/perPage for pagination. Use to review how much time the team logged versus their capacity, and the resulting billing and profitability.", "tags": [ "Time Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/employees/getters/employee-projects": { "get": { "operationId": "employees-getter-employee-projects", "summary": "Employee projects", "description": "List the projects a given employee is assigned to, including each project's name, client name, logo and the assignment pivot data (weekly_allocation_hours, archived_at, and billed_rate/currency when the caller may see billing). Payload: employee_id (required employee ULID). Allowed for users with manageEmployees or manageProjectAssignments, or for the employee viewing their own assignments. Use to see a team member's project allocations.", "tags": [ "Employees" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/employees/getters/hr-analytics": { "get": { "operationId": "employees-getter-hr-analytics", "summary": "Hr analytics", "description": "", "tags": [ "People Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/employees/{id}/actions": { "post": { "operationId": "employees-record-actions", "summary": "Actions: archive, unarchive, import-employees, ...", "description": "Perform an action on a single employee. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`archive`** - Archives (soft-deactivates) a single employee, identified by the repository record the action is invoked on. Archiving frees the employee's seat in the tenant subscription and removes them from active listings without deleting their historical data. Takes no payload beyond the target employee. The action is blocked when the caller lacks the `archive` ability, when there is no active tenant, or when the caller attempts to archive their own employee record. Call this when a user should be deactivated (e.g. they left the company) but their records must be preserved; use the `unarchive` action to reverse it.\n- **`unarchive`** - Reactivates a previously archived employee, restoring them to the active workforce. Expects a payload with `employee_id` (the ULID of the target Employee to unarchive). Because a reactivated employee re-occupies a subscription seat, the action fails with a 403 when the tenant has no available seats remaining, prompting the user to increase their plan; it also requires an active tenant and the `unarchive` ability on the target employee. Call this to bring back an employee who was archived by the `archive` action.\n- **`import-employees`** - Bulk-create employees by uploading an Excel/CSV spreadsheet (payload key \"file\"). Each row must include email, first_name, last_name, contract_type, start_date and weekly_hours_capacity; rows missing a required value or whose email already exists are skipped. Creation runs asynchronously via a queued job, so the response confirms the import started rather than returning the created records. Pass import_availalble=true to import only as many rows as there are available seats instead of failing when the file exceeds the seat count. Requires the manageEmployees permission.\n- **`download-template`** - Download the example Excel template that shows the columns expected by the employee bulk-import action (import-employees). Takes no payload and returns the .xlsx file for download. Requires the manageEmployees permission. Use this to obtain the correct spreadsheet format before importing employees.\n- **`generate-documents`** - Generate documents for this specific employee from one or more document templates, filling the template placeholders with the employee's data. Payload: template_ids (required array of template IDs; each must be a template applicable to employees). Creates Document records attached to the employee and returns the employee's documents relation. Requires the manageDocuments permission. Use to produce contracts, letters or other paperwork for a team member.\n- **`create-employee-from-identity-card`** - Creates a new employee by running AI vision OCR over an uploaded identity-card document. Expects a `files` payload: an array of one or more uploaded files (jpg, jpeg, png, or pdf, each max 10 MB) containing the ID card. The action extracts first name, last name, birth date, ID card number, personal identification number, and address from the document, creates the Employee record (defaulting to a 40-hour weekly capacity) and assigns the default `employee` role to the linked user. It requires an active tenant, the tenant to have AI access enabled, and the caller to hold the `manageEmployees` permission. Call this to onboard an employee automatically from a scanned ID instead of typing the fields by hand.\n- **`attach-projects`** - Assign one or more projects to this employee without removing existing assignments (idempotent attach). Payload: project_ids (required array of project ULIDs), and optional billed_rate (numeric), currency (3-letter code, e.g. EUR) and weekly_allocation_hours applied as pivot data on every attached project. Requires the manageEmployees or manageProjectAssignments permission. Use when staffing a team member onto projects.\n- **`upload-base64-document`** - Upload a document file for an employee from a base64-encoded payload, for MCP/API clients that cannot send multipart file uploads. Payload: file (required base64 string, raw or data-URI, max 20 MB), file_name (required, with extension), type_id (required document-type ID), and optional name, start_date, end_date and employee_id. Creates a Document record and returns its details. Any authenticated employee may upload for themselves; targeting a different employee_id requires the manageDocuments permission (callers without it always upload to their own profile). Use this to attach a PDF or similar file to a team member.\n- **`create-upload-url`** - Start a large-file upload for an employee document without sending the bytes through the model. This is step 1 of a 3-step flow: (1) call this action with file_name and type_id (optionally employee_id, client_id, name, start_date, end_date) to receive an upload_url and upload_token; (2) PUT the raw file bytes to upload_url exactly once (method PUT, using the returned headers); send a Content-Type header matching the file (e.g. application/pdf) so it is recorded on the stored object, though the server sniffs the real mime from the stored bytes regardless of what you send; (3) call the finalize-upload action with the upload_token to create the document. Only office/document/image types are accepted and the file must be 20 MB or smaller. Optionally pass sha256 and size so finalize can verify the stored bytes.\n- **`finalize-upload`** - Finalize a pre-signed employee document upload: pass the upload_token returned by create-upload-url after you have PUT the file bytes to the upload_url. Creates and returns the document.", "tags": [ "Employees" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "archive", "unarchive", "import-employees", "download-template", "generate-documents", "create-employee-from-identity-card", "attach-projects", "upload-base64-document", "create-upload-url", "finalize-upload" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "archive", "type": "object", "properties": {} }, { "title": "unarchive", "type": "object", "properties": {} }, { "title": "import-employees", "type": "object", "properties": { "file": { "description": "This field is required", "type": "string" }, "import_availalble": { "description": "Must be a boolean (true/false)", "type": "boolean" } } }, { "title": "download-template", "type": "object", "properties": {} }, { "title": "generate-documents", "type": "object", "properties": {} }, { "title": "create-employee-from-identity-card", "type": "object", "properties": {} }, { "title": "attach-projects", "type": "object", "properties": { "project_ids": { "description": "Must be an array", "type": "array" }, "project_ids.*": { "type": "string" }, "billed_rate": { "description": "Minimum value: 0", "minimum": 0, "type": "number" }, "currency": { "description": "Must be exactly 3 characters", "minLength": 3, "maxLength": 3, "type": "string" }, "weekly_allocation_hours": { "description": "Minimum value: 0", "minimum": 0, "type": "number" } } }, { "title": "upload-base64-document", "type": "object", "properties": { "file": { "description": "This field is required", "type": "string" }, "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "type_id": { "description": "Must exist in the database", "type": "string" }, "employee_id": { "description": "Must exist in the database", "type": "string" }, "name": { "type": "string" }, "start_date": { "description": "This field is optional", "type": "string" }, "end_date": { "description": "This field is optional", "type": "string" } } }, { "title": "create-upload-url", "type": "object", "properties": { "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "type_id": { "description": "Must exist in the database", "type": "string" }, "employee_id": { "description": "Must exist in the database", "type": "string" }, "client_id": { "description": "Must exist in the database", "type": "string" }, "name": { "type": "string" }, "start_date": { "description": "This field is optional", "type": "string" }, "end_date": { "description": "This field is optional", "type": "string" }, "sha256": { "description": "This field is optional", "type": "string" }, "size": { "description": "Maximum value: 20971520", "minimum": 1, "maximum": 20971520, "type": "integer" } } }, { "title": "finalize-upload", "type": "object", "properties": { "upload_token": { "description": "This field is required", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/departments": { "get": { "operationId": "departments-index", "summary": "List departments", "description": "Manages organizational departments (the departments table), the tenant-scoped top level of the company org structure. A department has many positions and many directions (its sub-groups), and employees are assigned to a department. Use this repository to list, search by name, and inspect departments and their nested positions/directions; it is the parent of the Direction repository and is referenced when categorizing employees or positions.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of departments per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- positions (fields: department_id, description, id, is_used, name)\n- directions (fields: department_id, description, is_used, name)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=positions,directions (include all fields)\n- include=positions[department_id,description] (selective fields with comma syntax)\n- include=positions[department_id|description] (selective fields with pipe syntax)\n- include=positions.posts (nested relationship - all fields)\n- include=positions[name].posts[title] (nested with field selection at each level)\n- include=positions[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=positions.posts[title],positions.comments[body] (multiple nested from same parent)\n- include=positions[name],directions[id] (multiple relationships with field selection)\n- include=positions[email|name].posts[title],directions[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter departments by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the departments. Available options: name (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Filter departments resource. Description: This is a exact match for direction (e.g., direction=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -direction=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DepartmentResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 7, "path": "https://demo.growee.test/api/restify/departments", "per_page": 1, "to": 1, "total": 7 }, "links": { "first": "https://demo.growee.test/api/restify/departments?page=1", "next": "https://demo.growee.test/api/restify/departments?page=2", "path": "https://demo.growee.test/api/restify/departments", "prev": null, "filters": "/api/restify/departments/filters" }, "data": [ { "id": "01kwt1xn9ta35wymj4dpbmrcgr", "type": "departments", "attributes": { "name": "People & Culture", "description": "Recruitment, onboarding and employee wellbeing", "is_used": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "departments-store", "summary": "Create a department", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The department name, e.g. \"Engineering\" or \"Sales\". Required plain string, unique per tenant in practice.", "type": "string" }, "description": { "description": "Optional free-text description of the department's purpose or scope. Nullable string.", "type": "string" } } }, "example": { "name": "People & Culture", "description": "Recruitment, onboarding and employee wellbeing" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepartmentResource" } } }, "example": { "data": { "id": "01kwt1xn9ta35wymj4dpbmrcgr", "type": "departments", "attributes": { "name": "People & Culture", "description": "Recruitment, onboarding and employee wellbeing", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/departments/{id}": { "get": { "operationId": "departments-show", "summary": "Retrieve a department", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The department ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Department detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepartmentResource" } } }, "example": { "data": { "id": "01kwt1xn9ta35wymj4dpbmrcgr", "type": "departments", "attributes": { "name": "People & Culture", "description": "Recruitment, onboarding and employee wellbeing", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "departments-update", "summary": "Update a department", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The department ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The department name, e.g. \"Engineering\" or \"Sales\". Required plain string, unique per tenant in practice.", "type": "string" }, "description": { "description": "Optional free-text description of the department's purpose or scope. Nullable string.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepartmentResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "departments-destroy", "summary": "Delete a department", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The department ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/positions": { "get": { "operationId": "positions-index", "summary": "List positions", "description": "Manages the job positions (the `positions` table) defined within the tenant company: the titles/roles that employees hold (e.g. \"Frontend Developer\", \"Accountant\") and that are referenced during performance evaluations. Each position optionally belongs to a department and tracks whether it is currently in use by any employee or evaluation. Use this tool to list or search the available positions before assigning one to an employee, or to create a new position title. Positions cannot be updated via MCP, and one that is attached to employees cannot be deleted.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of positions per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- department (fields: description, is_used, name)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=department (include all fields)\n- include=department[description,is_used] (selective fields with comma syntax)\n- include=department[description|is_used] (selective fields with pipe syntax)\n- include=department.posts (nested relationship - all fields)\n- include=department[name].posts[title] (nested with field selection at each level)\n- include=department[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=department.posts[title],department.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter positions by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the positions. Available options: positions.id (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter positions resource. Description: This is a exact match for department_id (e.g., department_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -department_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 24, "path": "https://demo.growee.test/api/restify/positions", "per_page": 1, "to": 1, "total": 24 }, "links": { "first": "https://demo.growee.test/api/restify/positions?page=1", "next": "https://demo.growee.test/api/restify/positions?page=2", "path": "https://demo.growee.test/api/restify/positions", "prev": null, "filters": "/api/restify/positions/filters" }, "data": [ { "id": "01kwt1xna0c29qbxm2y54q9kej", "type": "positions", "attributes": { "id": "01kwt1xna0c29qbxm2y54q9kej", "name": "Performance Review Coordinator", "description": "Keeps the evaluation pipeline on schedule", "department_id": "01kwt1xn9ta35wymj4dpbmrcgr", "is_used": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "positions-store", "summary": "Create a position", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The title of the job position, e.g. \"Senior Backend Developer\"; this is the human-facing name shown when assigning the position to an employee.", "type": "string" }, "description": { "description": "Optional free-text description of the position's responsibilities or scope.", "type": "string" }, "department_id": { "description": "Optional ULID foreign key referencing the department this position belongs to (the DepartmentRepository / departments table); null if the position is not tied to a department.", "type": "string" } } }, "example": { "name": "Performance Review Coordinator", "description": "Keeps the evaluation pipeline on schedule", "department_id": "01kwt1xn9ta35wymj4dpbmrcgr" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PositionResource" } } }, "example": { "data": { "id": "01kwt1xna0c29qbxm2y54q9kej", "type": "positions", "attributes": { "id": "01kwt1xna0c29qbxm2y54q9kej", "name": "Performance Review Coordinator", "description": "Keeps the evaluation pipeline on schedule", "department_id": "01kwt1xn9ta35wymj4dpbmrcgr", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/positions/{id}": { "get": { "operationId": "positions-show", "summary": "Retrieve a position", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The position ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Position detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PositionResource" } } }, "example": { "data": { "id": "01kwt1xna0c29qbxm2y54q9kej", "type": "positions", "attributes": { "id": "01kwt1xna0c29qbxm2y54q9kej", "name": "Performance Review Coordinator", "description": "Keeps the evaluation pipeline on schedule", "department_id": "01kwt1xn9ta35wymj4dpbmrcgr", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "positions-update", "summary": "Update a position", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The position ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The title of the job position, e.g. \"Senior Backend Developer\"; this is the human-facing name shown when assigning the position to an employee.", "type": "string" }, "description": { "description": "Optional free-text description of the position's responsibilities or scope.", "type": "string" }, "department_id": { "description": "Optional ULID foreign key referencing the department this position belongs to (the DepartmentRepository / departments table); null if the position is not tied to a department.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PositionResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "positions-destroy", "summary": "Delete a position", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The position ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/levels": { "get": { "operationId": "levels-index", "summary": "List levels", "description": "Levels are the tenant-scoped catalog of employee seniority/career tiers (rows in the levels table), such as \"Junior\", \"Mid\", \"Senior\" or \"Lead\". Each level is soft-deletable, can be assigned to many employees, and is referenced by evaluations to capture level-before/level-after changes (promotions). Use this repository to list or search seniority tiers when assigning them to employees or recording a level change in an evaluation, and to check whether a level is currently in use before deleting it.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of levels per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter levels by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the levels. Available options: name, description (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter levels resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LevelResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 7, "path": "https://demo.growee.test/api/restify/levels", "per_page": 1, "to": 1, "total": 7 }, "links": { "first": "https://demo.growee.test/api/restify/levels?page=1", "next": "https://demo.growee.test/api/restify/levels?page=2", "path": "https://demo.growee.test/api/restify/levels", "prev": null, "filters": "/api/restify/levels/filters" }, "data": [ { "id": "01kwt1xna4m4x9fy7ga1vyhga9", "type": "levels", "attributes": { "id": "01kwt1xna4m4x9fy7ga1vyhga9", "name": "C-Level", "description": "Level for top executive leadership", "created_at": "2026-07-05T21:11:03.000000Z", "is_used": false } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "levels-store", "summary": "Create a level", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the seniority level, e.g. \"Junior\", \"Mid\", \"Senior\" or \"Lead\". Required on create; unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this seniority level means or the expectations at this tier. Nullable string.", "type": "string" } }, "required": [ "name" ] }, "example": { "name": "C-Level", "description": "Level for top executive leadership" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LevelResource" } } }, "example": { "data": { "id": "01kwt1xna4m4x9fy7ga1vyhga9", "type": "levels", "attributes": { "id": "01kwt1xna4m4x9fy7ga1vyhga9", "name": "C-Level", "description": "Level for top executive leadership", "created_at": "2026-07-05T21:11:03.000000Z", "is_used": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/levels/{id}": { "get": { "operationId": "levels-show", "summary": "Retrieve a level", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The level ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Level detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LevelResource" } } }, "example": { "data": { "id": "01kwt1xna4m4x9fy7ga1vyhga9", "type": "levels", "attributes": { "id": "01kwt1xna4m4x9fy7ga1vyhga9", "name": "C-Level", "description": "Level for top executive leadership", "created_at": "2026-07-05T21:11:03.000000Z", "is_used": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "levels-update", "summary": "Update a level", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The level ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the seniority level, e.g. \"Junior\", \"Mid\", \"Senior\" or \"Lead\". Required on create; unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this seniority level means or the expectations at this tier. Nullable string.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LevelResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "levels-destroy", "summary": "Delete a level", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The level ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/directions": { "get": { "operationId": "directions-index", "summary": "List directions", "description": "Manages organizational directions (the directions table), tenant-scoped sub-groups that sit one level below a department in the company org structure (a department has many directions). Each direction belongs to exactly one department and is used to organize employees/positions more granularly. Use this repository to list, search by name, and inspect directions; it is a sibling of the Department repository (parent) and is referenced when categorizing employees.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of directions per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- department (fields: description, is_used, name)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=department (include all fields)\n- include=department[description,is_used] (selective fields with comma syntax)\n- include=department[description|is_used] (selective fields with pipe syntax)\n- include=department.posts (nested relationship - all fields)\n- include=department[name].posts[title] (nested with field selection at each level)\n- include=department[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=department.posts[title],department.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter directions by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the directions. Available options: name (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter directions resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectionResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 }, "links": { "first": "https://your-company.growee.net/api/restify/directions?page=1", "prev": null, "next": null }, "data": [ { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "directions", "attributes": { "name": "string", "description": "string", "department_id": "01jz9x8p4a3vn4dxyp71zsakqm", "is_used": false } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "directions-store", "summary": "Create a direction", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The direction name, e.g. \"Frontend\" or \"Recruiting\". Required plain string, unique within its department in practice.", "type": "string" }, "description": { "description": "Optional free-text description explaining what this direction covers. Nullable string.", "type": "string" }, "department_id": { "description": "ULID foreign key to the parent department (Department model / DepartmentRepository) this direction belongs to. Required.", "type": "string" } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectionResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "directions", "attributes": { "name": "string", "description": "string", "department_id": "01jz9x8p4a3vn4dxyp71zsakqm", "is_used": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/directions/{id}": { "get": { "operationId": "directions-show", "summary": "Retrieve a direction", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The direction ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Direction detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectionResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "directions", "attributes": { "name": "string", "description": "string", "department_id": "01jz9x8p4a3vn4dxyp71zsakqm", "is_used": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "directions-update", "summary": "Update a direction", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The direction ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The direction name, e.g. \"Frontend\" or \"Recruiting\". Required plain string, unique within its department in practice.", "type": "string" }, "description": { "description": "Optional free-text description explaining what this direction covers. Nullable string.", "type": "string" }, "department_id": { "description": "ULID foreign key to the parent department (Department model / DepartmentRepository) this direction belongs to. Required.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectionResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "directions-destroy", "summary": "Delete a direction", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The direction ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/work-locations": { "get": { "operationId": "work-locations-index", "summary": "List work locations", "description": "Manages work locations (the work_locations table), tenant-scoped named places (offices, remote, on-site) that employees are associated with via a many-to-many relationship. Use this repository to list, search by name, and inspect the locations available for employee assignment; it feeds employee profile and reporting features that group people by where they work.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of work-locations per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter work-locations by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the work-locations. Available options: name (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter work-locations resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLocationResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 2, "path": "https://demo.growee.test/api/restify/work-locations", "per_page": 1, "to": 1, "total": 2 }, "links": { "first": "https://demo.growee.test/api/restify/work-locations?page=1", "next": "https://demo.growee.test/api/restify/work-locations?page=2", "path": "https://demo.growee.test/api/restify/work-locations", "prev": null, "filters": "/api/restify/work-locations/filters" }, "data": [ { "id": "01kwt1y3ee85bd43h11s5rqvp7", "type": "work_locations", "attributes": { "name": "Remote", "description": "Fully remote, EU time zones" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "work-locations-store", "summary": "Create a work location", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The work location name, e.g. \"Cluj Office\" or \"Remote\". Required plain string, unique per tenant in practice.", "type": "string" }, "description": { "description": "Optional free-text description with details such as address or notes about the location. Nullable string.", "type": "string" } } }, "example": { "name": "Remote", "description": "Fully remote, EU time zones" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkLocationResource" } } }, "example": { "data": { "id": "01kwt1y3ee85bd43h11s5rqvp7", "type": "work_locations", "attributes": { "name": "Remote", "description": "Fully remote, EU time zones" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/work-locations/{id}": { "get": { "operationId": "work-locations-show", "summary": "Retrieve a work location", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The work location ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Work location detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkLocationResource" } } }, "example": { "data": { "id": "01kwt1y3ee85bd43h11s5rqvp7", "type": "work_locations", "attributes": { "name": "Remote", "description": "Fully remote, EU time zones" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "work-locations-update", "summary": "Update a work location", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The work location ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The work location name, e.g. \"Cluj Office\" or \"Remote\". Required plain string, unique per tenant in practice.", "type": "string" }, "description": { "description": "Optional free-text description with details such as address or notes about the location. Nullable string.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkLocationResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "work-locations-destroy", "summary": "Delete a work location", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The work location ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-types": { "get": { "operationId": "contract-types-index", "summary": "List contract types", "description": "Contract types define the catalog of employment-contract categories available in the current tenant (rows in the contract_types table), such as \"Full-time\", \"Part-time\", \"B2B\" or \"Internship\". Each contract type is a tenant-scoped, soft-deletable lookup value referenced by employee records to describe how a person is employed. Use this repository to list the available contract types when creating or editing employees, or to present the set of employment-contract options to the user.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of contract-types per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter contract-types by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the contract-types. Available options: contract_types.id (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter contract-types resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTypeResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 4, "path": "https://demo.growee.test/api/restify/contract-types", "per_page": 1, "to": 1, "total": 4 }, "links": { "first": "https://demo.growee.test/api/restify/contract-types?page=1", "next": "https://demo.growee.test/api/restify/contract-types?page=2", "path": "https://demo.growee.test/api/restify/contract-types", "prev": null, "filters": "/api/restify/contract-types/filters" }, "data": [ { "id": "01kdj6d46r3cwfe229d8sfgkne", "type": "contract_types", "attributes": { "id": "01kdj6d46r3cwfe229d8sfgkne", "name": "b2b_paid_holidays", "heading": "B2B Paid Holidays" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "contract-types-store", "summary": "Create a contract type", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable label of the employment-contract category, e.g. \"Full-time\", \"Part-time\", \"B2B\" or \"Internship\". Free-text string, unique per tenant by convention.", "type": "string" }, "heading": { "description": "Read-only display heading derived from the name (title-cased headline form of \"name\"). Used purely for presentation; it is not stored and defaults from the name when omitted.", "type": "string" } } }, "example": { "name": "b2b_paid_holidays", "heading": "B2B Paid Holidays" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContractTypeResource" } } }, "example": { "data": { "id": "01kdj6d46r3cwfe229d8sfgkne", "type": "contract_types", "attributes": { "id": "01kdj6d46r3cwfe229d8sfgkne", "name": "b2b_paid_holidays", "heading": "B2B Paid Holidays" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/contract-types/{id}": { "get": { "operationId": "contract-types-show", "summary": "Retrieve a contract type", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contract type ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contract type detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContractTypeResource" } } }, "example": { "data": { "id": "01kdj6d46r3cwfe229d8sfgkne", "type": "contract_types", "attributes": { "id": "01kdj6d46r3cwfe229d8sfgkne", "name": "b2b_paid_holidays", "heading": "B2B Paid Holidays" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "contract-types-update", "summary": "Update a contract type", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contract type ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable label of the employment-contract category, e.g. \"Full-time\", \"Part-time\", \"B2B\" or \"Internship\". Free-text string, unique per tenant by convention.", "type": "string" }, "heading": { "description": "Read-only display heading derived from the name (title-cased headline form of \"name\"). Used purely for presentation; it is not stored and defaults from the name when omitted.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContractTypeResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "contract-types-destroy", "summary": "Delete a contract type", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contract type ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/evaluation-types": { "get": { "operationId": "evaluation-types-index", "summary": "List evaluation types", "description": "Evaluation types are the tenant-scoped catalog of performance-review categories (rows in the evaluation_types table), such as \"Annual review\", \"Probation review\" or \"Quarterly check-in\". Each type is soft-deletable and has many evaluations attached via the type_id foreign key. Use this repository to list or search available review categories when creating evaluations in EvaluationRepository, and to determine which categories are in use before deleting them.", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of evaluation-types per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter evaluation-types by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the evaluation-types. Available options: evaluation_types.id (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter evaluation-types resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationTypeResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 3, "path": "https://demo.growee.test/api/restify/evaluation-types", "per_page": 1, "to": 1, "total": 3 }, "links": { "first": "https://demo.growee.test/api/restify/evaluation-types?page=1", "next": "https://demo.growee.test/api/restify/evaluation-types?page=2", "path": "https://demo.growee.test/api/restify/evaluation-types", "prev": null, "filters": "/api/restify/evaluation-types/filters" }, "data": [ { "id": "01kwt1xna5sbgeq72pcv52r30g", "type": "evaluation_types", "attributes": { "id": "01kwt1xna5sbgeq72pcv52r30g", "name": "Probation Review", "description": "End-of-probation evaluation for new hires", "is_used": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "evaluation-types-store", "summary": "Create an evaluation type", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the evaluation/review category, e.g. \"Annual review\" or \"Probation review\". Required free-text string, unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional longer free-text explanation of what this review category covers. Nullable.", "type": "string" } }, "required": [ "name" ] }, "example": { "name": "Probation Review", "description": "End-of-probation evaluation for new hires" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvaluationTypeResource" } } }, "example": { "data": { "id": "01kwt1xna5sbgeq72pcv52r30g", "type": "evaluation_types", "attributes": { "id": "01kwt1xna5sbgeq72pcv52r30g", "name": "Probation Review", "description": "End-of-probation evaluation for new hires", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/evaluation-types/{id}": { "get": { "operationId": "evaluation-types-show", "summary": "Retrieve an evaluation type", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The evaluation type ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Evaluation type detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvaluationTypeResource" } } }, "example": { "data": { "id": "01kwt1xna5sbgeq72pcv52r30g", "type": "evaluation_types", "attributes": { "id": "01kwt1xna5sbgeq72pcv52r30g", "name": "Probation Review", "description": "End-of-probation evaluation for new hires", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "evaluation-types-update", "summary": "Update an evaluation type", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The evaluation type ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the evaluation/review category, e.g. \"Annual review\" or \"Probation review\". Required free-text string, unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional longer free-text explanation of what this review category covers. Nullable.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvaluationTypeResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "evaluation-types-destroy", "summary": "Delete an evaluation type", "tags": [ "Organization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The evaluation type ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/benefits": { "get": { "operationId": "benefits-index", "summary": "List benefits", "description": "Manages the tenant's catalogue of employee benefits (the \"benefits\" table): reusable perk definitions such as gym memberships, meal vouchers, health insurance or bonuses that can be granted to employees. Each row stores a title, optional description, a recurrence cadence, and an optional monetary amount plus currency. Use this to list, search (by title/description), or filter benefit definitions; the actual grant of a benefit to an individual employee lives in the separate employee-benefits relationship (EmployeeBenefit), not here.", "tags": [ "Benefits" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of benefits per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter benefits by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the benefits. Available options: title, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": false, "description": "Filter benefits resource. Description: This is a exact match for title (e.g., title=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -title=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "recurrence", "in": "query", "required": false, "description": "Filter benefits resource. Description: This is a exact match for recurrence (e.g., recurrence=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -recurrence=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenefitResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 5, "path": "https://demo.growee.test/api/restify/benefits", "per_page": 1, "to": 1, "total": 5 }, "links": { "first": "https://demo.growee.test/api/restify/benefits?page=1", "next": "https://demo.growee.test/api/restify/benefits?page=2", "path": "https://demo.growee.test/api/restify/benefits", "prev": null, "filters": "/api/restify/benefits/filters" }, "data": [ { "id": "01kwt1y3f22ya9m5ypmn6p7xy4", "type": "benefits", "attributes": { "title": "Home office setup", "description": "One-time budget for desk, chair and peripherals", "recurrence": "one_time", "amount": "500.00", "currency": "EUR", "is_demo": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "benefits-store", "summary": "Create a benefit", "tags": [ "Benefits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Human-readable name of the benefit as shown to employees (e.g. \"Gym membership\", \"Meal vouchers\"). Required, max 255 characters.", "maxLength": 255, "type": "string" }, "description": { "description": "Optional longer explanation of what the benefit includes or its eligibility terms. Free text, may be null.", "type": "string" }, "recurrence": { "description": "How often the benefit recurs. Allowed values: \"monthly\", \"quarterly\", \"yearly\", \"one_time\". Defaults to \"monthly\" when omitted.", "enum": [ "monthly", "quarterly", "yearly", "one_time" ], "type": "string" }, "amount": { "description": "Optional monetary value of the benefit per recurrence, as a non-negative decimal (2 decimal places). Interpreted in the currency given by the currency field.", "minimum": 0, "type": "string" }, "currency": { "description": "ISO currency code for the amount (e.g. \"EUR\", \"USD\", \"RON\"). Max 8 characters; may be null when no amount applies.", "maxLength": 8, "type": "string" } }, "required": [ "title" ] }, "example": { "title": "Home office setup", "description": "One-time budget for desk, chair and peripherals", "recurrence": "one_time", "amount": "500.00", "currency": "EUR" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BenefitResource" } } }, "example": { "data": { "id": "01kwt1y3f22ya9m5ypmn6p7xy4", "type": "benefits", "attributes": { "title": "Home office setup", "description": "One-time budget for desk, chair and peripherals", "recurrence": "one_time", "amount": "500.00", "currency": "EUR", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/benefits/{id}": { "get": { "operationId": "benefits-show", "summary": "Retrieve a benefit", "tags": [ "Benefits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The benefit ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Benefit detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BenefitResource" } } }, "example": { "data": { "id": "01kwt1y3f22ya9m5ypmn6p7xy4", "type": "benefits", "attributes": { "title": "Home office setup", "description": "One-time budget for desk, chair and peripherals", "recurrence": "one_time", "amount": "500.00", "currency": "EUR", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "benefits-update", "summary": "Update a benefit", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Benefits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The benefit ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Human-readable name of the benefit as shown to employees (e.g. \"Gym membership\", \"Meal vouchers\"). Required, max 255 characters.", "maxLength": 255, "type": "string" }, "description": { "description": "Optional longer explanation of what the benefit includes or its eligibility terms. Free text, may be null.", "type": "string" }, "recurrence": { "description": "How often the benefit recurs. Allowed values: \"monthly\", \"quarterly\", \"yearly\", \"one_time\". Defaults to \"monthly\" when omitted.", "enum": [ "monthly", "quarterly", "yearly", "one_time" ], "type": "string" }, "amount": { "description": "Optional monetary value of the benefit per recurrence, as a non-negative decimal (2 decimal places). Interpreted in the currency given by the currency field.", "minimum": 0, "type": "string" }, "currency": { "description": "ISO currency code for the amount (e.g. \"EUR\", \"USD\", \"RON\"). Max 8 characters; may be null when no amount applies.", "maxLength": 8, "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BenefitResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "benefits-destroy", "summary": "Delete a benefit", "tags": [ "Benefits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The benefit ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/employee-benefits": { "get": { "operationId": "employee-benefits-index", "summary": "List employee benefits", "description": "This repository manages employee benefits: the pivot linking an employee to a benefit for a given period, stored in the employee_benefits table. Each record ties one employee (relation \"employee\") to one benefit definition (relation \"benefit\", from the benefits repository) with an optional start_date and end_date. Use it to list, filter and manage which benefits a team member is enrolled in. Users without the manageBenefits permission only see their own benefit assignments; the benefit definitions themselves live in the benefits repository.", "tags": [ "Benefits" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of employee-benefits per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- benefit (fields: amount, currency, description, is_demo, recurrence, title)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,benefit (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],benefit[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],benefit[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter employee-benefits by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the employee-benefits. Available options: start_date, end_date, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter employee-benefits resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "benefit_id", "in": "query", "required": false, "description": "Filter employee-benefits resource. Description: This is a exact match for benefit_id (e.g., benefit_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -benefit_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Filter employee-benefits resource. Description: This is a date match for start_date (e.g., start_date=YYYY-MM-DD or start_date=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -start_date=YYYY-MM-DD or -start_date=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Filter employee-benefits resource. Description: This is a date match for end_date (e.g., end_date=YYYY-MM-DD or end_date=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -end_date=YYYY-MM-DD or -end_date=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeBenefitResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 111, "path": "https://demo.growee.test/api/restify/employee-benefits", "per_page": 1, "to": 1, "total": 111 }, "links": { "first": "https://demo.growee.test/api/restify/employee-benefits?page=1", "next": "https://demo.growee.test/api/restify/employee-benefits?page=2", "path": "https://demo.growee.test/api/restify/employee-benefits", "prev": null, "filters": "/api/restify/employee-benefits/filters" }, "data": [ { "id": "01kwt1y3hmwfrv9215f9ksk84r", "type": "employee_benefits", "attributes": { "employee_id": "01kwt1xrxry8ng0rnaw98gftvp", "benefit_id": "01kwt1y3f22ya9m5ypmn6p7xy4", "start_date": "2024-03-01T00:00:00.000000Z", "is_demo": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "employee-benefits-store", "summary": "Create an employee benefit", "tags": [ "Benefits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "The employee receiving the benefit. Required. ULID referencing the employees repository.", "type": "string" }, "benefit_id": { "description": "The benefit being assigned. Required. ULID referencing the benefits repository, which holds the benefit definition (name, type, value).", "type": "string" }, "start_date": { "description": "The date from which the benefit applies to the employee. Optional date (Y-m-d).", "type": "string" }, "end_date": { "description": "The date on which the benefit stops applying. Optional date (Y-m-d); must be on or after start_date.", "type": "string" } }, "required": [ "employee_id", "benefit_id" ] }, "example": { "employee_id": "01kwt1xrxry8ng0rnaw98gftvp", "benefit_id": "01kwt1y3f22ya9m5ypmn6p7xy4", "start_date": "2024-03-01T00:00:00.000000Z" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmployeeBenefitResource" } } }, "example": { "data": { "id": "01kwt1y3hmwfrv9215f9ksk84r", "type": "employee_benefits", "attributes": { "employee_id": "01kwt1xrxry8ng0rnaw98gftvp", "benefit_id": "01kwt1y3f22ya9m5ypmn6p7xy4", "start_date": "2024-03-01T00:00:00.000000Z", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/employee-benefits/{id}": { "get": { "operationId": "employee-benefits-show", "summary": "Retrieve an employee benefit", "tags": [ "Benefits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee benefit ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee benefit detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmployeeBenefitResource" } } }, "example": { "data": { "id": "01kwt1y3hmwfrv9215f9ksk84r", "type": "employee_benefits", "attributes": { "employee_id": "01kwt1xrxry8ng0rnaw98gftvp", "benefit_id": "01kwt1y3f22ya9m5ypmn6p7xy4", "start_date": "2024-03-01T00:00:00.000000Z", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "employee-benefits-update", "summary": "Update an employee benefit", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Benefits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee benefit ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "The employee receiving the benefit. Required. ULID referencing the employees repository.", "type": "string" }, "benefit_id": { "description": "The benefit being assigned. Required. ULID referencing the benefits repository, which holds the benefit definition (name, type, value).", "type": "string" }, "start_date": { "description": "The date from which the benefit applies to the employee. Optional date (Y-m-d).", "type": "string" }, "end_date": { "description": "The date on which the benefit stops applying. Optional date (Y-m-d); must be on or after start_date.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmployeeBenefitResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "employee-benefits-destroy", "summary": "Delete an employee benefit", "tags": [ "Benefits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The employee benefit ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/holidays": { "get": { "operationId": "holidays-index", "summary": "List holidays", "description": "Manages employee holiday / time-off requests (the holidays table), the core of Growee absence tracking. Each record ties an employee to a holiday policy (vacation, sick leave, unpaid, etc.) over a start_date-end_date range, tracks its lifecycle status (draft, approved, rejected, cancelled), the deducted working days (days_off), approver signatures, and any generated documents. Use this to list, search, filter and inspect who is off and when, and to create requests that then flow through the approve/reject/cancel actions. Balances and eligibility come from the linked holiday policy (see the holiday-policies repository); the approving manager and the requesting employee are Employee records (see the employees repository). Visibility is automatically scoped: managers see their reports, everyone else sees only their own requests.", "tags": [ "Leave" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of holidays per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- policy (fields: allow_advance_booking, applicable_contract_types, can_cancel_own_holidays_until_start_date, carry_over, days_per_year, description, document_template_path, document_template_path_name, id, is_used, method, milestones, name, paid, timesheet_symbol, type, waiting_period_days)\n- approver (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- documents (fields: client_id, content, created_at, description, documentable_type, employee_id, end_date, file_name, id, is_signed, name, path, signature_count, size, start_date, status, type_id)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,policy (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],policy[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],policy[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter holidays by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the holidays. Available options: start_date, end_date, approved_at, rejected_at, status, user_first_name, user_last_name, policy (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "holiday_policy_id", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for holiday_policy_id (e.g., holiday_policy_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -holiday_policy_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "is_demo", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for is_demo (e.g., is_demo=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -is_demo=some_value). The filter type is string.", "schema": { "type": "boolean" } }, { "name": "start_date", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for start_date (e.g., start_date=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -start_date=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for end_date (e.g., end_date=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -end_date=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "approved_at", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a range match for approved_at (e.g., approved_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -approved_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "rejected_at", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a range match for rejected_at (e.g., rejected_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -rejected_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for type (e.g., type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "paid", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for paid (e.g., paid=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -paid=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "department", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for department (e.g., department=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -department=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "work_location", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for work_location (e.g., work_location=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -work_location=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "active_employee", "in": "query", "required": false, "description": "Filter holidays resource. Description: This is a exact match for active_employee (e.g., active_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -active_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HolidayResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 90, "path": "https://demo.growee.test/api/restify/holidays", "per_page": 1, "to": 1, "total": 90 }, "links": { "first": "https://demo.growee.test/api/restify/holidays?page=1", "next": "https://demo.growee.test/api/restify/holidays?page=2", "path": "https://demo.growee.test/api/restify/holidays", "prev": null, "filters": "/api/restify/holidays/filters" }, "data": [ { "id": "01kwt1xsvnjsakwrx8f02acn94", "type": "holidays", "attributes": { "id": "01kwt1xsvnjsakwrx8f02acn94", "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "holiday_policy_id": "01kdj6d7q7hc3yzdrhsxdnwgfk", "requested_approver_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "start_date": "2026-08-21T00:00:00.000000Z", "end_date": "2026-08-27T00:00:00.000000Z", "notes": "Visiting family", "created_at": "2026-07-05T21:11:08.000000Z", "approved_at": "2026-08-11T00:00:00.000000Z", "status": "approved", "status_changed_by": "01kwt1xngg4wdqf7x6c7s3yzy3", "days_off": 5, "is_demo": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "holidays-store", "summary": "Create a holiday", "tags": [ "Leave" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID of the Employee this holiday belongs to (references the employees repository). When omitted on create it defaults to the current authenticated employee; only managers with the manageHolidays / manageHolidaysForDirectReports permission may set it to another employee.", "type": "string" }, "holiday_policy_id": { "description": "Required ULID of the HolidayPolicy that governs this request (references the holiday-policies repository). It determines the leave type (e.g. vacation, sick, unpaid), whether it is paid, the available balance, waiting periods, and which employee contract types may use it.", "type": "string" }, "requested_approver_id": { "description": "This can be null or not stored at all. It represents the id for the manager who would approve the holiday, but when creating do not send it", "type": "string" }, "start_date": { "description": "First calendar day of the requested absence, as a date (YYYY-MM-DD). Inclusive; combined with end_date it defines the leave range from which days_off is calculated.", "type": "string" }, "end_date": { "description": "Last calendar day of the requested absence, as a date (YYYY-MM-DD). Inclusive and must be on or after start_date; validated against the policy balance and against any overlapping request for the same employee.", "type": "string" }, "notes": { "description": "Optional free-text note the requester adds when submitting the holiday, e.g. the reason for the absence or handover details.", "type": "string" }, "status_explanation": { "description": "Optional free-text reason attached when the status changes, e.g. why a request was rejected or cancelled. Can be supplied by the approve/reject/cancel actions.", "type": "string" }, "document_path": { "description": "Uploaded holiday document file (e.g. a signed leave form) stored on the documents disk. Accepts a file upload; the original filename and size are captured into file_name and size.", "type": "string" }, "file_name": { "description": "Original filename of the uploaded holiday document, captured automatically from document_path.", "type": "string" } }, "required": [ "holiday_policy_id", "start_date", "end_date" ] }, "example": { "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "holiday_policy_id": "01kdj6d7q7hc3yzdrhsxdnwgfk", "requested_approver_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "start_date": "2026-08-21T00:00:00.000000Z", "end_date": "2026-08-27T00:00:00.000000Z", "notes": "Visiting family" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayResource" } } }, "example": { "data": { "id": "01kwt1xsvnjsakwrx8f02acn94", "type": "holidays", "attributes": { "id": "01kwt1xsvnjsakwrx8f02acn94", "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "holiday_policy_id": "01kdj6d7q7hc3yzdrhsxdnwgfk", "requested_approver_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "start_date": "2026-08-21T00:00:00.000000Z", "end_date": "2026-08-27T00:00:00.000000Z", "notes": "Visiting family", "created_at": "2026-07-05T21:11:08.000000Z", "approved_at": "2026-08-11T00:00:00.000000Z", "status": "approved", "status_changed_by": "01kwt1xngg4wdqf7x6c7s3yzy3", "days_off": 5, "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/holidays/{id}": { "get": { "operationId": "holidays-show", "summary": "Retrieve a holiday", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Holiday detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayResource" } } }, "example": { "data": { "id": "01kwt1xsvnjsakwrx8f02acn94", "type": "holidays", "attributes": { "id": "01kwt1xsvnjsakwrx8f02acn94", "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "holiday_policy_id": "01kdj6d7q7hc3yzdrhsxdnwgfk", "requested_approver_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "start_date": "2026-08-21T00:00:00.000000Z", "end_date": "2026-08-27T00:00:00.000000Z", "notes": "Visiting family", "created_at": "2026-07-05T21:11:08.000000Z", "approved_at": "2026-08-11T00:00:00.000000Z", "status": "approved", "status_changed_by": "01kwt1xngg4wdqf7x6c7s3yzy3", "days_off": 5, "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "holidays-update", "summary": "Update a holiday", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID of the Employee this holiday belongs to (references the employees repository). When omitted on create it defaults to the current authenticated employee; only managers with the manageHolidays / manageHolidaysForDirectReports permission may set it to another employee.", "type": "string" }, "holiday_policy_id": { "description": "Required ULID of the HolidayPolicy that governs this request (references the holiday-policies repository). It determines the leave type (e.g. vacation, sick, unpaid), whether it is paid, the available balance, waiting periods, and which employee contract types may use it.", "type": "string" }, "requested_approver_id": { "description": "This can be null or not stored at all. It represents the id for the manager who would approve the holiday, but when creating do not send it", "type": "string" }, "start_date": { "description": "First calendar day of the requested absence, as a date (YYYY-MM-DD). Inclusive; combined with end_date it defines the leave range from which days_off is calculated.", "type": "string" }, "end_date": { "description": "Last calendar day of the requested absence, as a date (YYYY-MM-DD). Inclusive and must be on or after start_date; validated against the policy balance and against any overlapping request for the same employee.", "type": "string" }, "notes": { "description": "Optional free-text note the requester adds when submitting the holiday, e.g. the reason for the absence or handover details.", "type": "string" }, "status_explanation": { "description": "Optional free-text reason attached when the status changes, e.g. why a request was rejected or cancelled. Can be supplied by the approve/reject/cancel actions.", "type": "string" }, "document_path": { "description": "Uploaded holiday document file (e.g. a signed leave form) stored on the documents disk. Accepts a file upload; the original filename and size are captured into file_name and size.", "type": "string" }, "file_name": { "description": "Original filename of the uploaded holiday document, captured automatically from document_path.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "holidays-destroy", "summary": "Delete a holiday", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/holidays/getters/days-off": { "get": { "operationId": "holidays-getter-days-off", "summary": "Days off", "description": "Compute the number of working days off between two dates, accounting for weekends and public/legal holidays. Use this to preview how many days a prospective absence would consume before creating a holiday request. Payload: start_date (required date) and end_date (required date, on or after start_date). Returns { days_off: number }.", "tags": [ "Leave" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/holidays/getters/esignature-url": { "get": { "operationId": "holidays-getter-esignature-url", "summary": "Esignature url", "description": "Retrieve the e-signature signing URL for a specific holiday, generated by the external e-signature provider for the approver of the request. Use this to redirect the approving manager to sign the holiday document. Returns { url: string }. Requires the holiday to already have an esign_request_id and an approver with an email.", "tags": [ "Leave" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/holidays/{id}/actions": { "post": { "operationId": "holidays-record-actions", "summary": "Actions: approve, reject, cancel, ...", "description": "Perform an action on a single holiday. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`approve`** - Approve a single pending holiday request (moves its status to approved, stamps approved_at and the approver signature, and may create the corresponding Google Calendar event). Call this on a specific holiday when a manager grants the requested time off. Requires the caller to be an organization employee with approve permission and fails if the holiday is already approved. Optional payload: status_explanation (string, max 255) to record a note for the approval.\n- **`reject`** - Reject a single pending holiday request (moves its status to rejected, stamps rejected_at and the rejector signature, and does not deduct any balance). Call this on a specific holiday when a manager declines the requested time off. Requires an employee with reject permission and fails if the holiday is already rejected. Optional payload: status_explanation (string, max 255) to record the reason for the rejection.\n- **`cancel`** - Cancel a single holiday request (moves its status to cancelled and deletes the associated Google Calendar event if one exists). Call this to withdraw a request; it cannot be cancelled if already cancelled or rejected. Employees may cancel their own draft or approved (before start date, when the policy allows) requests, while managers with the approveRejectHolidays permission can cancel any. Optional payload: status_explanation (string) to record why it was cancelled.\n- **`export`** - Export holiday requests to a downloadable spreadsheet file (xlsx or csv). Requires the manageHolidays permission and returns the generated file as a download rather than JSON. Payload: format (required, one of the HolidayExportFormatEnum values, e.g. xlsx); columns (required array selecting which HolidayExportColumnsEnum columns to include, e.g. name, type, status, status_changed_by_name); optional holiday_filters (employee_ids, start_date, paid, status) and range (start_date/end_date on created_at) to narrow the exported set. Rows are ordered by start_date ascending.\n- **`generate-documents`** - Generate document files for a specific holiday from one or more document templates (e.g. an official leave form), attaching the results as documents on the holiday and returning the related documents. Requires the manageDocuments permission. Payload: template_ids (required array of existing template ULIDs; each must be a template applicable to holidays).\n- **`create-upload-url`** - Start a large-file upload for a holiday request document without sending the bytes through the model. This is step 1 of a 3-step flow: (1) call this action with the holiday_id and file_name to receive an upload_url and upload_token; (2) PUT the raw file bytes to upload_url exactly once (method PUT, using the returned headers); send a Content-Type header matching the file (e.g. application/pdf) so it is recorded on the stored object, though the server sniffs the real mime from the stored bytes regardless of what you send; (3) call the finalize-upload action with the upload_token to attach the document to the holiday. Rejected if the holiday already has a signed document. Optionally pass sha256 and size so finalize can verify the stored bytes.\n- **`finalize-upload`** - Finalize a pre-signed holiday document upload: pass the upload_token returned by create-upload-url after you have PUT the file bytes to the upload_url. Attaches the document to the holiday and returns it.", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "approve", "reject", "cancel", "export", "generate-documents", "create-upload-url", "finalize-upload" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "approve", "type": "object", "properties": { "status_explanation": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" } } }, { "title": "reject", "type": "object", "properties": { "status_explanation": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" } } }, { "title": "cancel", "type": "object", "properties": {} }, { "title": "export", "type": "object", "properties": { "format": { "description": "Must be one of: xlsx, csv", "enum": [ "xlsx", "csv" ], "type": "string" }, "columns": { "description": "Must be an array", "type": "array" }, "holiday_filters": { "description": "Must be an array", "type": "array" }, "holiday_filters.paid": { "type": "string" }, "holiday_filters.employee_ids": { "type": "string" }, "holiday_filters.start_date": { "type": "string" }, "holiday_filters.status": { "type": "string" }, "range": { "description": "Must be an array", "type": "array" }, "range.start_date": { "type": "string" }, "range.end_date": { "type": "string" } } }, { "title": "generate-documents", "type": "object", "properties": {} }, { "title": "create-upload-url", "type": "object", "properties": { "holiday_id": { "description": "Maximum length: 26 characters", "maxLength": 26, "type": "string" }, "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "sha256": { "description": "This field is optional", "type": "string" }, "size": { "description": "Maximum value: 20971520", "minimum": 1, "maximum": 20971520, "type": "integer" } } }, { "title": "finalize-upload", "type": "object", "properties": { "upload_token": { "description": "This field is required", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/holiday-balances": { "get": { "operationId": "holiday-balances-index", "summary": "List holiday balances", "description": "Tracks the leave allowance ledger: one row per employee, per holiday policy, per calendar year, storing how many days were originally granted (initial_balance) and how many remain (balance). It is the source of truth for \"how many vacation/leave days does this person have left\" and is consumed when approving holiday requests. Each row belongs to an Employee and a HolidayPolicy (which defines the day count, accrual method and rules). Use this repository to list or search an employee's remaining days; filter by employee_id, holiday_policy_id or year, and use the available-balance getter for a single employee/policy lookup. Balances are normally maintained automatically by the accrual engine rather than edited by hand.", "tags": [ "Leave" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of holiday-balances per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- holidayPolicy (fields: allow_advance_booking, applicable_contract_types, can_cancel_own_holidays_until_start_date, carry_over, days_per_year, description, document_template_path, document_template_path_name, id, is_used, method, milestones, name, paid, timesheet_symbol, type, waiting_period_days)\n- policy (fields: allow_advance_booking, applicable_contract_types, can_cancel_own_holidays_until_start_date, carry_over, days_per_year, description, document_template_path, document_template_path_name, id, is_used, method, milestones, name, paid, timesheet_symbol, type, waiting_period_days)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,holidayPolicy (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],holidayPolicy[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],holidayPolicy[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter holiday-balances by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the holiday-balances. Available options: employee_id, holiday_policy_id, balance (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter holiday-balances resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "holiday_policy_id", "in": "query", "required": false, "description": "Filter holiday-balances resource. Description: This is a exact match for holiday_policy_id (e.g., holiday_policy_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -holiday_policy_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Filter holiday-balances resource. Description: This is a exact match for year (e.g., year=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -year=some_value). The filter type is string.", "schema": { "type": "integer" } }, { "name": "active_employee", "in": "query", "required": false, "description": "Filter holiday-balances resource. Description: This is a exact match for active_employee (e.g., active_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -active_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "with_trashed", "in": "query", "required": false, "description": "Filter holiday-balances resource. Description: This is a exact match for with_trashed (e.g., with_trashed=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -with_trashed=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HolidayBalanceResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 404, "path": "https://demo.growee.test/api/restify/holiday-balances", "per_page": 1, "to": 1, "total": 404 }, "links": { "first": "https://demo.growee.test/api/restify/holiday-balances?page=1", "next": "https://demo.growee.test/api/restify/holiday-balances?page=2", "path": "https://demo.growee.test/api/restify/holiday-balances", "prev": null, "filters": "/api/restify/holiday-balances/filters" }, "data": [ { "id": "01kwt1xszeqnxvesbrwc9kzfgs", "type": "holiday_balances", "attributes": { "employee_id": "01kwt1xq6x2v5zdbnqzsk7rbd0", "holiday_policy_id": "01kdj6d7qyd12ye094esbtej2r", "balance": 0, "year": "2026", "initial_balance": 5 } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "holiday-balances-store", "summary": "Create a holiday balance", "tags": [ "Leave" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "holiday_policy_id": { "description": "ULID foreign key to the HolidayPolicy (HolidayPolicyRepository) this balance is measured against, e.g. paid vacation or sick leave. Together with employee_id and year it uniquely identifies the balance.", "type": "string" }, "balance": { "description": "Remaining leave days currently available to the employee under this policy for the given year (float, in days; decimals allowed for accrual-based policies). Decreases as holidays are approved and increases with accrual or manual credit.", "type": "integer" }, "year": { "description": "Calendar year (four-digit integer, e.g. 2026) this balance applies to. A new row exists per year because allowances reset annually.", "type": "string" }, "initial_balance": { "description": "The full allowance of days originally granted for the year before any holidays were taken (float, in days). Used as the baseline for reporting how many days were consumed versus remaining.", "type": "integer" }, "deleted_at": { "description": "Soft-delete timestamp; when set, the balance is archived and excluded from active queries unless the with_trashed matcher is used.", "type": "string" } } }, "example": { "holiday_policy_id": "01kdj6d7qyd12ye094esbtej2r", "balance": 0, "year": "2026", "initial_balance": 5 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayBalanceResource" } } }, "example": { "data": { "id": "01kwt1xszeqnxvesbrwc9kzfgs", "type": "holiday_balances", "attributes": { "employee_id": "01kwt1xq6x2v5zdbnqzsk7rbd0", "holiday_policy_id": "01kdj6d7qyd12ye094esbtej2r", "balance": 0, "year": "2026", "initial_balance": 5 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/holiday-balances/{id}": { "get": { "operationId": "holiday-balances-show", "summary": "Retrieve a holiday balance", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday balance ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Holiday balance detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayBalanceResource" } } }, "example": { "data": { "id": "01kwt1xszeqnxvesbrwc9kzfgs", "type": "holiday_balances", "attributes": { "employee_id": "01kwt1xq6x2v5zdbnqzsk7rbd0", "holiday_policy_id": "01kdj6d7qyd12ye094esbtej2r", "balance": 0, "year": "2026", "initial_balance": 5 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "holiday-balances-update", "summary": "Update a holiday balance", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday balance ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "holiday_policy_id": { "description": "ULID foreign key to the HolidayPolicy (HolidayPolicyRepository) this balance is measured against, e.g. paid vacation or sick leave. Together with employee_id and year it uniquely identifies the balance.", "type": "string" }, "balance": { "description": "Remaining leave days currently available to the employee under this policy for the given year (float, in days; decimals allowed for accrual-based policies). Decreases as holidays are approved and increases with accrual or manual credit.", "type": "integer" }, "year": { "description": "Calendar year (four-digit integer, e.g. 2026) this balance applies to. A new row exists per year because allowances reset annually.", "type": "string" }, "initial_balance": { "description": "The full allowance of days originally granted for the year before any holidays were taken (float, in days). Used as the baseline for reporting how many days were consumed versus remaining.", "type": "integer" }, "deleted_at": { "description": "Soft-delete timestamp; when set, the balance is archived and excluded from active queries unless the with_trashed matcher is used.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayBalanceResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "holiday-balances-destroy", "summary": "Delete a holiday balance", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday balance ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/holiday-balances/getters/available-balance": { "get": { "operationId": "holiday-balances-getter-available-balance", "summary": "Available balance", "description": "Returns the holiday balance rows for a single employee under a single policy. Pass employee_id (ULID of the Employee) and holiday_policy_id (ULID of the HolidayPolicy) as query parameters; it responds with the matching balances (one per year) so an agent can answer \"how many days of this leave type does this person have left\". Read-only, no side effects.", "tags": [ "Leave" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/holiday-policies": { "get": { "operationId": "holiday-policies-index", "summary": "List holiday policies", "description": "Defines the leave types a tenant offers, one row per policy such as paid vacation, sick leave, parental leave or unpaid leave. Each policy sets the yearly day allowance (days_per_year), whether it is paid, whether unused days carry over, a waiting period, the accrual method (given up front vs accrued daily), which contract types it applies to, and an optional document template generated when the leave is taken. Policies own seniority milestones (extra days after N years) and are the template from which HolidayBalance rows are created per employee/year. Use this repository to list or search available leave types by name; it relates to HolidayBalanceRepository (the per-employee ledger) and to the Holidays domain (actual leave requests filed against a policy).", "tags": [ "Leave" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of holiday-policies per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- milestones (fields: days_per_year, holiday_policy_id, id, years_in_company)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=milestones (include all fields)\n- include=milestones[days_per_year,holiday_policy_id] (selective fields with comma syntax)\n- include=milestones[days_per_year|holiday_policy_id] (selective fields with pipe syntax)\n- include=milestones.posts (nested relationship - all fields)\n- include=milestones[name].posts[title] (nested with field selection at each level)\n- include=milestones[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=milestones.posts[title],milestones.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter holiday-policies by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the holiday-policies. Available options: name (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter holiday-policies resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HolidayPolicyResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 11, "path": "https://demo.growee.test/api/restify/holiday-policies", "per_page": 1, "to": 1, "total": 11 }, "links": { "first": "https://demo.growee.test/api/restify/holiday-policies?page=1", "next": "https://demo.growee.test/api/restify/holiday-policies?page=2", "path": "https://demo.growee.test/api/restify/holiday-policies", "prev": null, "filters": "/api/restify/holiday-policies/filters" }, "data": [ { "id": "01kdj8c55c6drh2jjjqnvhtpy1", "type": "holiday_policies", "attributes": { "id": "01kdj8c55c6drh2jjjqnvhtpy1", "name": "Concediu Moldova", "type": "timeoff", "method": "accrual", "applicable_contract_types": [ "employment_contract" ], "timesheet_symbol": "Co", "days_per_year": 28, "carry_over": true, "waiting_period_days": 0, "paid": true, "milestones": [], "is_used": true, "allow_advance_booking": true, "can_cancel_own_holidays_until_start_date": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "holiday-policies-store", "summary": "Create a holiday policy", "tags": [ "Leave" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the leave type, e.g. \"Paid Vacation\" or \"Sick Leave\". Required. Well-known names are auto-translated to the current locale when read.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this leave type covers and any usage rules, shown to employees when they request leave.", "type": "string" }, "type": { "description": "Category of the policy. One of: \"timeoff\" (regular paid/unpaid time off), \"national\" (public/legal holiday), \"specialRequest\" (event-driven leave such as bereavement or marriage), \"other\".", "type": "string" }, "method": { "description": "How the yearly allowance is granted. \"given\" means the full days_per_year is available immediately at the start of the year; \"accrual\" means days accumulate daily at days_per_year/365. Defaults to \"given\".", "type": "string" }, "applicable_contract_types": { "description": "Array of contract type names (matching ContractType.name) this policy applies to; when set, only employees on those contract types can use it. Leave empty/null to apply to all contract types.", "type": "array" }, "timesheet_symbol": { "description": "Short code used on generated timesheets to mark days taken under this policy, drawn from the SheetSymbols enum (e.g. \"Co\" = paid vacation, \"CoN\" = unpaid vacation, \"Cm\" = medical, \"Cp\" = paternity, \"Zlp\" = paid days off).", "type": "string" }, "days_per_year": { "description": "Number of leave days granted per calendar year (integer, in days). A value of 0 means the policy is unlimited. Changing this can recalculate existing employee balances unless update_balances is set to false.", "type": "integer" }, "carry_over": { "description": "Boolean; when true, days left unused at year-end roll over into the next year instead of being forfeited.", "type": "boolean" }, "waiting_period_days": { "description": "Number of days (integer) a newly hired employee must wait after their start date before they are allowed to book leave under this policy.", "type": "integer" }, "paid": { "description": "Boolean; when true this leave is paid (salary continues while off). When false the time off is unpaid.", "type": "boolean" }, "document_template_path": { "description": "Uploaded Word/PDF template file (stored on the documents disk) used to generate a leave-request document when an employee books this type of leave. Optional.", "type": "string" }, "document_template_path_name": { "description": "Original file name of the uploaded document_template_path, preserved for display and download.", "type": "string" }, "update_balances": { "description": "Write-only control flag (not stored). When true (the default) on update, changing days_per_year re-runs balance recalculation for all employees on this policy; set false to change the allowance without touching existing balances.", "type": "string" }, "allow_advance_booking": { "description": "Boolean; when true employees may book leave for dates before their allowance for that period has fully accrued.", "type": "boolean" }, "can_cancel_own_holidays_until_start_date": { "description": "Boolean; when true employees can self-cancel an approved holiday under this policy any time up to its start date, without manager involvement.", "type": "boolean" } }, "required": [ "name" ] }, "example": { "name": "Concediu Moldova", "type": "timeoff", "method": "accrual", "applicable_contract_types": [ "employment_contract" ], "timesheet_symbol": "Co", "days_per_year": 28, "carry_over": true, "waiting_period_days": 0, "paid": true, "allow_advance_booking": true, "can_cancel_own_holidays_until_start_date": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayPolicyResource" } } }, "example": { "data": { "id": "01kdj8c55c6drh2jjjqnvhtpy1", "type": "holiday_policies", "attributes": { "id": "01kdj8c55c6drh2jjjqnvhtpy1", "name": "Concediu Moldova", "type": "timeoff", "method": "accrual", "applicable_contract_types": [ "employment_contract" ], "timesheet_symbol": "Co", "days_per_year": 28, "carry_over": true, "waiting_period_days": 0, "paid": true, "milestones": [], "is_used": true, "allow_advance_booking": true, "can_cancel_own_holidays_until_start_date": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/holiday-policies/{id}": { "get": { "operationId": "holiday-policies-show", "summary": "Retrieve a holiday policy", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday policy ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Holiday policy detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayPolicyResource" } } }, "example": { "data": { "id": "01kdj8c55c6drh2jjjqnvhtpy1", "type": "holiday_policies", "attributes": { "id": "01kdj8c55c6drh2jjjqnvhtpy1", "name": "Concediu Moldova", "type": "timeoff", "method": "accrual", "applicable_contract_types": [ "employment_contract" ], "timesheet_symbol": "Co", "days_per_year": 28, "carry_over": true, "waiting_period_days": 0, "paid": true, "milestones": [], "is_used": true, "allow_advance_booking": true, "can_cancel_own_holidays_until_start_date": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "holiday-policies-update", "summary": "Update a holiday policy", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday policy ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the leave type, e.g. \"Paid Vacation\" or \"Sick Leave\". Required. Well-known names are auto-translated to the current locale when read.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this leave type covers and any usage rules, shown to employees when they request leave.", "type": "string" }, "type": { "description": "Category of the policy. One of: \"timeoff\" (regular paid/unpaid time off), \"national\" (public/legal holiday), \"specialRequest\" (event-driven leave such as bereavement or marriage), \"other\".", "type": "string" }, "method": { "description": "How the yearly allowance is granted. \"given\" means the full days_per_year is available immediately at the start of the year; \"accrual\" means days accumulate daily at days_per_year/365. Defaults to \"given\".", "type": "string" }, "applicable_contract_types": { "description": "Array of contract type names (matching ContractType.name) this policy applies to; when set, only employees on those contract types can use it. Leave empty/null to apply to all contract types.", "type": "array" }, "timesheet_symbol": { "description": "Short code used on generated timesheets to mark days taken under this policy, drawn from the SheetSymbols enum (e.g. \"Co\" = paid vacation, \"CoN\" = unpaid vacation, \"Cm\" = medical, \"Cp\" = paternity, \"Zlp\" = paid days off).", "type": "string" }, "days_per_year": { "description": "Number of leave days granted per calendar year (integer, in days). A value of 0 means the policy is unlimited. Changing this can recalculate existing employee balances unless update_balances is set to false.", "type": "integer" }, "carry_over": { "description": "Boolean; when true, days left unused at year-end roll over into the next year instead of being forfeited.", "type": "boolean" }, "waiting_period_days": { "description": "Number of days (integer) a newly hired employee must wait after their start date before they are allowed to book leave under this policy.", "type": "integer" }, "paid": { "description": "Boolean; when true this leave is paid (salary continues while off). When false the time off is unpaid.", "type": "boolean" }, "document_template_path": { "description": "Uploaded Word/PDF template file (stored on the documents disk) used to generate a leave-request document when an employee books this type of leave. Optional.", "type": "string" }, "document_template_path_name": { "description": "Original file name of the uploaded document_template_path, preserved for display and download.", "type": "string" }, "update_balances": { "description": "Write-only control flag (not stored). When true (the default) on update, changing days_per_year re-runs balance recalculation for all employees on this policy; set false to change the allowance without touching existing balances.", "type": "boolean" }, "allow_advance_booking": { "description": "Boolean; when true employees may book leave for dates before their allowance for that period has fully accrued.", "type": "boolean" }, "can_cancel_own_holidays_until_start_date": { "description": "Boolean; when true employees can self-cancel an approved holiday under this policy any time up to its start date, without manager involvement.", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HolidayPolicyResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "holiday-policies-destroy", "summary": "Delete a holiday policy", "tags": [ "Leave" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The holiday policy ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/timesheets": { "get": { "operationId": "timesheets-index", "summary": "List timesheets", "description": "Manages time-tracking entries stored in the [timesheets] table: each row is worked time (in minutes) an employee spent on a specific project and task on a given date, optionally flagged as a break. Rows link to employees, projects and tasks, and may carry a billed hourly rate (visible only to payroll managers) used for profitability and invoicing. Use this repository to list, search, filter (by employee, project, client, task or date range) and report on logged hours; passing a \"group\" of employee_id, project_id or task_id returns aggregated totals instead of individual entries. It is the source of worked-hours data that feeds project profitability, payroll and client billing.", "tags": [ "Time Tracking" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of timesheets per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- project (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- task (fields: archived, created_by, description, id, name, project_id)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,project (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],project[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],project[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter timesheets by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the timesheets. Available options: worked_minutes, created_at, date (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a exact match for project_id (e.g., project_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -project_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a exact match for client_id (e.g., client_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -client_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "task_id", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a exact match for task_id (e.g., task_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -task_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a range match for date (e.g., date=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -date=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "active_employee", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a exact match for active_employee (e.g., active_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -active_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "archived_employee", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a exact match for archived_employee (e.g., archived_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -archived_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "timer_started_at", "in": "query", "required": false, "description": "Filter timesheets resource. Description: This is a date match for timer_started_at (e.g., timer_started_at=YYYY-MM-DD or timer_started_at=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -timer_started_at=YYYY-MM-DD or -timer_started_at=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } }, { "name": "group", "in": "query", "required": false, "description": "Return an aggregated report instead of individual entries. Group by `employee_id`, `project_id` or `task_id` - each row then carries totals such as `total_worked_minutes`, `total_worked_hours` and, for payroll managers, billing/profitability figures. Combine with a `date` range (`date=2026-01-01,2026-01-31`).", "schema": { "type": "string", "enum": [ "employee_id", "project_id", "task_id" ] } }, { "name": "group_client_id", "in": "query", "required": false, "description": "When grouping, restrict the report to projects of this client and add a client dimension to each row.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1895, "path": "https://demo.growee.test/api/restify/timesheets", "per_page": 1, "to": 1, "total": 1895, "total_worked_hours": 10150 }, "links": { "first": "https://demo.growee.test/api/restify/timesheets?page=1", "next": "https://demo.growee.test/api/restify/timesheets?page=2", "path": "https://demo.growee.test/api/restify/timesheets", "prev": null, "filters": "/api/restify/timesheets/filters" }, "data": [ { "id": "01kxdwj6yc9h1eypmcma8hcm2k", "type": "timesheets", "attributes": { "id": "01kxdwj6yc9h1eypmcma8hcm2k", "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "task_id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "worked_minutes": 240, "is_break": false, "description": "Am lucrat pe...", "date": "2026-08-03T00:00:00.000000Z", "created_at": "2026-07-13T14:02:14.000000Z", "billed_hourly_rate": "0.00" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "timesheets-store", "summary": "Create a timesheet", "tags": [ "Time Tracking" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID of the Employee (EmployeeRepository) this time entry belongs to. Defaults to the current employee when omitted; only users allowed to manage timesheets may log time for another employee.", "type": "string" }, "project_id": { "description": "ULID of the Project (ProjectRepository) the worked time is attributed to. Required when creating an entry.", "type": "string" }, "task_id": { "description": "ULID of the Task (TaskRepository) within the project that the time was spent on. Required when creating an entry.", "type": "string" }, "worked_minutes": { "description": "Duration of the logged time in whole minutes (e.g. 90 means one hour and a half). Divide by 60 to get hours.", "type": "integer" }, "is_break": { "description": "When true the entry represents a break rather than billable work; break entries are excluded from worked-hours totals.", "type": "boolean" }, "description": { "description": "Optional free-text note describing what was worked on during this time entry.", "type": "string" }, "date": { "description": "Calendar day the work was performed, formatted as Y-m-d (date only, no time). Required when creating an entry.", "type": "string" } }, "required": [ "employee_id", "project_id", "task_id", "worked_minutes", "date" ] }, "example": { "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "task_id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "worked_minutes": 240, "is_break": false, "description": "Am lucrat pe...", "date": "2026-08-03T00:00:00.000000Z" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TimesheetResource" } } }, "example": { "data": { "id": "01kxdwj6yc9h1eypmcma8hcm2k", "type": "timesheets", "attributes": { "id": "01kxdwj6yc9h1eypmcma8hcm2k", "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "task_id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "worked_minutes": 240, "is_break": false, "description": "Am lucrat pe...", "date": "2026-08-03T00:00:00.000000Z", "created_at": "2026-07-13T14:02:14.000000Z", "billed_hourly_rate": "0.00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/timesheets/{id}": { "get": { "operationId": "timesheets-show", "summary": "Retrieve a timesheet", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timesheet detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TimesheetResource" } } }, "example": { "data": { "id": "01kxdwj6yc9h1eypmcma8hcm2k", "type": "timesheets", "attributes": { "id": "01kxdwj6yc9h1eypmcma8hcm2k", "employee_id": "01kwt1xnvkjg93yxthp73ngqza", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "task_id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "worked_minutes": 240, "is_break": false, "description": "Am lucrat pe...", "date": "2026-08-03T00:00:00.000000Z", "created_at": "2026-07-13T14:02:14.000000Z", "billed_hourly_rate": "0.00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "timesheets-update", "summary": "Update a timesheet", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID of the Employee (EmployeeRepository) this time entry belongs to. Defaults to the current employee when omitted; only users allowed to manage timesheets may log time for another employee.", "type": "string" }, "project_id": { "description": "ULID of the Project (ProjectRepository) the worked time is attributed to. Required when creating an entry.", "type": "string" }, "task_id": { "description": "ULID of the Task (TaskRepository) within the project that the time was spent on. Required when creating an entry.", "type": "string" }, "worked_minutes": { "description": "Duration of the logged time in whole minutes (e.g. 90 means one hour and a half). Divide by 60 to get hours.", "minimum": 0, "type": "integer" }, "is_break": { "description": "When true the entry represents a break rather than billable work; break entries are excluded from worked-hours totals.", "type": "boolean" }, "description": { "description": "Optional free-text note describing what was worked on during this time entry.", "type": "string" }, "date": { "description": "Calendar day the work was performed, formatted as Y-m-d (date only, no time). Required when creating an entry.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TimesheetResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "timesheets-destroy", "summary": "Delete a timesheet", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/timesheets/{id}/actions": { "post": { "operationId": "timesheets-record-actions", "summary": "Actions: replicate-period, download-pdf-report, start-timer, ...", "description": "Perform an action on a single timesheet. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`replicate-period`** - Copies the current employee's existing timesheet entries from the previous period into the current one, creating new time entries so recurring work does not have to be re-logged manually. Requires a \"period\" payload key with either \"day\" (duplicate yesterday into today) or \"week\" (duplicate last week into this week). Call this when an employee wants to repeat a prior day's or week's logged hours; it returns the newly created timesheet entries.\n- **`download-pdf-report`** - Generates a detailed PDF timesheet report for the given filter and emails it (asynchronously) to the requesting employee or the supplied email address. Expects \"path\" (https URL of the report page to render), an optional \"file_name\", an optional \"email\" recipient, and a \"report_filter\" array describing the report scope. This action is hidden from the MCP/AI tool surface and is used by the app UI to deliver PDF exports rather than to return data inline.\n- **`start-timer`** - Starts a live running timer on a specific timesheet entry so worked time is tracked in real time. It sets timer_started_at on the entry (accounting for any minutes already logged) and is only permitted for the entry's own employee or a user who may manage that employee's timesheets. Call this when the user begins actively working on a logged task; stop the timer later with the stop-timer action.\n- **`stop-timer`** - Stops the running timer on a timesheet entry, converting the elapsed time since timer_started_at into worked_minutes and clearing the running-timer flag. It is only permitted for the entry's own employee or a user who may manage that employee's timesheets, and is a no-op if no timer is running. Call this when the user finishes working on a task whose timer was previously started with start-timer.", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "replicate-period", "download-pdf-report", "start-timer", "stop-timer" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "replicate-period", "type": "object", "properties": { "period": { "description": "This field is required", "type": "string" } } }, { "title": "download-pdf-report", "type": "object", "properties": { "path": { "description": "This field is required", "type": "string" }, "file_name": { "description": "This field is optional", "type": "string" }, "email": { "description": "This field is optional", "type": "string" }, "report_filter": { "description": "Must be an array", "type": "array" } } }, { "title": "start-timer", "type": "object", "properties": {} }, { "title": "stop-timer", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/timesheet-submissions": { "get": { "operationId": "timesheet-submissions-index", "summary": "List timesheet submissions", "description": "This repository manages the [TimesheetSubmission] model, which corresponds to the [timesheet_submissions] table in the database. It provides functionalities such as listing, searching, sorting, filtering, and relationship management. The model/table has the following attributes: employee_id, week_start_date, status, submitted_at, approved_at, rejected_at, status_changed_by, status_explanation, is_demo.", "tags": [ "Time Tracking" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "perPage", "in": "query", "required": false, "description": "Results per page.", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Search term.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort field; prefix with - for descending.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetSubmissionResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 10, "path": "https://demo.growee.test/api/restify/timesheet-submissions", "per_page": 1, "to": 1, "total": 10 }, "links": { "first": "https://demo.growee.test/api/restify/timesheet-submissions?page=1", "next": "https://demo.growee.test/api/restify/timesheet-submissions?page=2", "path": "https://demo.growee.test/api/restify/timesheet-submissions", "prev": null, "filters": "/api/restify/timesheet-submissions/filters" }, "data": [ { "id": "01kxdwkwf1vjgeprh1mqhsfbne", "type": "timesheet_submissions", "attributes": { "id": "01kxdwkwf1vjgeprh1mqhsfbne", "employee_id": "01kwt1xq6x2v5zdbnqzsk7rbd0", "week_start_date": "2026-07-06T00:00:00.000000Z", "status": "rejected", "submitted_at": "2026-07-13T14:03:09.000000Z", "rejected_at": "2026-07-13T14:03:09.000000Z", "status_changed_by": "01kwt1xncps2bcdqep555p1300", "status_explanation": "Nu mi se par valide" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/timesheet-submissions/{id}": { "get": { "operationId": "timesheet-submissions-show", "summary": "Retrieve a timesheet submission", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet submission ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timesheet submission detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TimesheetSubmissionResource" } } }, "example": { "data": { "id": "01kxdwkwf1vjgeprh1mqhsfbne", "type": "timesheet_submissions", "attributes": { "id": "01kxdwkwf1vjgeprh1mqhsfbne", "employee_id": "01kwt1xq6x2v5zdbnqzsk7rbd0", "week_start_date": "2026-07-06T00:00:00.000000Z", "status": "rejected", "submitted_at": "2026-07-13T14:03:09.000000Z", "rejected_at": "2026-07-13T14:03:09.000000Z", "status_changed_by": "01kwt1xncps2bcdqep555p1300", "status_explanation": "Nu mi se par valide" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "timesheet-submissions-destroy", "summary": "Delete a timesheet submission", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet submission ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/timesheet-submissions/getters/weekly-approval-report": { "get": { "operationId": "timesheet-submissions-getter-weekly-approval-report", "summary": "Weekly approval report", "description": "", "tags": [ "Time Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/timesheet-submissions/{id}/actions": { "post": { "operationId": "timesheet-submissions-record-actions", "summary": "Actions: submit, approve-week, approve, ...", "description": "Perform an action on a single timesheet submission. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`submit`** - Submit the current employee timesheet week for approval.\n- **`approve-week`** - Approve an employee timesheet week, even when it was not submitted yet.\n- **`approve`** - Approve a submitted timesheet week.\n- **`reject`** - Reject a submitted timesheet week. A reason is required and will be shared with the employee.\n- **`reject-week`** - Reject an employee timesheet week, even when it was not submitted yet. A reason is required.\n- **`remind`** - Send an employee a reminder to submit their timesheet week for approval.", "tags": [ "Time Tracking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The timesheet submission ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "submit", "approve-week", "approve", "reject", "reject-week", "remind" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "submit", "type": "object", "properties": { "week_start_date": { "description": "This field is required", "type": "string" } } }, { "title": "approve-week", "type": "object", "properties": { "employee_id": { "description": "Must exist in the database", "type": "string" }, "week_start_date": { "description": "This field is required", "type": "string" } } }, { "title": "approve", "type": "object", "properties": {} }, { "title": "reject", "type": "object", "properties": { "status_explanation": { "description": "Maximum length: 1000 characters", "maxLength": 1000, "type": "string" } } }, { "title": "reject-week", "type": "object", "properties": { "employee_id": { "description": "Must exist in the database", "type": "string" }, "week_start_date": { "description": "This field is required", "type": "string" }, "status_explanation": { "description": "Maximum length: 1000 characters", "maxLength": 1000, "type": "string" } } }, { "title": "remind", "type": "object", "properties": { "employee_id": { "description": "Must exist in the database", "type": "string" }, "week_start_date": { "description": "This field is required", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/projects": { "get": { "operationId": "projects-index", "summary": "List projects", "description": "A project is a billable client engagement in Growee and the central unit for time tracking, budgeting, invoicing and profitability. The projects table stores the engagement name, its owning client_id (Client the work is delivered for), commercial terms (billing_model, budget, budget_type, revenue_share_percent, currency), the active window (starts_at, ends_at) and archive state. It has many tasks (work breakdown), many timesheets (logged hours), many expenses and invoices, and a many-to-many team of employees carrying per-member billed_rate and internal cost on the project_employee pivot. Use this repository to list, search or inspect client work; pair it with the ClientRepository (the account the project belongs to), the TaskRepository (work items under a project) and the project-profitability / project-team-economics / portfolio-overview getters for financial analysis.", "tags": [ "Projects" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of projects per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- tenant (fields: api, company_industry, country, frontend, general_information, has_beta_access, has_demo_data, invitations, locale, name, referrer_source, sensitive_information, team_size)\n- tasks (fields: archived, created_by, description, id, name, project_id)\n- timesheets (fields: billed_hourly_rate, created_at, date, description, employee_id, id, is_break, project_id, task_id, timer_started_at, worked_minutes)\n- expenses (fields: amount, approved_at, currency, date, description, employee_id, expense_bundle_id, expense_category_id, id, is_demo, paid_at, project_id, receipt_filename, rejected_at, requested_approver_id, status, status_changed_by, status_explanation)\n- expensesBundles (fields: approved_at, description, employee_id, end_date, id, is_demo, paid_at, project_id, rejected_at, requested_approver_id, start_date, status, status_changed_by, status_explanation, title, total_amount)\n- client (fields: bank_account, bank_name, bank_swift, city, company_address, company_identifier, company_name, company_vat, country, created_at, custom_fields, description, domain, id, industry, is_used, lifecycle_stage, logo_path, meta, owner_id, prefered_currency, representative_name, representative_position, size, website)\n- activeEmployees (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- archivedEmployees (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- employees (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=creator,tenant (include all fields)\n- include=creator[archived_at,avatar] (selective fields with comma syntax)\n- include=creator[archived_at|avatar] (selective fields with pipe syntax)\n- include=creator.posts (nested relationship - all fields)\n- include=creator[name].posts[title] (nested with field selection at each level)\n- include=creator[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=creator.posts[title],creator.comments[body] (multiple nested from same parent)\n- include=creator[name],tenant[id] (multiple relationships with field selection)\n- include=creator[email|name].posts[title],tenant[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter projects by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the projects. Available options: name, invoiced_date (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter projects resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter projects resource. Description: This is a exact match for client_id (e.g., client_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -client_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "Filter projects resource. Description: This is a exact match for archived (e.g., archived=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -archived=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter projects resource. Description: This is an array match for employee_id (e.g., employee_id=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=value1,value2). The values acccepted can be any.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 13, "path": "https://demo.growee.test/api/restify/projects", "per_page": 1, "to": 1, "total": 13 }, "links": { "first": "https://demo.growee.test/api/restify/projects?page=1", "next": "https://demo.growee.test/api/restify/projects?page=2", "path": "https://demo.growee.test/api/restify/projects", "prev": null, "filters": "/api/restify/projects/filters" }, "data": [ { "id": "01kxdwetf1z8gn7nyqhpcq27qq", "type": "projects", "attributes": { "id": "01kxdwetf1z8gn7nyqhpcq27qq", "budget_type": "monthly", "name": "Intern", "client_name": "Intern", "created_at": "2026-07-13T14:00:23.000000Z", "client_id": "01kxdwdz8ch3ce36rdggs01npf", "is_used": true, "archived": false } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "projects-store", "summary": "Create a project", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "budget": { "description": "The monetary budget for the project, expressed in the project currency. Interpreted according to budget_type (weekly/monthly/yearly recurring amount, or a single fixed total). Drives budget-basis revenue and the remaining/overspend figures in profitability reports. Only visible to users who can manage salaries.", "type": "string" }, "budget_type": { "description": "How the budget value recurs. One of: weekly, monthly, yearly, fixed — weekly, monthly and yearly treat budget as a recurring amount prorated across the reporting window, while fixed treats budget as a single total for the whole engagement.", "enum": [ "weekly", "monthly", "yearly", "fixed" ], "type": "string" }, "billing_model": { "description": "The commercial model that determines how revenue is recognised for this project. One of: retainer, fixed_price, time_and_materials, ppc_passthrough, revenue_share, internal — retainer/fixed_price recognise revenue from the budget, time_and_materials from billable timesheet amounts, ppc_passthrough and revenue_share are pass-through/share arrangements, and internal marks non-billable internal work counted only as cost. Only visible to users who can manage salaries.", "type": "string" }, "revenue_share_percent": { "description": "The share of revenue retained by the company, as a percentage from 0 to 100. Only meaningful for revenue_share billing_model projects. Only visible to users who can manage salaries.", "minimum": 0, "maximum": 100, "type": "number" }, "currency": { "description": "The 3-letter ISO 4217 currency code (e.g. EUR, USD, RON) in which the budget and billed rates are denominated. If null, the project falls back to the client preferred currency and then the tenant default currency. Only visible to users who can manage salaries.", "minLength": 3, "maxLength": 3, "type": "string" }, "starts_at": { "description": "The date (Y-m-d) the engagement starts. Bounds the active window used when prorating recurring budgets and computing costs; if null the project creation date is treated as the effective start. Must be on or before ends_at.", "type": "string" }, "ends_at": { "description": "The date (Y-m-d) the engagement ends, or null for an open-ended project. When set and in the past, the project is treated as ended in profitability reports. Must be on or after starts_at.", "type": "string" }, "name": { "description": "The human-readable name of the project. Required on create and must be unique within the tenant.", "type": "string" }, "website": { "description": "An optional URL for the project or the client work (e.g. the delivered site). Trailing slashes are stripped on save; max 255 characters.", "maxLength": 255, "type": "string" }, "description": { "description": "Free-text notes describing the project scope or context.", "type": "string" }, "client_id": { "description": "ULID foreign key to the Client (ClientRepository) this project is delivered for and billed to. Required on create; must reference an existing client.", "type": "string" }, "logo_path": { "description": "Field: logo_path.. Examples: sample text, example value -- Important: This should be an absolute path or URL to the file that can be read.", "type": "string" } }, "required": [ "name", "client_id" ] }, "example": { "budget_type": "monthly", "name": "Intern", "client_id": "01kxdwdz8ch3ce36rdggs01npf" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } } }, "example": { "data": { "id": "01kxdwetf1z8gn7nyqhpcq27qq", "type": "projects", "attributes": { "id": "01kxdwetf1z8gn7nyqhpcq27qq", "budget_type": "monthly", "name": "Intern", "client_name": "Intern", "created_at": "2026-07-13T14:00:23.000000Z", "client_id": "01kxdwdz8ch3ce36rdggs01npf", "is_used": true, "archived": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/projects/{id}": { "get": { "operationId": "projects-show", "summary": "Retrieve a project", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } } }, "example": { "data": { "id": "01kxdwetf1z8gn7nyqhpcq27qq", "type": "projects", "attributes": { "id": "01kxdwetf1z8gn7nyqhpcq27qq", "budget_type": "monthly", "name": "Intern", "client_name": "Intern", "created_at": "2026-07-13T14:00:23.000000Z", "client_id": "01kxdwdz8ch3ce36rdggs01npf", "is_used": true, "archived": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "projects-update", "summary": "Update a project", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "budget": { "description": "The monetary budget for the project, expressed in the project currency. Interpreted according to budget_type (weekly/monthly/yearly recurring amount, or a single fixed total). Drives budget-basis revenue and the remaining/overspend figures in profitability reports. Only visible to users who can manage salaries.", "type": "string" }, "budget_type": { "description": "How the budget value recurs. One of: weekly, monthly, yearly, fixed — weekly, monthly and yearly treat budget as a recurring amount prorated across the reporting window, while fixed treats budget as a single total for the whole engagement.", "enum": [ "weekly", "monthly", "yearly", "fixed" ], "type": "string" }, "billing_model": { "description": "The commercial model that determines how revenue is recognised for this project. One of: retainer, fixed_price, time_and_materials, ppc_passthrough, revenue_share, internal — retainer/fixed_price recognise revenue from the budget, time_and_materials from billable timesheet amounts, ppc_passthrough and revenue_share are pass-through/share arrangements, and internal marks non-billable internal work counted only as cost. Only visible to users who can manage salaries.", "type": "string" }, "revenue_share_percent": { "description": "The share of revenue retained by the company, as a percentage from 0 to 100. Only meaningful for revenue_share billing_model projects. Only visible to users who can manage salaries.", "minimum": 0, "maximum": 100, "type": "number" }, "currency": { "description": "The 3-letter ISO 4217 currency code (e.g. EUR, USD, RON) in which the budget and billed rates are denominated. If null, the project falls back to the client preferred currency and then the tenant default currency. Only visible to users who can manage salaries.", "minLength": 3, "maxLength": 3, "type": "string" }, "starts_at": { "description": "The date (Y-m-d) the engagement starts. Bounds the active window used when prorating recurring budgets and computing costs; if null the project creation date is treated as the effective start. Must be on or before ends_at.", "type": "string" }, "ends_at": { "description": "The date (Y-m-d) the engagement ends, or null for an open-ended project. When set and in the past, the project is treated as ended in profitability reports. Must be on or after starts_at.", "type": "string" }, "name": { "description": "The human-readable name of the project. Required on create and must be unique within the tenant.", "type": "string" }, "website": { "description": "An optional URL for the project or the client work (e.g. the delivered site). Trailing slashes are stripped on save; max 255 characters.", "maxLength": 255, "type": "string" }, "description": { "description": "Free-text notes describing the project scope or context.", "type": "string" }, "client_id": { "description": "ULID foreign key to the Client (ClientRepository) this project is delivered for and billed to. Required on create; must reference an existing client.", "type": "string" }, "logo_path": { "description": "Field: logo_path.. Examples: sample text, example value -- Important: This should be an absolute path or URL to the file that can be read.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "projects-destroy", "summary": "Delete a project", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/projects/getters/project-profitability": { "get": { "operationId": "projects-getter-project-profitability", "summary": "Project profitability", "description": "Detailed month-by-month profitability analysis for one specific project over a date range. Run against a single project and pass start_date and end_date (both Y-m-d; default to the current month). Returns, in the project currency, a per-month and total breakdown of projected cost vs actual cost (split into holiday, salary, hourly and expense components), timesheet billable amount, invoiced amount, resolved revenue and profit with the revenue/profit basis (invoiced, budget or billable, chosen from the billing_model), plus budget usage, remaining budget and overspend percentage. Use this to understand whether a single engagement is profitable and where its cost goes; use portfolio-overview for the whole company and project-team-economics for a per-member split.", "tags": [ "Project Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/projects/getters/project-team-economics": { "get": { "operationId": "projects-getter-project-team-economics", "summary": "Project team economics", "description": "Per-member economics for one project over a date range. Run against a single project and pass start_date and end_date (both Y-m-d). For each active roster member it returns their billed rate, internal hourly cost, worked vs expected hours, utilization percent, internal cost, billable amount and margin (with percent), plus tenant-level totals and a fee-based summary (monthly fee and team margin) when the billing_model is retainer/fixed-price. Requires manage-salaries permission. Use this to see which individuals on a project are profitable and how utilized they are; use project-profitability for the project total and portfolio-overview for all projects.", "tags": [ "Project Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/projects/getters/portfolio-overview": { "get": { "operationId": "projects-getter-portfolio-overview", "summary": "Portfolio overview", "description": "Portfolio-wide profitability overview across all projects in the tenant for a date range. Pass start_date and end_date (both Y-m-d; start on or before end). Returns, in the reporting currency: a per-project breakdown of revenue, cost, margin and margin percent with the revenue basis used (invoiced/budget/billable); client revenue concentration (share per client); internal_burn (total cost of non-billable internal projects); and the currency_mix of invoiced revenue. Requires manage-salaries permission. Use this for company-level financial health, client concentration risk and burn analysis; use project-profitability for a single project drill-down.", "tags": [ "Project Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/projects/{id}/actions": { "post": { "operationId": "projects-record-actions", "summary": "Actions: detach-employee, restore-employees, set-billed-rate, ...", "description": "Perform an action on a single project. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`detach-employee`** - Detaches (archives) one or more employees from a specific project, identified by the Project record the action is invoked on. Expects an `employees` payload: an array of employee ULIDs, each of which must exist in the employees table. For each id it archives that employee's assignment on the project, ending their active participation while retaining the historical assignment record. Requires the caller to hold either the `manageEmployees` or `manageProjectAssignments` permission. Call this to remove team members from a project; use the `restore-employees` action to reattach them.\n- **`restore-employees`** - Restores (unarchives) one or more previously detached employees back onto a specific project, identified by the Project record the action is invoked on. Expects an `employees` payload: an array of employee ULIDs, each of which must exist in the employees table. For each id it reactivates that employee's assignment on the project, returning them to the active team. Requires the caller to hold either the `manageEmployees` or `manageProjectAssignments` permission. Call this to reverse the `detach-employee` action and put team members back on a project.\n- **`set-billed-rate`** - Set or update one team member's commercial terms on a project. Run against a specific project and pass: employee_id (ULID of the Employee to update), billed_rate (the hourly rate charged to the client, required), and optionally weekly_allocation_hours (planned hours per week) and currency (3-letter ISO code, e.g. EUR/USD/RON). It writes these onto the project_employee pivot and propagates the new rate to that employee's future timesheets on the project. Requires manage-projects permission. Use this to price a member onto a project or change what the client is billed for their work.\n- **`archive`** - Archive a single project. Run against one project (by ID); it marks the project as archived so it disappears from active project lists and reports without being deleted, preserving its history and timesheets. Requires manage-projects permission. Use this to retire a finished or paused engagement; call the unarchive action to reverse it. Takes no payload beyond the target project.\n- **`unarchive`** - Restore a previously archived project back to active status. This is a standalone action: pass project_id (the ULID of the archived project) in the payload. It removes the archive marker so the project reappears in active lists and reports. Requires manage-projects permission. Use this to reactivate an engagement that was archived by mistake or has resumed.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "detach-employee", "restore-employees", "set-billed-rate", "archive", "unarchive" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "detach-employee", "type": "object", "properties": { "employees": { "description": "Must be an array", "type": "array" }, "employees.*": { "type": "string" } } }, { "title": "restore-employees", "type": "object", "properties": { "employees": { "description": "Must be an array", "type": "array" }, "employees.*": { "type": "string" } } }, { "title": "set-billed-rate", "type": "object", "properties": { "employee_id": { "description": "Must exist in the database", "type": "string" }, "billed_rate": { "description": "This field is required", "type": "string" }, "weekly_allocation_hours": { "description": "Must be a numeric value", "type": "number" }, "currency": { "description": "Must be one of: EUR, RON, USD, GBP, MDL, NOK, CHF, AED, AUD, BGN, BYN, CAD, CNY, EGP, SEK, TRY", "enum": [ "EUR", "RON", "USD", "GBP", "MDL", "NOK", "CHF", "AED", "AUD", "BGN", "BYN", "CAD", "CNY", "EGP", "SEK", "TRY" ], "type": "string" } } }, { "title": "archive", "type": "object", "properties": {} }, { "title": "unarchive", "type": "object", "properties": { "project_id": { "description": "Must exist in the database", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/tasks": { "get": { "operationId": "tasks-index", "summary": "List tasks", "description": "A task is a unit of work belonging to a project, and the label employees pick when logging time. The tasks table stores the task name, its parent project_id, an optional description and an archive state. Each task belongs to one Project (ProjectRepository) and has many timesheets (logged hours); a task with logged hours cannot be deleted, only archived. Use this repository to list, search or manage the work breakdown under projects; filter by project_id to see a single project's tasks.", "tags": [ "Projects" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of tasks per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- project (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- timesheets (fields: archived, created_by, description, id, name, project_id)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=project,creator (include all fields)\n- include=project[archived,billing_model] (selective fields with comma syntax)\n- include=project[archived|billing_model] (selective fields with pipe syntax)\n- include=project.posts (nested relationship - all fields)\n- include=project[name].posts[title] (nested with field selection at each level)\n- include=project[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=project.posts[title],project.comments[body] (multiple nested from same parent)\n- include=project[name],creator[id] (multiple relationships with field selection)\n- include=project[email|name].posts[title],creator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter tasks by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the tasks. Available options: name (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter tasks resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter tasks resource. Description: This is a exact match for project_id (e.g., project_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -project_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter tasks resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "Filter tasks resource. Description: This is a exact match for archived (e.g., archived=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -archived=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 58, "path": "https://demo.growee.test/api/restify/tasks", "per_page": 1, "to": 1, "total": 58 }, "links": { "first": "https://demo.growee.test/api/restify/tasks?page=1", "next": "https://demo.growee.test/api/restify/tasks?page=2", "path": "https://demo.growee.test/api/restify/tasks", "prev": null, "filters": "/api/restify/tasks/filters" }, "data": [ { "id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "type": "tasks", "attributes": { "id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "name": "Munca suplimentara", "created_by": "01kwt1xnc4c15beb3jr1109trm", "archived": false } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "tasks-store", "summary": "Create a task", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "ULID foreign key to the parent Project (ProjectRepository) this task belongs to. Required on create; must reference an existing project.", "type": "string" }, "name": { "description": "The human-readable name of the task (the label shown when logging time). Required on create; up to 1024 characters.", "maxLength": 1024, "type": "string" }, "description": { "description": "Optional free-text description giving more detail about the task.", "type": "string" } }, "required": [ "project_id", "name" ] }, "example": { "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "name": "Munca suplimentara" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskResource" } } }, "example": { "data": { "id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "type": "tasks", "attributes": { "id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "name": "Munca suplimentara", "created_by": "01kwt1xnc4c15beb3jr1109trm", "archived": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/tasks/{id}": { "get": { "operationId": "tasks-show", "summary": "Retrieve a task", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskResource" } } }, "example": { "data": { "id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "type": "tasks", "attributes": { "id": "01kxdwfjfrmpt6k5w7w2m9g5fc", "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "name": "Munca suplimentara", "created_by": "01kwt1xnc4c15beb3jr1109trm", "archived": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "tasks-update", "summary": "Update a task", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "ULID foreign key to the parent Project (ProjectRepository) this task belongs to. Required on create; must reference an existing project.", "type": "string" }, "name": { "description": "The human-readable name of the task (the label shown when logging time). Required on create; up to 1024 characters.", "type": "string" }, "description": { "description": "Optional free-text description giving more detail about the task.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "tasks-destroy", "summary": "Delete a task", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tasks/{id}/actions": { "post": { "operationId": "tasks-record-actions", "summary": "Actions: archive, unarchive", "description": "Perform an action on a single task. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`archive`** - Archive a single task (by ID). It marks the task as archived so it no longer appears in active task lists or as a selectable option for logging time, while keeping its history and any logged hours intact. Requires manage-projects permission. Use this to retire a completed or obsolete task; call the unarchive action to restore it. Takes no payload beyond the target task.\n- **`unarchive`** - Restore a previously archived task back to active status. This is a standalone action: pass task_id (the ULID of the archived task) in the payload. It removes the archive marker so the task reappears in active lists and can again be selected when logging time. Requires manage-projects permission. Use this to reactivate a task archived by mistake or one whose work has resumed.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "archive", "unarchive" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "archive", "type": "object", "properties": {} }, { "title": "unarchive", "type": "object", "properties": { "task_id": { "description": "Must exist in the database", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/project-employees": { "get": { "operationId": "project-employees-index", "summary": "List project employees", "description": "A project_employee row is the pivot linking one Employee to one Project — a team membership. It stores the commercial and cost terms of that assignment: the client-facing billed_rate, the internal cost (hourly or a fixed monthly amount via cost_type), the per-week allocation (weekly_allocation_hours), the currency, and an archived_at marker for members removed from the active roster. This repository is the direct way to list or manage individual project memberships and their rates; the same data is also exposed through the ProjectRepository employees relation and the set-billed-rate project action.", "tags": [ "Projects" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of project-employees per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- project (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=project,employee (include all fields)\n- include=project[archived,billing_model] (selective fields with comma syntax)\n- include=project[archived|billing_model] (selective fields with pipe syntax)\n- include=project.posts (nested relationship - all fields)\n- include=project[name].posts[title] (nested with field selection at each level)\n- include=project[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=project.posts[title],project.comments[body] (multiple nested from same parent)\n- include=project[name],employee[id] (multiple relationships with field selection)\n- include=project[email|name].posts[title],employee[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter project-employees by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the project-employees. Available options: created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter project-employees resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter project-employees resource. Description: This is a exact match for project_id (e.g., project_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -project_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEmployeeResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 160, "path": "https://demo.growee.test/api/restify/project-employees", "per_page": 1, "to": 1, "total": 160 }, "links": { "first": "https://demo.growee.test/api/restify/project-employees?page=1", "next": "https://demo.growee.test/api/restify/project-employees?page=2", "path": "https://demo.growee.test/api/restify/project-employees", "prev": null, "filters": "/api/restify/project-employees/filters" }, "data": [ { "id": "746", "type": "project_employee", "attributes": { "id": 746, "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "employee_id": "01kwt1xqv7hz30k9ax28zy5hnk", "weekly_allocation_hours": 0, "billed_rate": 0 } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "project-employees-store", "summary": "Create a project employee", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "ULID foreign key to the Project (ProjectRepository) this membership belongs to. Required on create; must reference an existing project.", "type": "string" }, "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) assigned to the project. Required on create; must reference an existing employee.", "type": "string" }, "currency": { "description": "This is the currency for this employee's billed rate and internal cost on this project. If not set, the company's default currency will be used.", "type": "string" }, "weekly_allocation_hours": { "description": "This is the number of hours this employee is allocated to work on this project each week. Default is 40 hours.", "type": "integer" }, "internal_hourly_cost_for_project": { "description": "This is the internal hourly cost for this employee's work on this project. This is not visible to the client.", "type": "string" }, "cost_type": { "description": "How this member is costed on the project. Can be hourly, monthly. When set to monthly, a fixed monthly cost (prorated by allocation) is used instead of hourly timesheet cost.", "type": "string" }, "internal_monthly_cost_for_project": { "description": "The fixed monthly internal cost for this member on this project. Only used when cost_type is monthly.", "minimum": 0, "type": "number" }, "billed_rate": { "description": "This is the hourly rate that will be billed to the client for this employee's work on this project.", "type": "integer" } }, "required": [ "project_id", "employee_id" ] }, "example": { "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "employee_id": "01kwt1xqv7hz30k9ax28zy5hnk", "weekly_allocation_hours": 0, "billed_rate": 0 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectEmployeeResource" } } }, "example": { "data": { "id": "746", "type": "project_employee", "attributes": { "id": 746, "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "employee_id": "01kwt1xqv7hz30k9ax28zy5hnk", "weekly_allocation_hours": 0, "billed_rate": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/project-employees/{id}": { "get": { "operationId": "project-employees-show", "summary": "Retrieve a project employee", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project employee ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project employee detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectEmployeeResource" } } }, "example": { "data": { "id": "746", "type": "project_employee", "attributes": { "id": 746, "project_id": "01kxdwetf1z8gn7nyqhpcq27qq", "employee_id": "01kwt1xqv7hz30k9ax28zy5hnk", "weekly_allocation_hours": 0, "billed_rate": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "project-employees-update", "summary": "Update a project employee", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project employee ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "ULID foreign key to the Project (ProjectRepository) this membership belongs to. Required on create; must reference an existing project.", "type": "string" }, "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) assigned to the project. Required on create; must reference an existing employee.", "type": "string" }, "currency": { "description": "This is the currency for this employee's billed rate and internal cost on this project. If not set, the company's default currency will be used.", "type": "string" }, "weekly_allocation_hours": { "description": "This is the number of hours this employee is allocated to work on this project each week. Default is 40 hours.", "type": "integer" }, "internal_hourly_cost_for_project": { "description": "This is the internal hourly cost for this employee's work on this project. This is not visible to the client.", "type": "string" }, "cost_type": { "description": "How this member is costed on the project. Can be hourly, monthly. When set to monthly, a fixed monthly cost (prorated by allocation) is used instead of hourly timesheet cost.", "type": "string" }, "internal_monthly_cost_for_project": { "description": "The fixed monthly internal cost for this member on this project. Only used when cost_type is monthly.", "minimum": 0, "type": "number" }, "billed_rate": { "description": "This is the hourly rate that will be billed to the client for this employee's work on this project.", "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectEmployeeResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "project-employees-destroy", "summary": "Delete a project employee", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The project employee ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/clients": { "get": { "operationId": "clients-index", "summary": "List clients", "description": "Manages clients: the companies (customers and prospects) this tenant does business with, stored in the clients table with ULID primary keys. Each client anchors billing (invoices, projects, services) as well as the CRM view of the same company (domain, industry, size, lifecycle_stage, owner). The /restify/organizations endpoint is a CRM-facing facade over this exact same table, and client contacts (people at the company) live in the client_contacts table. Use this repository to look up, search, filter or report on customers, their profitability, and their relationships to invoices, projects, contacts and interactions.", "tags": [ "Clients" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of clients per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- tenant (fields: api, company_industry, country, frontend, general_information, has_beta_access, has_demo_data, invitations, locale, name, referrer_source, sensitive_information, team_size)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- invoices (fields: client_id, created_at, currency, disable_payment_reminders, due_date, from_address, id, invoice_number, issue_date, notes, paid_amount, paid_at, project_id, share_token, status, subtotal, tax, title, to_address, total)\n- projects (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- contacts (fields: client_id, custom_fields, email, id, name, phone, position, verification_status)\n- feedback (fields: audio_file, audio_file_name, created_by, created_by_employee_id, feedback_request_id, feedbackable_id, feedbackable_type, file, file_name, given_at, id, is_visible_to_employee, notes, transcription, transcription_status, type)\n- services (fields: billing_unit, created_at, currency, default_price, description, id, is_active, name)\n- documents (fields: client_id, content, created_at, description, documentable_type, employee_id, end_date, file_name, id, is_signed, name, path, signature_count, size, start_date, status, type_id)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=tenant,creator (include all fields)\n- include=tenant[api,company_industry] (selective fields with comma syntax)\n- include=tenant[api|company_industry] (selective fields with pipe syntax)\n- include=tenant.posts (nested relationship - all fields)\n- include=tenant[name].posts[title] (nested with field selection at each level)\n- include=tenant[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=tenant.posts[title],tenant.comments[body] (multiple nested from same parent)\n- include=tenant[name],creator[id] (multiple relationships with field selection)\n- include=tenant[email|name].posts[title],creator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter clients by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the clients. Available options: created_at, prefered_currency, bank_name (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "company_name", "in": "query", "required": false, "description": "Filter clients resource. Description: This is a exact match for company_name (e.g., company_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -company_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "bank_name", "in": "query", "required": false, "description": "Filter clients resource. Description: This is a exact match for bank_name (e.g., bank_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -bank_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "prefered_currency", "in": "query", "required": false, "description": "Filter clients resource. Description: This is a exact match for prefered_currency (e.g., prefered_currency=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -prefered_currency=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter clients resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 7, "path": "https://demo.growee.test/api/restify/clients", "per_page": 1, "to": 1, "total": 7 }, "links": { "first": "https://demo.growee.test/api/restify/clients?page=1", "next": "https://demo.growee.test/api/restify/clients?page=2", "path": "https://demo.growee.test/api/restify/clients", "prev": null, "filters": "/api/restify/clients/filters" }, "data": [ { "id": "01kxdwdz8ch3ce36rdggs01npf", "type": "clients", "attributes": { "id": "01kxdwdz8ch3ce36rdggs01npf", "company_name": "Intern", "prefered_currency": "EUR", "company_address": { "city": null, "state": null, "street": null, "country": null, "zip_code": null }, "lifecycle_stage": "lead", "created_at": "2026-07-13T13:59:55.000000Z", "is_used": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "clients-store", "summary": "Create a client", "tags": [ "Clients" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_name": { "description": "The legal or trading name of the client company. Required and must be unique per tenant; this is the primary human-readable identifier for the client.", "type": "string" }, "description": { "description": "Free-text notes about the client company (may contain HTML). Used for internal context and AI enrichment.", "type": "string" }, "website": { "description": "The client's full website URL (e.g. https://acme.com); a trailing slash is stripped on save. Nullable, max 255 characters.", "maxLength": 255, "type": "string" }, "prefered_currency": { "description": "The client's preferred billing currency as an ISO 4217 code (e.g. EUR, USD, RON). Used as the default currency when invoicing this client.", "type": "string" }, "company_identifier": { "description": "The client's legal company registration number (e.g. trade register / company number), used on invoices and contracts.", "type": "string" }, "company_vat": { "description": "The client's VAT / tax identification number, printed on invoices for tax purposes.", "type": "string" }, "representative_name": { "description": "Full name of the client's legal representative or signatory used on generated documents and contracts.", "type": "string" }, "representative_position": { "description": "Job title of the client's legal representative (e.g. \"CEO\", \"Managing Director\"), shown alongside representative_name on documents.", "type": "string" }, "company_address": { "description": "The client's postal/billing address, stored as a JSON object (structured address parts). Appears on invoices and contracts.", "type": "object" }, "bank_name": { "description": "Name of the client's bank, used for payment details on invoices.", "type": "string" }, "bank_account": { "description": "The client's bank account number / IBAN. Stored encrypted at rest.", "type": "string" }, "bank_swift": { "description": "The SWIFT/BIC code of the client's bank for international transfers. Stored encrypted at rest.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" }, "domain": { "description": "The client's primary web domain without protocol (e.g. \"acme.com\"). CRM attribute used to match and deduplicate organizations. Nullable, max 200 characters.", "maxLength": 200, "type": "string" }, "industry": { "description": "Free-text industry / sector of the client company (e.g. \"Software\", \"Manufacturing\"). CRM segmentation attribute. Nullable, max 100 characters.", "maxLength": 100, "type": "string" }, "size": { "description": "Free-text company size, typically an employee-count band (e.g. \"1-10\", \"50-200\"). CRM segmentation attribute. Nullable, max 20 characters.", "maxLength": 20, "type": "string" }, "city": { "description": "City where the client is located. CRM attribute. Nullable, max 100 characters.", "maxLength": 100, "type": "string" }, "country": { "description": "Country where the client is located, as free text. CRM attribute. Nullable, max 100 characters.", "maxLength": 100, "type": "string" }, "lifecycle_stage": { "description": "CRM lifecycle stage of the client. One of: \"lead\", \"marketing_qualified\", \"sales_qualified\", \"customer\", \"churned\". Defaults to \"lead\" on creation; advance it as the relationship progresses.", "type": "string" }, "owner_id": { "description": "ULID foreign key to the employees table (an EmployeeRepository record) identifying the account owner responsible for this client. Must reference a non-deleted employee in the current tenant. Nullable.", "type": "string" }, "meta": { "description": "Free-form JSON metadata bag for extra CRM attributes not modeled as columns. Nullable object.", "type": "array" }, "logo_path": { "description": "The client's logo image file, stored on S3. On read it resolves to a temporary signed URL valid for 7 days; on write send an uploaded file.", "type": "string" } }, "required": [ "company_name" ] }, "example": { "company_name": "Intern", "prefered_currency": "EUR", "company_address": { "city": null, "state": null, "street": null, "country": null, "zip_code": null }, "lifecycle_stage": "lead" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientResource" } } }, "example": { "data": { "id": "01kxdwdz8ch3ce36rdggs01npf", "type": "clients", "attributes": { "id": "01kxdwdz8ch3ce36rdggs01npf", "company_name": "Intern", "prefered_currency": "EUR", "company_address": { "city": null, "state": null, "street": null, "country": null, "zip_code": null }, "lifecycle_stage": "lead", "created_at": "2026-07-13T13:59:55.000000Z", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/clients/{id}": { "get": { "operationId": "clients-show", "summary": "Retrieve a client", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientResource" } } }, "example": { "data": { "id": "01kxdwdz8ch3ce36rdggs01npf", "type": "clients", "attributes": { "id": "01kxdwdz8ch3ce36rdggs01npf", "company_name": "Intern", "prefered_currency": "EUR", "company_address": { "city": null, "state": null, "street": null, "country": null, "zip_code": null }, "lifecycle_stage": "lead", "created_at": "2026-07-13T13:59:55.000000Z", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "clients-update", "summary": "Update a client", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_name": { "description": "The legal or trading name of the client company. Required and must be unique per tenant; this is the primary human-readable identifier for the client.", "type": "string" }, "description": { "description": "Free-text notes about the client company (may contain HTML). Used for internal context and AI enrichment.", "type": "string" }, "website": { "description": "The client's full website URL (e.g. https://acme.com); a trailing slash is stripped on save. Nullable, max 255 characters.", "maxLength": 255, "type": "string" }, "prefered_currency": { "description": "The client's preferred billing currency as an ISO 4217 code (e.g. EUR, USD, RON). Used as the default currency when invoicing this client.", "type": "string" }, "company_identifier": { "description": "The client's legal company registration number (e.g. trade register / company number), used on invoices and contracts.", "type": "string" }, "company_vat": { "description": "The client's VAT / tax identification number, printed on invoices for tax purposes.", "type": "string" }, "representative_name": { "description": "Full name of the client's legal representative or signatory used on generated documents and contracts.", "type": "string" }, "representative_position": { "description": "Job title of the client's legal representative (e.g. \"CEO\", \"Managing Director\"), shown alongside representative_name on documents.", "type": "string" }, "company_address": { "description": "The client's postal/billing address, stored as a JSON object (structured address parts). Appears on invoices and contracts.", "type": "object" }, "bank_name": { "description": "Name of the client's bank, used for payment details on invoices.", "type": "string" }, "bank_account": { "description": "The client's bank account number / IBAN. Stored encrypted at rest.", "type": "string" }, "bank_swift": { "description": "The SWIFT/BIC code of the client's bank for international transfers. Stored encrypted at rest.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" }, "domain": { "description": "The client's primary web domain without protocol (e.g. \"acme.com\"). CRM attribute used to match and deduplicate organizations. Nullable, max 200 characters.", "maxLength": 200, "type": "string" }, "industry": { "description": "Free-text industry / sector of the client company (e.g. \"Software\", \"Manufacturing\"). CRM segmentation attribute. Nullable, max 100 characters.", "maxLength": 100, "type": "string" }, "size": { "description": "Free-text company size, typically an employee-count band (e.g. \"1-10\", \"50-200\"). CRM segmentation attribute. Nullable, max 20 characters.", "maxLength": 20, "type": "string" }, "city": { "description": "City where the client is located. CRM attribute. Nullable, max 100 characters.", "maxLength": 100, "type": "string" }, "country": { "description": "Country where the client is located, as free text. CRM attribute. Nullable, max 100 characters.", "maxLength": 100, "type": "string" }, "lifecycle_stage": { "description": "CRM lifecycle stage of the client. One of: \"lead\", \"marketing_qualified\", \"sales_qualified\", \"customer\", \"churned\". Defaults to \"lead\" on creation; advance it as the relationship progresses.", "type": "string" }, "owner_id": { "description": "ULID foreign key to the employees table (an EmployeeRepository record) identifying the account owner responsible for this client. Must reference a non-deleted employee in the current tenant. Nullable.", "type": "string" }, "meta": { "description": "Free-form JSON metadata bag for extra CRM attributes not modeled as columns. Nullable object.", "type": "array" }, "logo_path": { "description": "The client's logo image file, stored on S3. On read it resolves to a temporary signed URL valid for 7 days; on write send an uploaded file.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "clients-destroy", "summary": "Delete a client", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/clients/getters/client-profitability": { "get": { "operationId": "clients-getter-client-profitability", "summary": "Client profitability", "description": "Returns a month-by-month profitability breakdown per client over a date range: invoiced amount, paid amount, projected cost, actual cost, and both projected and actual profitability (revenue minus cost), plus per-client totals. Optional inputs: start_date and end_date (dates, default to the current calendar month) and client_ids (array of client ULIDs to restrict the report; omit for all clients). Amounts are in the tenant's configured base currency and only invoices in that currency are counted. Call this when an agent needs to analyze how much money each client makes or loses over time; it reads data only and changes nothing.", "tags": [ "Project Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/clients/{id}/actions": { "post": { "operationId": "clients-record-actions", "summary": "Actions: generate-documents, generate-review-link, upload-base64, ...", "description": "Perform an action on a single client. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`generate-documents`** - No description.\n- **`generate-review-link`** - No description.\n- **`upload-base64`** - Creates and stores a new CRM document from a base64-encoded file, attaching it to a client, lead, or client contact. This is the MCP/API-friendly alternative to the multipart upload endpoint. Payload keys: \"file\" (required, the base64-encoded content, raw or data-URI), \"file_name\" (required, the name to store the file under including extension), \"record_id\" (required, the ULID of the parent record), and \"record_type\" (optional, one of client/lead/client_contact — defaults to \"client\"). The file must decode to at most ~25 MB. On success it persists the file to storage and returns the created document metadata (id, name, mime, size, source, path). Use this whenever an agent needs to attach a file to a CRM record.\n- **`create-upload-url`** - Start a large-file upload for a client document without sending the bytes through the model. This is step 1 of a 3-step flow: (1) call this action with the client record_id and file_name to receive an upload_url and upload_token; (2) PUT the raw file bytes to upload_url exactly once (method PUT, using the returned headers); send a Content-Type header matching the file (e.g. application/pdf) so it is recorded on the stored object, though the server sniffs the real mime from the stored bytes regardless of what you send; (3) call the finalize-upload action with the upload_token to create the CRM document. Optionally pass sha256 and size so finalize can verify the stored bytes.\n- **`finalize-upload`** - Finalize a pre-signed client document upload: pass the upload_token returned by create-upload-url after you have PUT the file bytes to the upload_url. Creates and returns the CRM document.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "generate-documents", "generate-review-link", "upload-base64", "create-upload-url", "finalize-upload" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "generate-documents", "type": "object", "properties": {} }, { "title": "generate-review-link", "type": "object", "properties": {} }, { "title": "upload-base64", "type": "object", "properties": { "record_type": { "description": "Must be one of: client_contact, lead, client", "enum": [ "client_contact", "lead", "client" ], "type": "string" }, "record_id": { "description": "Maximum length: 26 characters", "maxLength": 26, "type": "string" }, "file": { "description": "This field is required", "type": "string" }, "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" } } }, { "title": "create-upload-url", "type": "object", "properties": { "record_id": { "description": "Maximum length: 26 characters", "maxLength": 26, "type": "string" }, "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "sha256": { "description": "This field is optional", "type": "string" }, "size": { "description": "Maximum value: 26214400", "minimum": 1, "maximum": 26214400, "type": "integer" } } }, { "title": "finalize-upload", "type": "object", "properties": { "upload_token": { "description": "This field is required", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/client-contacts": { "get": { "operationId": "client-contacts-index", "summary": "List client contacts", "description": "Manages client contacts: the individual people (name, email, phone, position) who work at a client company, stored in the client_contacts table. Each contact belongs to one company via client_id (exposed to the CRM frontend as organization_id, both pointing at the same clients row) and can own several email addresses through the related client-contact-emails repository. Contacts are the people you email and against whom interactions are logged, whereas the client/organization is the company itself. Each row also carries a read-only verification_status derived from CRM email verification. Use this repository to find or manage the humans you communicate with at a customer.", "tags": [ "Clients" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of client-contacts per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- client (fields: bank_account, bank_name, bank_swift, city, company_address, company_identifier, company_name, company_vat, country, created_at, custom_fields, description, domain, id, industry, is_used, lifecycle_stage, logo_path, meta, owner_id, prefered_currency, representative_name, representative_position, size, website)\n- organization (fields: city, company_name, country, created_at, created_by, custom_fields, domain, id, industry, is_demo, lifecycle_stage, meta, owner_id, size, tenant_id, updated_at, updated_by, website)\n- emails (fields: client_contact_id, created_at, email, id, is_primary, updated_at)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=creator,client (include all fields)\n- include=creator[archived_at,avatar] (selective fields with comma syntax)\n- include=creator[archived_at|avatar] (selective fields with pipe syntax)\n- include=creator.posts (nested relationship - all fields)\n- include=creator[name].posts[title] (nested with field selection at each level)\n- include=creator[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=creator.posts[title],creator.comments[body] (multiple nested from same parent)\n- include=creator[name],client[id] (multiple relationships with field selection)\n- include=creator[email|name].posts[title],client[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter client-contacts by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the client-contacts. Available options: client_contacts.id (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter client-contacts resource. Description: This is a exact match for client_id (e.g., client_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -client_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientContactResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 9, "path": "https://demo.growee.test/api/restify/client-contacts", "per_page": 1, "to": 1, "total": 9 }, "links": { "first": "https://demo.growee.test/api/restify/client-contacts?page=1", "next": "https://demo.growee.test/api/restify/client-contacts?page=2", "path": "https://demo.growee.test/api/restify/client-contacts", "prev": null, "filters": "/api/restify/client-contacts/filters" }, "data": [ { "id": "01kwt1xszv4vzkgjk8a028sm51", "type": "client_contacts", "attributes": { "id": "01kwt1xszv4vzkgjk8a028sm51", "name": "Rachel Donovan", "email": "rachel.donovan@craftmedia.example.com", "phone": "+1 212 555 0147", "position": "VP Product", "organization_id": "01kwt1xszttmp3jwatej49q4qe", "client_id": "01kwt1xszttmp3jwatej49q4qe" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "client-contacts-store", "summary": "Create a client contact", "tags": [ "Clients" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name of the contact person. Required on create; the primary human-readable label for the contact.", "type": "string" }, "email": { "description": "The contact's primary email address. Required on create and must be a valid email. This is the display address; additional addresses are managed via the client-contact-emails repository.", "type": "string" }, "phone": { "description": "The contact's phone number as free text. Optional.", "type": "string" }, "position": { "description": "The contact's job title or role at the company (e.g. \"Head of Procurement\"). Optional.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" }, "client_id": { "description": "ULID foreign key to the clients table (a ClientRepository / organization record) identifying the company this contact works at. Required on create; may be sent as organization_id, which is mirrored onto client_id.", "type": "string" } }, "required": [ "name", "email", "client_id" ] }, "example": { "name": "Rachel Donovan", "email": "rachel.donovan@craftmedia.example.com", "phone": "+1 212 555 0147", "position": "VP Product", "client_id": "01kwt1xszttmp3jwatej49q4qe" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientContactResource" } } }, "example": { "data": { "id": "01kwt1xszv4vzkgjk8a028sm51", "type": "client_contacts", "attributes": { "id": "01kwt1xszv4vzkgjk8a028sm51", "name": "Rachel Donovan", "email": "rachel.donovan@craftmedia.example.com", "phone": "+1 212 555 0147", "position": "VP Product", "organization_id": "01kwt1xszttmp3jwatej49q4qe", "client_id": "01kwt1xszttmp3jwatej49q4qe" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/client-contacts/{id}": { "get": { "operationId": "client-contacts-show", "summary": "Retrieve a client contact", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client contact ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client contact detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientContactResource" } } }, "example": { "data": { "id": "01kwt1xszv4vzkgjk8a028sm51", "type": "client_contacts", "attributes": { "id": "01kwt1xszv4vzkgjk8a028sm51", "name": "Rachel Donovan", "email": "rachel.donovan@craftmedia.example.com", "phone": "+1 212 555 0147", "position": "VP Product", "organization_id": "01kwt1xszttmp3jwatej49q4qe", "client_id": "01kwt1xszttmp3jwatej49q4qe" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "client-contacts-update", "summary": "Update a client contact", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client contact ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name of the contact person. Required on create; the primary human-readable label for the contact.", "type": "string" }, "email": { "description": "The contact's primary email address. Required on create and must be a valid email. This is the display address; additional addresses are managed via the client-contact-emails repository.", "type": "string" }, "phone": { "description": "The contact's phone number as free text. Optional.", "type": "string" }, "position": { "description": "The contact's job title or role at the company (e.g. \"Head of Procurement\"). Optional.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" }, "client_id": { "description": "ULID foreign key to the clients table (a ClientRepository / organization record) identifying the company this contact works at. Required on create; may be sent as organization_id, which is mirrored onto client_id.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientContactResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "client-contacts-destroy", "summary": "Delete a client contact", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client contact ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/client-contacts/{id}/actions": { "post": { "operationId": "client-contacts-record-actions", "summary": "Actions: send-email", "description": "Perform an action on a single client contact. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`send-email`** - Send a one-to-one CRM email to a single client contact from the current employee's sender identity. Runs on a specific contact (show scope) and requires the payload keys subject (string, max 300) and body (string, max 20000). Side effects: the email is queued and sent asynchronously and the send is logged as an interaction on the contact; it counts against per-tenant/per-user rate limits and the sender's daily cap (returns 429 or 422 when a limit is reached). The contact must have an email address. Use this when an agent should actually email a person, not merely record a note.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client contact ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "send-email" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "title": "send-email", "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoices": { "get": { "operationId": "invoices-index", "summary": "List invoices", "description": "Manages client invoices (the \"invoices\" table) for the current tenant. Each invoice belongs to a client and optionally to a project, carries monetary totals (subtotal, tax, total) in a chosen currency, and moves through a status lifecycle (draft, sent, late, partially_paid, paid). Invoices own their line items (invoice-lines repository) and an immutable audit trail (invoice-history repository), and can be sent by email, reminded, marked paid, shared via a public token, or exported to Romanian ANAF e-Factura XML. Use this repository to list, search, sort and filter invoices, inspect their payment state, and understand a client's or project's billing. Reply-to sender addresses used when emailing invoices are managed separately in the invoice-reply-mails repository.", "tags": [ "Invoicing" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of invoices per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- lineItems (fields: created_at, id, invoice_id, name, quantity, total, unit_price)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- client (fields: bank_account, bank_name, bank_swift, city, company_address, company_identifier, company_name, company_vat, country, created_at, custom_fields, description, domain, id, industry, is_used, lifecycle_stage, logo_path, meta, owner_id, prefered_currency, representative_name, representative_position, size, website)\n- project (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- files (fields: created_at, downloadable_path, employee_id, file_name, fileable_id, fileable_type, id, path, size)\n- history (fields: created_at, created_by, event, id, title, updated_at)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=lineItems,creator (include all fields)\n- include=lineItems[created_at,id] (selective fields with comma syntax)\n- include=lineItems[created_at|id] (selective fields with pipe syntax)\n- include=lineItems.posts (nested relationship - all fields)\n- include=lineItems[name].posts[title] (nested with field selection at each level)\n- include=lineItems[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=lineItems.posts[title],lineItems.comments[body] (multiple nested from same parent)\n- include=lineItems[name],creator[id] (multiple relationships with field selection)\n- include=lineItems[email|name].posts[title],creator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter invoices by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the invoices. Available options: subtotal, paid_at, created_at, total, tax, issue_date, due_date, title, currency (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a exact match for client_id (e.g., client_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -client_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a exact match for project_id (e.g., project_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -project_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "paid_at", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a range match for paid_at (e.g., paid_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -paid_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "issue_date", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a range match for issue_date (e.g., issue_date=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -issue_date=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "due_date", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a range match for due_date (e.g., due_date=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -due_date=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter invoices resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 87, "path": "https://demo.growee.test/api/restify/invoices", "per_page": 1, "to": 1, "total": 87, "total_unpaid": 8500, "total_paid": 0 }, "links": { "first": "https://demo.growee.test/api/restify/invoices?page=1", "next": "https://demo.growee.test/api/restify/invoices?page=2", "path": "https://demo.growee.test/api/restify/invoices", "prev": null, "filters": "/api/restify/invoices/filters" }, "data": [ { "id": "01kwt1xxafxpb7m9tmdxxrymbe", "type": "invoices", "attributes": { "id": "01kwt1xxafxpb7m9tmdxxrymbe", "issue_date": "2026-07-04T00:00:00.000000Z", "due_date": "2026-08-03T00:00:00.000000Z", "title": "Nordwind SLA & Support — June 2026", "invoice_number": "INV-2026-0050", "status": "draft", "client_id": "01kwt1xszjavwxk26b3sz0rnbv", "project_id": "01kwt1xt3ymfrm4ekzsyhcm2b8", "subtotal": 8500, "total": 8500, "tax": 0, "paid_amount": 0, "disable_payment_reminders": false, "from_address": { "name": "Demo Company", "address": "Strada Eroilor 1, Cluj-Napoca, Romania" }, "to_address": { "name": "Nordwind Logistics GmbH", "address": "Speicherstadt 14, Hamburg, Germany" }, "created_at": "2026-07-05T21:11:11.000000Z", "currency": "EUR" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "invoices-store", "summary": "Create an invoice", "tags": [ "Invoicing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issue_date": { "description": "The date when the invoice was issued. Example: 2023-10-15", "type": "string" }, "due_date": { "description": "The date when the invoice is due. Example: 2023-11-15. By default use 30 days after issue date.", "type": "string" }, "title": { "description": "A brief title or description for the invoice. Example: 'Web Development Services for October 2023'", "type": "string" }, "notes": { "description": "Additional notes or terms related to the invoice. Keep empty by default unless the user asks to fill it. Example: 'Payment is due within 30 days. Late payments may incur a fee.'", "type": "string" }, "client_id": { "description": "The client associated with the invoice. This field is required. Get the client from the clients list.", "type": "string" }, "project_id": { "description": "The project associated with the invoice. This field is optional. If provided, the project must belong to the selected client. You can get the project from the projects list and filter by client_id.", "type": "string" }, "subtotal": { "description": "The net amount before tax, as a decimal number in the invoice currency (e.g. 1000.00). This is the sum of the line items before tax.", "type": "number" }, "total": { "description": "The gross amount the client owes including tax, as a decimal number in the invoice currency (e.g. 1190.00). Usually subtotal plus tax.", "type": "number" }, "tax": { "description": "The tax amount included in the total, as a decimal number in the invoice currency (e.g. 190.00). Optional; omit or set 0 when no tax applies.", "type": "number" }, "currency": { "description": "The currency for the invoice. You can choose from the list of available currencies: USD, EUR, GBP, AUD, CAD, JPY, BYR, AED, AFN, ALL, AMD, ANG, AOA, ARS, AWG, AZN, BAM, BBD, BCH, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BZD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, FJD, FKP, GBX, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMM, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZWD. If not specified, it will default to EUR.", "enum": [ "USD", "EUR", "GBP", "AUD", "CAD", "JPY", "BYR", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BZD", "CDF", "CHF", "CLF", "CLP", "CNH", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EEK", "EGP", "ERN", "ETB", "FJD", "FKP", "GBX", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MTL", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SKK", "SLE", "SLL", "SOS", "SRD", "SSP", "STD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMM", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "UYU", "UZS", "VEF", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XFU", "XOF", "XPD", "XPF", "XPT", "YER", "ZAR", "ZMK", "ZWD" ], "type": "string" } }, "required": [ "client_id", "subtotal", "total" ] }, "example": { "issue_date": "2026-07-04T00:00:00.000000Z", "due_date": "2026-08-03T00:00:00.000000Z", "title": "Nordwind SLA & Support — June 2026", "client_id": "01kwt1xszjavwxk26b3sz0rnbv", "project_id": "01kwt1xt3ymfrm4ekzsyhcm2b8", "subtotal": 8500, "total": 8500, "tax": 0, "currency": "EUR" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceResource" } } }, "example": { "data": { "id": "01kwt1xxafxpb7m9tmdxxrymbe", "type": "invoices", "attributes": { "id": "01kwt1xxafxpb7m9tmdxxrymbe", "issue_date": "2026-07-04T00:00:00.000000Z", "due_date": "2026-08-03T00:00:00.000000Z", "title": "Nordwind SLA & Support — June 2026", "invoice_number": "INV-2026-0050", "status": "draft", "client_id": "01kwt1xszjavwxk26b3sz0rnbv", "project_id": "01kwt1xt3ymfrm4ekzsyhcm2b8", "subtotal": 8500, "total": 8500, "tax": 0, "paid_amount": 0, "disable_payment_reminders": false, "from_address": { "name": "Demo Company", "address": "Strada Eroilor 1, Cluj-Napoca, Romania" }, "to_address": { "name": "Nordwind Logistics GmbH", "address": "Speicherstadt 14, Hamburg, Germany" }, "created_at": "2026-07-05T21:11:11.000000Z", "currency": "EUR" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoices/{id}": { "get": { "operationId": "invoices-show", "summary": "Retrieve an invoice", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceResource" } } }, "example": { "data": { "id": "01kwt1xxafxpb7m9tmdxxrymbe", "type": "invoices", "attributes": { "id": "01kwt1xxafxpb7m9tmdxxrymbe", "issue_date": "2026-07-04T00:00:00.000000Z", "due_date": "2026-08-03T00:00:00.000000Z", "title": "Nordwind SLA & Support — June 2026", "invoice_number": "INV-2026-0050", "status": "draft", "client_id": "01kwt1xszjavwxk26b3sz0rnbv", "project_id": "01kwt1xt3ymfrm4ekzsyhcm2b8", "subtotal": 8500, "total": 8500, "tax": 0, "paid_amount": 0, "disable_payment_reminders": false, "from_address": { "name": "Demo Company", "address": "Strada Eroilor 1, Cluj-Napoca, Romania" }, "to_address": { "name": "Nordwind Logistics GmbH", "address": "Speicherstadt 14, Hamburg, Germany" }, "created_at": "2026-07-05T21:11:11.000000Z", "currency": "EUR" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "invoices-update", "summary": "Update an invoice", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paid_at": { "description": "Date the invoice was fully paid (Y-m-d), or null if it is not yet fully paid. Set automatically when the invoice is marked as paid; a non-null value together with a paid status means the invoice is settled.", "type": "string" }, "issue_date": { "description": "The date the invoice was issued, in Y-m-d format (e.g. 2023-10-15).", "type": "string" }, "due_date": { "description": "The date payment is due, in Y-m-d format (e.g. 2023-11-15); typically 30 days after the issue date.", "type": "string" }, "title": { "description": "Short human-readable title or summary of what the invoice is for (e.g. \"Web Development Services for October 2023\").", "type": "string" }, "invoice_number": { "description": "The tenant-unique invoice number/reference shown to the client (e.g. \"INV-2023-001\"). Must be unique within the current tenant.", "type": "string" }, "notes": { "description": "Free-text notes or payment terms printed on the invoice (e.g. \"Payment is due within 30 days.\"). Empty by default.", "type": "string" }, "status": { "description": "Lifecycle status of the invoice. One of: draft, sent, late, partially_paid, paid.", "type": "string" }, "client_id": { "description": "ULID foreign key of the Client (clients repository) that is billed by this invoice. Required.", "type": "string" }, "project_id": { "description": "Optional ULID foreign key of the Project (projects repository) this invoice relates to. If set, the project must belong to the same client as client_id.", "type": "string" }, "subtotal": { "description": "Net amount before tax, as a decimal number in the invoice currency (e.g. 1000.00).", "type": "integer" }, "total": { "description": "Gross amount the client owes including tax, as a decimal number in the invoice currency (e.g. 1190.00).", "type": "integer" }, "tax": { "description": "Tax amount included in the total, as a decimal number in the invoice currency (e.g. 190.00). Optional.", "type": "integer" }, "disable_payment_reminders": { "description": "When true, automatic overdue payment reminder emails are suppressed for this invoice. Defaults to false.", "type": "boolean" }, "from_address": { "description": "JSON object holding the sender/issuer address details (the tenant's billing-from address) shown on the invoice.", "type": "array" }, "to_address": { "description": "JSON object holding the recipient/client address details (bill-to address) shown on the invoice.", "type": "array" }, "currency": { "description": "ISO currency code for all monetary amounts on this invoice (e.g. EUR, USD, RON, GBP). Defaults to EUR when not provided.", "enum": [ "USD", "EUR", "GBP", "AUD", "CAD", "JPY", "BYR", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BZD", "CDF", "CHF", "CLF", "CLP", "CNH", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EEK", "EGP", "ERN", "ETB", "FJD", "FKP", "GBX", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MTL", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SKK", "SLE", "SLL", "SOS", "SRD", "SSP", "STD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMM", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "UYU", "UZS", "VEF", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XFU", "XOF", "XPD", "XPF", "XPT", "YER", "ZAR", "ZMK", "ZWD" ], "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "invoices-destroy", "summary": "Delete an invoice", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices/getters/chart": { "get": { "operationId": "invoices-getter-chart", "summary": "Chart", "description": "Returns invoiced and paid amounts aggregated by month for a single year, for building a revenue/cash-flow chart. Each month entry includes the total invoiced amount, the total paid amount, and a per-currency breakdown of both. Optional \"year\" payload (format YYYY) selects the year; defaults to the current year. Requires manage-invoices permission.", "tags": [ "Finance Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/invoices/getters/invoice-analytics": { "get": { "operationId": "invoices-getter-invoice-analytics", "summary": "Invoice analytics", "description": "", "tags": [ "Finance Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/invoices/{id}/actions": { "post": { "operationId": "invoices-record-actions", "summary": "Actions: share-invoice, mark-as-paid, send-invoice, ...", "description": "Perform an action on a single invoice. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`share-invoice`** - Generate a new public share token for this invoice and return it. Use this when the user wants a shareable link that lets the client view the invoice without logging in. Regenerating replaces the previously used token. Requires manage-invoices permission; takes no payload.\n- **`mark-as-paid`** - Record a payment against this invoice and update its status. Use this when the user reports that the client has paid. Optional payload: \"amount\" (decimal in the invoice currency) records a partial payment — omit it to pay the remaining balance in full; \"date\" (a date) sets when the payment was received, defaulting to now. When the cumulative paid amount reaches the total the invoice becomes paid (paid_at set), otherwise it becomes partially_paid. Returns the updated invoice.\n- **`send-invoice`** - Email this invoice to one or more recipients and mark it as sent. Use this to deliver the invoice to the client. Required payload: \"recipients\" (array of email addresses), \"subject\" (string), \"body\" (string) and \"attach_pdf\" (boolean — whether to attach the invoice PDF). Optional \"reply_to_email\" overrides the reply-to sender address. The email is queued and sent asynchronously, and the invoice status transitions to sent.\n- **`replicate`** - Duplicate this invoice into a new draft invoice, copying its client, project and line items but resetting payment/sending state and setting fresh issue and due dates. Use this to quickly create a recurring or similar invoice. Requires a \"new_invoice_number\" (string) that is unique within the tenant. Returns the newly created invoice.\n- **`remind`** - Send a payment reminder email to the recipients this invoice was originally sent to. Use this to chase an unpaid or overdue invoice. Requires \"subject\" and \"body\" (both strings) in the payload. Only works if the invoice has already been sent (has recipients); otherwise returns a 400. The email is queued and sent asynchronously.\n- **`generate-xml`** - Generate the Romanian ANAF e-Factura (e-invoice) XML document for this invoice and return it. Use this when the user needs the standardized XML representation of the invoice for e-Factura submission. Accepts an optional boolean \"validate\" payload key; when true the generated XML is validated against ANAF and validation errors are returned instead of the document. Returns a 422 with a message when the invoice or XML is invalid.\n- **`upload-efactura`** - Generate and upload this invoice's e-Factura XML to the Romanian ANAF e-invoicing system, attaching the resulting document to the invoice files. Use this to officially submit the invoice to ANAF. Requires no payload. Returns the invoice with its updated files, or a 422 with a message when the XML fails validation.\n- **`validate-xml`** - Validate an e-Factura XML document against the Romanian ANAF rules and return the validation result. Use this to check that an e-invoice XML is well-formed and compliant before submitting it. The raw XML is sent as the request body. Standalone action tied to no specific invoice; returns a 422 with a message when the XML is invalid.\n- **`test-anaf-connection`** - Test the tenant's connection to the Romanian ANAF e-Factura API and return the result. Use this to verify that ANAF e-invoicing credentials/connectivity are working before generating or uploading e-Factura documents. Standalone action that operates on no specific invoice and needs no payload.", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "share-invoice", "mark-as-paid", "send-invoice", "replicate", "remind", "generate-xml", "upload-efactura", "validate-xml", "test-anaf-connection" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "share-invoice", "type": "object", "properties": {} }, { "title": "mark-as-paid", "type": "object", "properties": { "date": { "description": "This field is required", "type": "string" }, "amount": { "description": "Minimum value: 0.01", "minimum": 0, "type": "number" } } }, { "title": "send-invoice", "type": "object", "properties": { "recipients": { "description": "Must be an array", "type": "array" }, "recipients.*": { "type": "string" }, "subject": { "description": "This field is required", "type": "string" }, "reply_to_email": { "description": "This field is optional", "type": "string" }, "body": { "description": "This field is required", "type": "string" }, "attach_pdf": { "description": "Must be a boolean (true/false)", "type": "boolean" } } }, { "title": "replicate", "type": "object", "properties": { "new_invoice_number": { "description": "Must be unique in the database.", "type": "string" } } }, { "title": "remind", "type": "object", "properties": { "subject": { "description": "This field is required", "type": "string" }, "body": { "description": "This field is required", "type": "string" } } }, { "title": "generate-xml", "type": "object", "properties": { "validate": { "description": "Must be a boolean (true/false)", "type": "boolean" } } }, { "title": "upload-efactura", "type": "object", "properties": {} }, { "title": "validate-xml", "type": "object", "properties": {} }, { "title": "test-anaf-connection", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoice-lines": { "get": { "operationId": "invoice-lines-index", "summary": "List invoice lines", "description": "Manages the individual line items of invoices (the \"invoice_lines\" table). Each row belongs to one invoice (invoices repository) and represents a single billed product or service with a name, optional quantity and unit_price, and a computed total. Use this repository to list, search or filter the breakdown of what an invoice charges for, or to add/adjust the itemized detail behind an invoice.", "tags": [ "Invoicing" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of invoice-lines per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- invoice (fields: client_id, created_at, currency, disable_payment_reminders, due_date, from_address, id, invoice_number, issue_date, notes, paid_amount, paid_at, project_id, share_token, status, subtotal, tax, title, to_address, total)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=invoice,creator (include all fields)\n- include=invoice[client_id,created_at] (selective fields with comma syntax)\n- include=invoice[client_id|created_at] (selective fields with pipe syntax)\n- include=invoice.posts (nested relationship - all fields)\n- include=invoice[name].posts[title] (nested with field selection at each level)\n- include=invoice[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=invoice.posts[title],invoice.comments[body] (multiple nested from same parent)\n- include=invoice[name],creator[id] (multiple relationships with field selection)\n- include=invoice[email|name].posts[title],creator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter invoice-lines by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the invoice-lines. Available options: name, created_at, quantity, total, unit_price (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "required": false, "description": "Filter invoice-lines resource. Description: This is a exact match for invoice_id (e.g., invoice_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -invoice_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter invoice-lines resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 373, "path": "https://demo.growee.test/api/restify/invoice-lines", "per_page": 1, "to": 1, "total": 373 }, "links": { "first": "https://demo.growee.test/api/restify/invoice-lines?page=1", "next": "https://demo.growee.test/api/restify/invoice-lines?page=2", "path": "https://demo.growee.test/api/restify/invoice-lines", "prev": null, "filters": "/api/restify/invoice-lines/filters" }, "data": [ { "id": "01kwt1xxapesnhzj97nq7sxha2", "type": "invoice_lines", "attributes": { "id": "01kwt1xxapesnhzj97nq7sxha2", "name": "Monthly retainer — June 2026", "quantity": 1, "unit_price": 8500, "total": 8500, "invoice_id": "01kwt1xxafxpb7m9tmdxxrymbe", "created_at": "2026-07-05T21:11:11.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "invoice-lines-store", "summary": "Create an invoice line", "tags": [ "Invoicing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Description of the billed product or service for this line (e.g. \"Senior developer hours\"). Required, max 500 characters.", "maxLength": 500, "type": "string" }, "quantity": { "description": "Number of units billed on this line as a decimal (e.g. 10 for 10 hours). Optional.", "type": "number" }, "unit_price": { "description": "Price per single unit as a decimal in the parent invoice currency (e.g. 50.00). Optional.", "type": "number" }, "total": { "description": "Line total as a decimal in the parent invoice currency, normally quantity multiplied by unit_price (e.g. 500.00). Required.", "type": "number" }, "invoice_id": { "description": "ULID foreign key of the parent Invoice (invoices repository) this line belongs to.", "type": "string" } }, "required": [ "name", "total" ] }, "example": { "name": "Monthly retainer — June 2026", "quantity": 1, "unit_price": 8500, "total": 8500, "invoice_id": "01kwt1xxafxpb7m9tmdxxrymbe" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceLineResource" } } }, "example": { "data": { "id": "01kwt1xxapesnhzj97nq7sxha2", "type": "invoice_lines", "attributes": { "id": "01kwt1xxapesnhzj97nq7sxha2", "name": "Monthly retainer — June 2026", "quantity": 1, "unit_price": 8500, "total": 8500, "invoice_id": "01kwt1xxafxpb7m9tmdxxrymbe", "created_at": "2026-07-05T21:11:11.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoice-lines/{id}": { "get": { "operationId": "invoice-lines-show", "summary": "Retrieve an invoice line", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice line ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice line detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceLineResource" } } }, "example": { "data": { "id": "01kwt1xxapesnhzj97nq7sxha2", "type": "invoice_lines", "attributes": { "id": "01kwt1xxapesnhzj97nq7sxha2", "name": "Monthly retainer — June 2026", "quantity": 1, "unit_price": 8500, "total": 8500, "invoice_id": "01kwt1xxafxpb7m9tmdxxrymbe", "created_at": "2026-07-05T21:11:11.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "invoice-lines-update", "summary": "Update an invoice line", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice line ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Description of the billed product or service for this line (e.g. \"Senior developer hours\"). Required, max 500 characters.", "type": "string" }, "quantity": { "description": "Number of units billed on this line as a decimal (e.g. 10 for 10 hours). Optional.", "type": "integer" }, "unit_price": { "description": "Price per single unit as a decimal in the parent invoice currency (e.g. 50.00). Optional.", "type": "number" }, "total": { "description": "Line total as a decimal in the parent invoice currency, normally quantity multiplied by unit_price (e.g. 500.00). Required.", "type": "integer" }, "invoice_id": { "description": "ULID foreign key of the parent Invoice (invoices repository) this line belongs to.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceLineResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "invoice-lines-destroy", "summary": "Delete an invoice line", "tags": [ "Invoicing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice line ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/expenses": { "get": { "operationId": "expenses-index", "summary": "List expenses", "description": "This repository manages individual expenses in the expenses table: single reimbursable costs (receipts, transport, meals, subscriptions) that an employee incurs and submits for approval and reimbursement. Each expense has a monetary amount in a given currency, an optional exchange_rate to the tenant base currency, a category, an optional project it should be billed to, and a receipt file. Expenses are typically grouped into an ExpenseBundle (Romanian: \"decont\"/travel report) via expense_bundle_id and move through the statuses pending, approved, rejected and paid. Use this repository to list, search, filter and stat individual expenses; use the ExpenseBundles repository to manage the grouping and bundle-level approval, and the ExpenseCategories repository for the category catalog.", "tags": [ "Expenses" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of expenses per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- project (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=project (include all fields)\n- include=project[archived,billing_model] (selective fields with comma syntax)\n- include=project[archived|billing_model] (selective fields with pipe syntax)\n- include=project.posts (nested relationship - all fields)\n- include=project[name].posts[title] (nested with field selection at each level)\n- include=project[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=project.posts[title],project.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter expenses by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the expenses. Available options: expenses.id (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "expense_bundle_id", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a exact match for expense_bundle_id (e.g., expense_bundle_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -expense_bundle_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "requested_approver_id", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a exact match for requested_approver_id (e.g., requested_approver_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -requested_approver_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "expense_category_id", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a exact match for expense_category_id (e.g., expense_category_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -expense_category_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a exact match for project_id (e.g., project_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -project_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "Filter expenses resource. Description: This is a date match for date (e.g., date=YYYY-MM-DD or date=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -date=YYYY-MM-DD or -date=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 89, "path": "https://demo.growee.test/api/restify/expenses", "per_page": 1, "to": 1, "total": 89, "by_currency": [ { "amount": 29694.39999999999, "currency": "EUR" } ] }, "links": { "first": "https://demo.growee.test/api/restify/expenses?page=1", "next": "https://demo.growee.test/api/restify/expenses?page=2", "path": "https://demo.growee.test/api/restify/expenses", "prev": null, "filters": "/api/restify/expenses/filters" }, "data": [ { "id": "01kwt1xxgkzq603zc082bgp5de", "type": "expenses", "attributes": { "id": "01kwt1xxgkzq603zc082bgp5de", "employee_id": "01kwt1xrdjz5jgk7t8trm4mt6e", "expense_category_id": "01kwt1xnace6xz2qbwevy86x73", "requested_approver_id": "01kwt1xp2nd6xx918qyhzwzf4h", "date": "2026-02-22T00:00:00.000000Z", "amount": "59.00", "currency": "EUR", "description": "Technical books", "approved_at": "2026-02-24T21:11:03.000000Z", "paid_at": "2026-03-08T21:11:03.000000Z", "status": "paid", "status_changed_by": "01kwt1xp2nd6xx918qyhzwzf4h", "is_demo": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "expenses-store", "summary": "Create an expense", "tags": [ "Expenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "The id of the employee submitting the expense. If not provided, it defaults to the currently authenticated employee.", "type": "string" }, "expense_bundle_id": { "description": "This is very important in order to be grouped with other expenses for approval and payment. Try to always provide it from the list of expense bundles.", "type": "string" }, "expense_category_id": { "description": "The ULID id of the ExpenseCategory (ExpenseCategories repository) this expense belongs to, e.g. transport, meals or accommodation. The category determines whether a receipt is required and any per-expense maximum amount.", "type": "string" }, "project_id": { "description": "If expense is related to a project, select it here.", "type": "string" }, "requested_approver_id": { "description": "The ULID id of the Employee (Employees repository) who is requested to approve this expense. Must be an employee of the current tenant; if omitted the organization approval workflow assigns the approver.", "type": "string" }, "date": { "description": "The calendar date the expense was incurred, in YYYY-MM-DD format. Defaults to today when not provided.", "type": "string" }, "amount": { "description": "The gross monetary amount of the expense as a positive decimal (two decimal places) expressed in the field currency, e.g. 42.50. Must be at least 0.01.", "minimum": 0, "type": "string" }, "currency": { "description": "The currency code in ISO 4217 format, e.g., USD, EUR. Must be one of: USD, EUR, GBP, AUD, CAD, JPY, BYR, AED, AFN, ALL, AMD, ANG, AOA, ARS, AWG, AZN, BAM, BBD, BCH, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BZD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, FJD, FKP, GBX, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMM, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZWD", "minLength": 3, "maxLength": 3, "type": "string" }, "description": { "description": "Free-text note describing what the expense was for (merchant, purpose). Optional but recommended so approvers understand the cost.", "type": "string" }, "status": { "description": "The approval lifecycle state of the expense. One of: pending (awaiting approval, the default), approved, rejected, or paid (reimbursed). Only users who can manage expenses may set it directly; otherwise it is driven by the approve/reject/mark-as-paid actions.", "enum": [ "pending", "approved", "rejected", "paid" ], "type": "string" }, "status_explanation": { "description": "Optional free-text reason recorded when the status changes, e.g. why the expense was rejected. Sent as the explanation payload by the approve/reject/mark-as-paid actions.", "type": "string" }, "receipt_filename": { "description": "Original filename of the uploaded receipt. You can keep it empty or provide an intuitive name if there is a file.", "type": "string" } }, "required": [ "amount" ] }, "example": { "employee_id": "01kwt1xrdjz5jgk7t8trm4mt6e", "expense_category_id": "01kwt1xnace6xz2qbwevy86x73", "requested_approver_id": "01kwt1xp2nd6xx918qyhzwzf4h", "date": "2026-02-22T00:00:00.000000Z", "amount": "59.00", "currency": "EUR", "description": "Technical books", "status": "paid" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExpenseResource" } } }, "example": { "data": { "id": "01kwt1xxgkzq603zc082bgp5de", "type": "expenses", "attributes": { "id": "01kwt1xxgkzq603zc082bgp5de", "employee_id": "01kwt1xrdjz5jgk7t8trm4mt6e", "expense_category_id": "01kwt1xnace6xz2qbwevy86x73", "requested_approver_id": "01kwt1xp2nd6xx918qyhzwzf4h", "date": "2026-02-22T00:00:00.000000Z", "amount": "59.00", "currency": "EUR", "description": "Technical books", "approved_at": "2026-02-24T21:11:03.000000Z", "paid_at": "2026-03-08T21:11:03.000000Z", "status": "paid", "status_changed_by": "01kwt1xp2nd6xx918qyhzwzf4h", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/expenses/{id}": { "get": { "operationId": "expenses-show", "summary": "Retrieve an expense", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Expense detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExpenseResource" } } }, "example": { "data": { "id": "01kwt1xxgkzq603zc082bgp5de", "type": "expenses", "attributes": { "id": "01kwt1xxgkzq603zc082bgp5de", "employee_id": "01kwt1xrdjz5jgk7t8trm4mt6e", "expense_category_id": "01kwt1xnace6xz2qbwevy86x73", "requested_approver_id": "01kwt1xp2nd6xx918qyhzwzf4h", "date": "2026-02-22T00:00:00.000000Z", "amount": "59.00", "currency": "EUR", "description": "Technical books", "approved_at": "2026-02-24T21:11:03.000000Z", "paid_at": "2026-03-08T21:11:03.000000Z", "status": "paid", "status_changed_by": "01kwt1xp2nd6xx918qyhzwzf4h", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "expenses-update", "summary": "Update an expense", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "The id of the employee submitting the expense. If not provided, it defaults to the currently authenticated employee.", "type": "string" }, "expense_bundle_id": { "description": "This is very important in order to be grouped with other expenses for approval and payment. Try to always provide it from the list of expense bundles.", "type": "string" }, "expense_category_id": { "description": "The ULID id of the ExpenseCategory (ExpenseCategories repository) this expense belongs to, e.g. transport, meals or accommodation. The category determines whether a receipt is required and any per-expense maximum amount.", "type": "string" }, "project_id": { "description": "If expense is related to a project, select it here.", "type": "string" }, "requested_approver_id": { "description": "The ULID id of the Employee (Employees repository) who is requested to approve this expense. Must be an employee of the current tenant; if omitted the organization approval workflow assigns the approver.", "type": "string" }, "date": { "description": "The calendar date the expense was incurred, in YYYY-MM-DD format. Defaults to today when not provided.", "type": "string" }, "amount": { "description": "The gross monetary amount of the expense as a positive decimal (two decimal places) expressed in the field currency, e.g. 42.50. Must be at least 0.01.", "type": "string" }, "currency": { "description": "The currency code in ISO 4217 format, e.g., USD, EUR. Must be one of: USD, EUR, GBP, AUD, CAD, JPY, BYR, AED, AFN, ALL, AMD, ANG, AOA, ARS, AWG, AZN, BAM, BBD, BCH, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BZD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, FJD, FKP, GBX, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMM, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZWD", "minLength": 3, "maxLength": 3, "type": "string" }, "description": { "description": "Free-text note describing what the expense was for (merchant, purpose). Optional but recommended so approvers understand the cost.", "type": "string" }, "status": { "description": "The approval lifecycle state of the expense. One of: pending (awaiting approval, the default), approved, rejected, or paid (reimbursed). Only users who can manage expenses may set it directly; otherwise it is driven by the approve/reject/mark-as-paid actions.", "enum": [ "pending", "approved", "rejected", "paid" ], "type": "string" }, "status_explanation": { "description": "Optional free-text reason recorded when the status changes, e.g. why the expense was rejected. Sent as the explanation payload by the approve/reject/mark-as-paid actions.", "type": "string" }, "receipt_filename": { "description": "Original filename of the uploaded receipt. You can keep it empty or provide an intuitive name if there is a file.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExpenseResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "expenses-destroy", "summary": "Delete an expense", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/expenses/getters/expense-stats": { "get": { "operationId": "expenses-getter-expense-stats", "summary": "Expense stats", "description": "Return aggregate statistics over individual expenses for the current tenant, respecting the caller permission scope. Responds with total_value (sum of amount * exchange_rate in the base currency) and pending_count, approved_count and rejected_count. Accepts the same optional filters as the listing (expense_bundle_id, employee_id, requested_approver_id, expense_category_id, project_id, status, and a \"start,end\" date range) to narrow the aggregation. Read-only; use it for dashboards and summaries instead of paging through every expense.", "tags": [ "Finance Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/expenses/getters/expense-analytics": { "get": { "operationId": "expenses-getter-expense-analytics", "summary": "Expense analytics", "description": "", "tags": [ "Finance Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/expenses/{id}/actions": { "post": { "operationId": "expenses-record-actions", "summary": "Actions: approve, reject, mark-as-paid, ...", "description": "Perform an action on a single expense. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`approve`** - Approve the target expense or expense bundle: sets its status to approved and records approved_at plus the approving employee. Optionally accepts a status_explanation note. Fails if the record is already approved or already paid, and requires the caller to be a tenant employee with approve permission. Call this when a submitted expense/bundle has been reviewed and should be cleared for reimbursement.\n- **`reject`** - Reject the target expense or expense bundle: sets its status to rejected and records rejected_at plus the rejecting employee. Optionally accepts a status_explanation note describing why it was rejected. Fails if the record is already rejected, approved or paid, and requires the caller to be a tenant employee with reject permission. Call this when a submitted expense/bundle should not be reimbursed.\n- **`mark-as-paid`** - Mark the target expense or expense bundle as reimbursed: sets its status to paid and records paid_at plus the employee who marked it. Optionally accepts a status_explanation note. Fails if the record is already paid, and requires the caller to be a tenant employee with the mark-as-paid permission. Call this once the money has actually been reimbursed to the employee.\n- **`download-expenses`** - Build and stream a downloadable ZIP archive bundling the selected expenses together with their receipt files. Operates on a collection of expenses (typically the current filtered list) and returns a binary file download rather than JSON. Use it to export receipts for accounting; it does not change any expense data.\n- **`create-upload-url`** - Start a large-file upload for an expense receipt without sending the bytes through the model. This is step 1 of a 3-step flow: (1) call this action with the expense_id and file_name to receive an upload_url and upload_token; (2) PUT the raw file bytes to upload_url exactly once (method PUT, using the returned headers); send a Content-Type header matching the file (e.g. application/pdf or image/jpeg) so it is recorded on the stored object, though the server sniffs the real mime from the stored bytes regardless of what you send; (3) call the finalize-upload action with the upload_token to attach the receipt to the expense. Only pdf and common image receipts are accepted. Optionally pass sha256 and size so finalize can verify the stored bytes.\n- **`finalize-upload`** - Finalize a pre-signed expense receipt upload: pass the upload_token returned by create-upload-url after you have PUT the file bytes to the upload_url. Attaches the receipt to the expense and returns it.", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "approve", "reject", "mark-as-paid", "download-expenses", "create-upload-url", "finalize-upload" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "approve", "type": "object", "properties": {} }, { "title": "reject", "type": "object", "properties": {} }, { "title": "mark-as-paid", "type": "object", "properties": {} }, { "title": "download-expenses", "type": "object", "properties": {} }, { "title": "create-upload-url", "type": "object", "properties": { "expense_id": { "description": "Maximum length: 26 characters", "maxLength": 26, "type": "string" }, "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "sha256": { "description": "This field is optional", "type": "string" }, "size": { "description": "Maximum value: 10485760", "minimum": 1, "maximum": 10485760, "type": "integer" } } }, { "title": "finalize-upload", "type": "object", "properties": { "upload_token": { "description": "This field is required", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/expense-categories": { "get": { "operationId": "expense-categories-index", "summary": "List expense categories", "description": "This repository manages the catalog of expense categories in the expense_categories table: the reusable classifications (transport, meals, accommodation, software, etc.) that individual expenses are grouped under within a tenant. Each category defines whether a receipt is required, an optional maximum allowed amount, a display color, and an optional document template used when generating expense paperwork. Use it to list or look up categories so their ULID id can be set as expense_category_id on expenses in the Expenses repository. A category cannot be deleted while expenses reference it.", "tags": [ "Expenses" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of expense-categories per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- expenses (fields: amount, approved_at, currency, date, description, employee_id, expense_bundle_id, expense_category_id, id, is_demo, paid_at, project_id, receipt_filename, rejected_at, requested_approver_id, status, status_changed_by, status_explanation)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=expenses (include all fields)\n- include=expenses[amount,approved_at] (selective fields with comma syntax)\n- include=expenses[amount|approved_at] (selective fields with pipe syntax)\n- include=expenses.posts (nested relationship - all fields)\n- include=expenses[name].posts[title] (nested with field selection at each level)\n- include=expenses[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=expenses.posts[title],expenses.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter expense-categories by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the expense-categories. Available options: name, requires_receipt, max_amount (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Filter expense-categories resource. Description: This is a exact match for name (e.g., name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "requires_receipt", "in": "query", "required": false, "description": "Filter expense-categories resource. Description: This is a exact match for requires_receipt (e.g., requires_receipt=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -requires_receipt=some_value). The filter type is string.", "schema": { "type": "boolean" } }, { "name": "max_amount", "in": "query", "required": false, "description": "Filter expense-categories resource. Description: This is a exact match for max_amount (e.g., max_amount=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -max_amount=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseCategoryResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 5, "path": "https://demo.growee.test/api/restify/expense-categories", "per_page": 1, "to": 1, "total": 5 }, "links": { "first": "https://demo.growee.test/api/restify/expense-categories?page=1", "next": "https://demo.growee.test/api/restify/expense-categories?page=2", "path": "https://demo.growee.test/api/restify/expense-categories", "prev": null, "filters": "/api/restify/expense-categories/filters" }, "data": [ { "id": "01kwt1xnadqb3fv3bex9bx31dy", "type": "expense_categories", "attributes": { "id": "01kwt1xnadqb3fv3bex9bx31dy", "name": "Client Entertainment", "description": "Business meals and client entertainment expenses", "requires_receipt": true, "max_amount": "300.00", "color": "#149ea3" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "expense-categories-store", "summary": "Create an expense category", "tags": [ "Expenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Unique human-readable name of the category, e.g. \"Transport\" or \"Accommodation\". Required, up to 255 characters.", "maxLength": 255, "type": "string" }, "description": { "description": "Optional free-text explanation of what expenses belong in this category.", "type": "string" }, "requires_receipt": { "description": "Boolean flag: when true, expenses in this category must have a receipt file attached. Defaults to true.", "type": "boolean" }, "max_amount": { "description": "Optional maximum allowed amount (positive decimal) per expense in this category, used as a spending ceiling. Null means no limit.", "minimum": 0, "type": "string" }, "document_template_path": { "description": "Optional uploaded document template file (stored on the documents disk) used when generating paperwork for expenses in this category. Provide an absolute file URL only if you have one.", "type": "string" }, "document_template_path_name": { "description": "Original filename of the uploaded document template, if any.", "type": "string" }, "color": { "description": "Display color used for this category in the UI, e.g. a hex code or named color.", "type": "string" } }, "required": [ "name", "requires_receipt" ] }, "example": { "name": "Client Entertainment", "description": "Business meals and client entertainment expenses", "requires_receipt": true, "max_amount": "300.00", "color": "#149ea3" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExpenseCategoryResource" } } }, "example": { "data": { "id": "01kwt1xnadqb3fv3bex9bx31dy", "type": "expense_categories", "attributes": { "id": "01kwt1xnadqb3fv3bex9bx31dy", "name": "Client Entertainment", "description": "Business meals and client entertainment expenses", "requires_receipt": true, "max_amount": "300.00", "color": "#149ea3" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/expense-categories/{id}": { "get": { "operationId": "expense-categories-show", "summary": "Retrieve an expense category", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense category ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Expense category detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExpenseCategoryResource" } } }, "example": { "data": { "id": "01kwt1xnadqb3fv3bex9bx31dy", "type": "expense_categories", "attributes": { "id": "01kwt1xnadqb3fv3bex9bx31dy", "name": "Client Entertainment", "description": "Business meals and client entertainment expenses", "requires_receipt": true, "max_amount": "300.00", "color": "#149ea3" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "expense-categories-update", "summary": "Update an expense category", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense category ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Unique human-readable name of the category, e.g. \"Transport\" or \"Accommodation\". Required, up to 255 characters.", "type": "string" }, "description": { "description": "Optional free-text explanation of what expenses belong in this category.", "type": "string" }, "requires_receipt": { "description": "Boolean flag: when true, expenses in this category must have a receipt file attached. Defaults to true.", "type": "boolean" }, "max_amount": { "description": "Optional maximum allowed amount (positive decimal) per expense in this category, used as a spending ceiling. Null means no limit.", "minimum": 0, "type": "string" }, "document_template_path": { "description": "Optional uploaded document template file (stored on the documents disk) used when generating paperwork for expenses in this category. Provide an absolute file URL only if you have one.", "type": "string" }, "document_template_path_name": { "description": "Original filename of the uploaded document template, if any.", "type": "string" }, "color": { "description": "Display color used for this category in the UI, e.g. a hex code or named color.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExpenseCategoryResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "expense-categories-destroy", "summary": "Delete an expense category", "tags": [ "Expenses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The expense category ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/jobs": { "get": { "operationId": "jobs-index", "summary": "List jobs", "description": "Manages job postings (the \"jobs\" table): the open roles a tenant is hiring for in the Growee hiring/recruitment module. Each job carries a title, HTML description, status (active/inactive), optional salary range and location, contract type, remote flag, and a hiring manager, and links to positions, seniority levels, and projects. Jobs own the candidates that apply to them (see the candidates domain) and can be published to a public careers page (slug, public_url, public_configuration) via the publish action or shared privately via a tokenized link (share action). Use this repository to list, search, filter, create, and edit vacancies; use the HiringPricingRepository for the per-job and per-candidate quota pricing that governs how many jobs and candidates a tenant may create.", "tags": [ "Hiring" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of jobs per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- positions (fields: department_id, description, id, is_used, name)\n- levels (fields: created_at, description, id, is_used, name)\n- projects (fields: archived, billing_model, budget, budget_type, client_id, client_name, created_at, currency, description, ends_at, id, is_used, logo_path, name, revenue_share_percent, starts_at, website)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- editor (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- hiringManager (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=positions,levels (include all fields)\n- include=positions[department_id,description] (selective fields with comma syntax)\n- include=positions[department_id|description] (selective fields with pipe syntax)\n- include=positions.posts (nested relationship - all fields)\n- include=positions[name].posts[title] (nested with field selection at each level)\n- include=positions[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=positions.posts[title],positions.comments[body] (multiple nested from same parent)\n- include=positions[name],levels[id] (multiple relationships with field selection)\n- include=positions[email|name].posts[title],levels[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter jobs by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the jobs. Available options: title, status, started_at, ending_at, location, salary_min, salary_max, is_remote, created_at, updated_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "is_remote", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a boolean match for is_remote (e.g., is_remote=true or is_remote=false). It accepts negation by prefixing the column with a hyphen (e.g., -is_remote=true or -is_remote=false). Accepted values are boolean.", "schema": { "type": "boolean" } }, { "name": "contract_type", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a exact match for contract_type (e.g., contract_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -contract_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "location", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a exact match for location (e.g., location=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -location=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "salary_min", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a range match for salary_min (e.g., salary_min=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -salary_min=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "salary_max", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a range match for salary_max (e.g., salary_max=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -salary_max=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "hiring_manager_id", "in": "query", "required": false, "description": "Filter jobs resource. Description: This is a exact match for hiring_manager_id (e.g., hiring_manager_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -hiring_manager_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 3, "path": "https://demo.growee.test/api/restify/jobs", "per_page": 1, "to": 1, "total": 3 }, "links": { "first": "https://demo.growee.test/api/restify/jobs?page=1", "next": "https://demo.growee.test/api/restify/jobs?page=2", "path": "https://demo.growee.test/api/restify/jobs", "prev": null, "filters": "/api/restify/jobs/filters" }, "data": [ { "id": "01kwt1y3dgbhbqs85qk5rxpwez", "type": "jobs", "attributes": { "id": "01kwt1y3dgbhbqs85qk5rxpwez", "title": "Project Manager", "content": "

Role filled — thank you to everyone who applied. We keep strong profiles in our talent pool.

", "status": "inactive", "started_at": "2026-03-05T00:00:00.000000Z", "ending_at": "2026-06-05T00:00:00.000000Z", "location": "Cluj-Napoca / Hybrid", "salary_min": "3500.00", "salary_max": "5000.00", "salary_currency": "EUR", "salary_type": "monthly", "contract_type": "employment_contract", "is_remote": false, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "position_ids": [], "level_ids": [], "project_ids": [], "candidates_count": 2, "created_at": "2026-07-05T21:11:18.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "jobs-store", "summary": "Create a job", "tags": [ "Hiring" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "The job title as shown to applicants (e.g. \"Senior Laravel Developer\"). Required, plain text up to 255 characters. Creating a job consumes one job-posting quota slot.", "maxLength": 255, "type": "string" }, "content": { "description": "The full job description body as HTML (responsibilities, requirements, benefits). Required; HTML is sanitized on save. Use the generate-description action to draft this from the job attributes.", "type": "string" }, "status": { "description": "The lifecycle status of the job. Allowed values: \"active\" (open and accepting candidates) or \"inactive\" (paused/closed). Defaults to active.", "enum": [ "active", "inactive" ], "type": "string" }, "started_at": { "description": "The date the job opening starts, as a date string (YYYY-MM-DD). Optional; used for scheduling and reporting, not for publication.", "type": "string" }, "ending_at": { "description": "The date the job opening closes, as a date string (YYYY-MM-DD). Optional; must be on or after started_at.", "type": "string" }, "location": { "description": "The free-text location of the role (e.g. \"Cluj-Napoca, Romania\"). Optional, up to 255 characters. See the unique-locations getter for values already in use.", "maxLength": 255, "type": "string" }, "salary_min": { "description": "The lower bound of the offered salary range, as a non-negative decimal amount in the currency given by salary_currency. Optional.", "minimum": 0, "type": "string" }, "salary_max": { "description": "The upper bound of the offered salary range, as a non-negative decimal amount in the currency given by salary_currency. Optional; must be greater than or equal to salary_min.", "minimum": 0, "type": "string" }, "salary_currency": { "description": "The ISO 4217 currency code for salary_min and salary_max (e.g. \"EUR\", \"USD\", \"RON\"). Optional, 3-letter code.", "maxLength": 3, "type": "string" }, "salary_type": { "description": "The period the salary range refers to. Allowed values: \"hourly\" or \"monthly\". Optional.", "enum": [ "hourly", "monthly" ], "type": "string" }, "contract_type": { "description": "The employment arrangement offered. Allowed values: \"employment_contract\" (standard employment with full labor rights and paid holidays), \"internship\" (temporary training role, often fixed duration), \"b2b_unpaid_holidays\" (B2B contractor agreement without paid holidays), \"b2b_paid_holidays\" (B2B contractor agreement with paid holidays). Optional.", "enum": [ "employment_contract", "internship", "b2b_unpaid_holidays", "b2b_paid_holidays" ], "type": "string" }, "is_remote": { "description": "Boolean flag: true if the role can be performed fully remotely, false if it is on-site or hybrid tied to the location.", "type": "boolean" }, "hiring_manager_id": { "description": "The ULID foreign key of the Employee (see EmployeeRepository) responsible for this hiring process. Optional; must reference an existing employee.", "type": "string" } }, "required": [ "title", "content" ] }, "example": { "title": "Project Manager", "content": "

Role filled — thank you to everyone who applied. We keep strong profiles in our talent pool.

", "status": "inactive", "started_at": "2026-03-05T00:00:00.000000Z", "ending_at": "2026-06-05T00:00:00.000000Z", "location": "Cluj-Napoca / Hybrid", "salary_min": "3500.00", "salary_max": "5000.00", "salary_currency": "EUR", "salary_type": "monthly", "contract_type": "employment_contract", "is_remote": false, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobResource" } } }, "example": { "data": { "id": "01kwt1y3dgbhbqs85qk5rxpwez", "type": "jobs", "attributes": { "id": "01kwt1y3dgbhbqs85qk5rxpwez", "title": "Project Manager", "content": "

Role filled — thank you to everyone who applied. We keep strong profiles in our talent pool.

", "status": "inactive", "started_at": "2026-03-05T00:00:00.000000Z", "ending_at": "2026-06-05T00:00:00.000000Z", "location": "Cluj-Napoca / Hybrid", "salary_min": "3500.00", "salary_max": "5000.00", "salary_currency": "EUR", "salary_type": "monthly", "contract_type": "employment_contract", "is_remote": false, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "position_ids": [], "level_ids": [], "project_ids": [], "candidates_count": 2, "created_at": "2026-07-05T21:11:18.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/jobs/{id}": { "get": { "operationId": "jobs-show", "summary": "Retrieve a job", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobResource" } } }, "example": { "data": { "id": "01kwt1y3dgbhbqs85qk5rxpwez", "type": "jobs", "attributes": { "id": "01kwt1y3dgbhbqs85qk5rxpwez", "title": "Project Manager", "content": "

Role filled — thank you to everyone who applied. We keep strong profiles in our talent pool.

", "status": "inactive", "started_at": "2026-03-05T00:00:00.000000Z", "ending_at": "2026-06-05T00:00:00.000000Z", "location": "Cluj-Napoca / Hybrid", "salary_min": "3500.00", "salary_max": "5000.00", "salary_currency": "EUR", "salary_type": "monthly", "contract_type": "employment_contract", "is_remote": false, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "position_ids": [], "level_ids": [], "project_ids": [], "candidates_count": 2, "created_at": "2026-07-05T21:11:18.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "jobs-update", "summary": "Update a job", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "The job title as shown to applicants (e.g. \"Senior Laravel Developer\"). Required, plain text up to 255 characters. Creating a job consumes one job-posting quota slot.", "maxLength": 255, "type": "string" }, "content": { "description": "The full job description body as HTML (responsibilities, requirements, benefits). Required; HTML is sanitized on save. Use the generate-description action to draft this from the job attributes.", "type": "string" }, "status": { "description": "The lifecycle status of the job. Allowed values: \"active\" (open and accepting candidates) or \"inactive\" (paused/closed). Defaults to active.", "enum": [ "active", "inactive" ], "type": "string" }, "started_at": { "description": "The date the job opening starts, as a date string (YYYY-MM-DD). Optional; used for scheduling and reporting, not for publication.", "type": "string" }, "ending_at": { "description": "The date the job opening closes, as a date string (YYYY-MM-DD). Optional; must be on or after started_at.", "type": "string" }, "location": { "description": "The free-text location of the role (e.g. \"Cluj-Napoca, Romania\"). Optional, up to 255 characters. See the unique-locations getter for values already in use.", "maxLength": 255, "type": "string" }, "salary_min": { "description": "The lower bound of the offered salary range, as a non-negative decimal amount in the currency given by salary_currency. Optional.", "minimum": 0, "type": "string" }, "salary_max": { "description": "The upper bound of the offered salary range, as a non-negative decimal amount in the currency given by salary_currency. Optional; must be greater than or equal to salary_min.", "minimum": 0, "type": "string" }, "salary_currency": { "description": "The ISO 4217 currency code for salary_min and salary_max (e.g. \"EUR\", \"USD\", \"RON\"). Optional, 3-letter code.", "maxLength": 3, "type": "string" }, "salary_type": { "description": "The period the salary range refers to. Allowed values: \"hourly\" or \"monthly\". Optional.", "enum": [ "hourly", "monthly" ], "type": "string" }, "contract_type": { "description": "The employment arrangement offered. Allowed values: \"employment_contract\" (standard employment with full labor rights and paid holidays), \"internship\" (temporary training role, often fixed duration), \"b2b_unpaid_holidays\" (B2B contractor agreement without paid holidays), \"b2b_paid_holidays\" (B2B contractor agreement with paid holidays). Optional.", "enum": [ "employment_contract", "internship", "b2b_unpaid_holidays", "b2b_paid_holidays" ], "type": "string" }, "is_remote": { "description": "Boolean flag: true if the role can be performed fully remotely, false if it is on-site or hybrid tied to the location.", "type": "boolean" }, "hiring_manager_id": { "description": "The ULID foreign key of the Employee (see EmployeeRepository) responsible for this hiring process. Optional; must reference an existing employee.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "jobs-destroy", "summary": "Delete a job", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/jobs/getters/unique-locations": { "get": { "operationId": "jobs-getter-unique-locations", "summary": "Unique locations", "description": "Returns the distinct, non-empty job locations already used across the tenant's jobs, sorted alphabetically, each as a {label, value} option. Takes no parameters. Use this to populate a location filter or to suggest existing locations when creating a job.", "tags": [ "Hiring" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/jobs/{id}/actions": { "post": { "operationId": "jobs-record-actions", "summary": "Actions: generate-description, score-candidate, share, ...", "description": "Perform an action on a single job. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`generate-description`** - Generates an AI-written HTML job description from the supplied job attributes, without persisting anything. Payload keys: \"title\" (required), and optional \"location\", \"contract_type\", \"is_remote\", \"salary_min\", \"salary_max\", \"salary_currency\", \"salary_type\". Returns the generated \"content\" HTML for the caller to review and save into a job. Use this to draft a description before creating or updating a job.\n- **`score-candidate`** - Triggers AI scoring of a single candidate against this job, evaluating how well the candidate fits the role. Side effect: dispatches a scoring job (synchronously when possible, otherwise queued) that computes and stores the candidate's match scores asynchronously. Required payload: \"candidate_id\" (the ULID of an existing candidate). Returns immediately with a queued acknowledgement; scores become available shortly after. Use this when the user asks to score or rank a candidate for a specific job.\n- **`share`** - Creates a private, tokenized shareable link for a job without publishing it to the public careers page. Side effect: creates a shareable record with a unique token and its display configuration. Accepts an optional \"configuration\" object with booleans \"show_salary\", \"show_projects\", and \"show_positions_levels\". Returns the token and configuration. Use this to share a vacancy privately (e.g. with a specific candidate or partner) rather than making it fully public.\n- **`publish`** - Publishes a job to the public careers page, making it visible to external applicants. Side effects: generates a URL slug (if missing), sets published_at, and stores the display configuration. Accepts an optional \"configuration\" object with booleans \"show_salary\", \"show_projects\", and \"show_positions_levels\" controlling what the public listing reveals. Returns the slug, published_at, public_url, and configuration. Call this when the user wants to make a vacancy live/public.\n- **`unpublish`** - Unpublishes a job, removing it from the public careers page so external applicants can no longer see it. Side effect: clears published_at (the job otherwise stays intact and editable). Takes no payload. Returns the slug and a null published_at. Call this when the user wants to take a live vacancy offline.", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "generate-description", "score-candidate", "share", "publish", "unpublish" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "generate-description", "type": "object", "properties": {} }, { "title": "score-candidate", "type": "object", "properties": { "candidate_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "share", "type": "object", "properties": {} }, { "title": "publish", "type": "object", "properties": {} }, { "title": "unpublish", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/candidates": { "get": { "operationId": "candidates-index", "summary": "List candidates", "description": "Candidates are job applicants tracked in the tenant hiring/recruitment (ATS) module, stored in the candidates table. Each candidate belongs to a Job vacancy (job_id), sits in a CandidateStage of the recruitment pipeline (stage_id), and can be assigned to an Employee acting as hiring manager. Records hold contact info, resume/CV file, structured education/work history/skills/languages, AI-generated fit scores, tags and notes. Use this repository to list, search (by name/email/phone/location), filter (by stage, source, job, hiring manager, archived state) and sort candidates. Related but distinct: CandidateStageRepository defines the pipeline columns candidates move through, and a candidate becomes an Employee once hired.", "tags": [ "Hiring" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of candidates per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- job (fields: candidates_count, content, contract_type, created_at, ending_at, hiring_manager_id, id, is_remote, level_ids, location, position_ids, project_ids, public_configuration, public_url, published_at, salary_currency, salary_max, salary_min, salary_type, slug, started_at, status, title, updated_at)\n- hiringManager (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- editor (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- stage (fields: color, created_at, description, id, name, position, updated_at)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=job,hiringManager (include all fields)\n- include=job[candidates_count,content] (selective fields with comma syntax)\n- include=job[candidates_count|content] (selective fields with pipe syntax)\n- include=job.posts (nested relationship - all fields)\n- include=job[name].posts[title] (nested with field selection at each level)\n- include=job[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=job.posts[title],job.comments[body] (multiple nested from same parent)\n- include=job[name],hiringManager[id] (multiple relationships with field selection)\n- include=job[email|name].posts[title],hiringManager[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter candidates by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the candidates. Available options: name, email, created_at, updated_at, score_overall (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "stage_id", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a exact match for stage_id (e.g., stage_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -stage_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a exact match for source (e.g., source=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -source=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "hiring_manager_id", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a exact match for hiring_manager_id (e.g., hiring_manager_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -hiring_manager_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a exact match for job_id (e.g., job_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -job_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a range match for updated_at (e.g., updated_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -updated_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "applied_via_token", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a exact match for applied_via_token (e.g., applied_via_token=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -applied_via_token=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a exact match for archived (e.g., archived=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -archived=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "archived_at", "in": "query", "required": false, "description": "Filter candidates resource. Description: This is a range match for archived_at (e.g., archived_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -archived_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 18, "path": "https://demo.growee.test/api/restify/candidates", "per_page": 1, "to": 1, "total": 18 }, "links": { "first": "https://demo.growee.test/api/restify/candidates?page=1", "next": "https://demo.growee.test/api/restify/candidates?page=2", "path": "https://demo.growee.test/api/restify/candidates", "prev": null, "filters": "/api/restify/candidates/filters" }, "data": [ { "id": "01kwt1y3ecw4j6vkq192kr4mvs", "type": "candidates", "attributes": { "id": "01kwt1y3ecw4j6vkq192kr4mvs", "name": "Oscar Newman", "email": "oscar.newman@candidates.example.com", "phone": "+40 730 802 332", "linkedin_url": "https://linkedin.com/in/oscar-newman", "location": "Remote, Romania", "expected_salary_amount": "6200.00", "expected_salary_currency": "EUR", "availability_date": "2026-09-12T00:00:00.000000Z", "stage_id": 14, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "job_id": "01kwt1y3dgbhbqs85qk5rxpwez", "source": "linkedin", "score_overall": 4, "score_education": 9, "score_skills": 10, "score_role_fit": 5, "education": [ { "field": "Engineering", "degree": "Bachelor of Science", "end_date": "2019-06-30", "start_date": "2015-09-01", "institution": "Dach, Heidenreich and Hintz University" } ], "work_history": [ { "company": "Nikolaus-Cremin", "end_date": "2022-12-31", "position": "Environmental Science Teacher", "start_date": "2019-07-01", "description": "Consequatur ex natus necessitatibus qui eveniet aut aut optio. Sed ad perspiciatis nesciunt et ullam. Magnam aut temporibus explicabo molestias magnam except..." } ], "skills": [ "PHP", "Laravel", "MySQL", "Vue.js", "Docker" ], "languages": [ { "language": "English", "proficiency": "fluent" }, { "language": "Spanish", "proficiency": "intermediate" } ], "notes": "Process closed.", "created_by": "01kwt1xnkj88cyqk2882392sa3", "created_at": "2026-04-11T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "candidates-store", "summary": "Create a candidate", "tags": [ "Hiring" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name of the candidate/applicant. Required when creating.", "maxLength": 255, "type": "string" }, "email": { "description": "Primary email address of the candidate; must be a valid email. Required when creating and used to detect duplicate people when hiring.", "maxLength": 255, "type": "string" }, "phone": { "description": "Candidate phone number as free-form text (any format), optional.", "maxLength": 50, "type": "string" }, "linkedin_url": { "description": "URL of the candidate LinkedIn profile (e.g. https://linkedin.com/in/...), optional.", "maxLength": 500, "type": "string" }, "portfolio_url": { "description": "URL to the candidate personal website, portfolio or GitHub, optional.", "maxLength": 500, "type": "string" }, "location": { "description": "Candidate location as free-form text, e.g. city and country. Optional.", "maxLength": 255, "type": "string" }, "expected_salary_amount": { "description": "Salary the candidate expects, as a non-negative decimal amount (2 decimal places). Interpret the currency from expected_salary_currency. Optional.", "minimum": 0, "type": "string" }, "expected_salary_currency": { "description": "ISO 4217 currency code (e.g. EUR, USD, RON) for expected_salary_amount. Optional.", "maxLength": 3, "type": "string" }, "availability_date": { "description": "Date (YYYY-MM-DD) from which the candidate is available to start. Optional.", "type": "string" }, "interview_date": { "description": "Scheduled interview date (YYYY-MM-DD) for the candidate. Optional.", "type": "string" }, "stage_id": { "description": "ULID foreign key referencing a CandidateStage (candidate-stages repository) that positions this candidate in the hiring pipeline. Optional.", "type": "integer" }, "hiring_manager_id": { "description": "ULID foreign key referencing the Employee (employees repository) responsible for this candidate as hiring manager. Optional.", "type": "string" }, "job_id": { "description": "ULID foreign key referencing the Job vacancy (jobs repository) this candidate applied to or is being considered for. Optional.", "type": "string" }, "source": { "description": "How the candidate entered the pipeline. One of: manual, pdf_upload, linkedin, referral, job_board, website, other. Defaults to manual.", "enum": [ "manual", "pdf_upload", "linkedin", "referral", "job_board", "website", "other" ], "type": "string" }, "score_overall": { "description": "Overall AI-generated fit score for the candidate, numeric between 0 and 10 (higher is better). Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_education": { "description": "AI-generated score for the candidate education, numeric between 0 and 10. Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_skills": { "description": "AI-generated score for the candidate skills, numeric between 0 and 10. Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_role_fit": { "description": "AI-generated score for how well the candidate fits the target role, numeric between 0 and 10. Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_reasoning": { "description": "Free-text explanation from the AI justifying the scores above. Optional.", "type": "string" }, "education": { "description": "Education history as a JSON array of entries, each typically with from, till, institution and description keys. Optional.", "type": "array" }, "work_history": { "description": "Work experience as a JSON array of entries, each typically with from, till, company_name, position and description keys. Optional.", "type": "array" }, "skills": { "description": "Candidate skills as a JSON array; entries may be plain skill strings or objects with category and skills keys. Optional.", "type": "array" }, "languages": { "description": "Spoken languages as a JSON array; entries may be language name strings or objects with language/name and level/proficiency keys. Optional.", "type": "array" }, "tags": { "description": "Free-form labels for organizing/filtering candidates, as a JSON array of strings. Optional.", "type": "array" }, "notes": { "description": "Free-text internal notes about the candidate. Optional.", "type": "string" }, "cv_filename": { "description": "Original filename of the uploaded CV. You can keep it empty or provide an intuitive name if there is a file.", "type": "string" } }, "required": [ "name", "email" ] }, "example": { "name": "Oscar Newman", "email": "oscar.newman@candidates.example.com", "phone": "+40 730 802 332", "linkedin_url": "https://linkedin.com/in/oscar-newman", "location": "Remote, Romania", "expected_salary_amount": "6200.00", "expected_salary_currency": "EUR", "availability_date": "2026-09-12T00:00:00.000000Z", "stage_id": 14, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "job_id": "01kwt1y3dgbhbqs85qk5rxpwez", "source": "linkedin", "score_overall": 4, "score_education": 9, "score_skills": 10, "score_role_fit": 5, "education": [ { "field": "Engineering", "degree": "Bachelor of Science", "end_date": "2019-06-30", "start_date": "2015-09-01", "institution": "Dach, Heidenreich and Hintz University" } ], "work_history": [ { "company": "Nikolaus-Cremin", "end_date": "2022-12-31", "position": "Environmental Science Teacher", "start_date": "2019-07-01", "description": "Consequatur ex natus necessitatibus qui eveniet aut aut optio. Sed ad perspiciatis nesciunt et ullam. Magnam aut temporibus explicabo molestias magnam except..." } ], "skills": [ "PHP", "Laravel", "MySQL", "Vue.js", "Docker" ], "languages": [ { "language": "English", "proficiency": "fluent" }, { "language": "Spanish", "proficiency": "intermediate" } ], "notes": "Process closed." } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CandidateResource" } } }, "example": { "data": { "id": "01kwt1y3ecw4j6vkq192kr4mvs", "type": "candidates", "attributes": { "id": "01kwt1y3ecw4j6vkq192kr4mvs", "name": "Oscar Newman", "email": "oscar.newman@candidates.example.com", "phone": "+40 730 802 332", "linkedin_url": "https://linkedin.com/in/oscar-newman", "location": "Remote, Romania", "expected_salary_amount": "6200.00", "expected_salary_currency": "EUR", "availability_date": "2026-09-12T00:00:00.000000Z", "stage_id": 14, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "job_id": "01kwt1y3dgbhbqs85qk5rxpwez", "source": "linkedin", "score_overall": 4, "score_education": 9, "score_skills": 10, "score_role_fit": 5, "education": [ { "field": "Engineering", "degree": "Bachelor of Science", "end_date": "2019-06-30", "start_date": "2015-09-01", "institution": "Dach, Heidenreich and Hintz University" } ], "work_history": [ { "company": "Nikolaus-Cremin", "end_date": "2022-12-31", "position": "Environmental Science Teacher", "start_date": "2019-07-01", "description": "Consequatur ex natus necessitatibus qui eveniet aut aut optio. Sed ad perspiciatis nesciunt et ullam. Magnam aut temporibus explicabo molestias magnam except..." } ], "skills": [ "PHP", "Laravel", "MySQL", "Vue.js", "Docker" ], "languages": [ { "language": "English", "proficiency": "fluent" }, { "language": "Spanish", "proficiency": "intermediate" } ], "notes": "Process closed.", "created_by": "01kwt1xnkj88cyqk2882392sa3", "created_at": "2026-04-11T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/candidates/{id}": { "get": { "operationId": "candidates-show", "summary": "Retrieve a candidate", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Candidate detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CandidateResource" } } }, "example": { "data": { "id": "01kwt1y3ecw4j6vkq192kr4mvs", "type": "candidates", "attributes": { "id": "01kwt1y3ecw4j6vkq192kr4mvs", "name": "Oscar Newman", "email": "oscar.newman@candidates.example.com", "phone": "+40 730 802 332", "linkedin_url": "https://linkedin.com/in/oscar-newman", "location": "Remote, Romania", "expected_salary_amount": "6200.00", "expected_salary_currency": "EUR", "availability_date": "2026-09-12T00:00:00.000000Z", "stage_id": 14, "hiring_manager_id": "01kwt1xnm6ykcmhbar2x1haa7t", "job_id": "01kwt1y3dgbhbqs85qk5rxpwez", "source": "linkedin", "score_overall": 4, "score_education": 9, "score_skills": 10, "score_role_fit": 5, "education": [ { "field": "Engineering", "degree": "Bachelor of Science", "end_date": "2019-06-30", "start_date": "2015-09-01", "institution": "Dach, Heidenreich and Hintz University" } ], "work_history": [ { "company": "Nikolaus-Cremin", "end_date": "2022-12-31", "position": "Environmental Science Teacher", "start_date": "2019-07-01", "description": "Consequatur ex natus necessitatibus qui eveniet aut aut optio. Sed ad perspiciatis nesciunt et ullam. Magnam aut temporibus explicabo molestias magnam except..." } ], "skills": [ "PHP", "Laravel", "MySQL", "Vue.js", "Docker" ], "languages": [ { "language": "English", "proficiency": "fluent" }, { "language": "Spanish", "proficiency": "intermediate" } ], "notes": "Process closed.", "created_by": "01kwt1xnkj88cyqk2882392sa3", "created_at": "2026-04-11T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "candidates-update", "summary": "Update a candidate", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name of the candidate/applicant. Required when creating.", "maxLength": 255, "type": "string" }, "email": { "description": "Primary email address of the candidate; must be a valid email. Required when creating and used to detect duplicate people when hiring.", "type": "string" }, "phone": { "description": "Candidate phone number as free-form text (any format), optional.", "maxLength": 50, "type": "string" }, "linkedin_url": { "description": "URL of the candidate LinkedIn profile (e.g. https://linkedin.com/in/...), optional.", "maxLength": 500, "type": "string" }, "portfolio_url": { "description": "URL to the candidate personal website, portfolio or GitHub, optional.", "maxLength": 500, "type": "string" }, "location": { "description": "Candidate location as free-form text, e.g. city and country. Optional.", "maxLength": 255, "type": "string" }, "expected_salary_amount": { "description": "Salary the candidate expects, as a non-negative decimal amount (2 decimal places). Interpret the currency from expected_salary_currency. Optional.", "minimum": 0, "type": "string" }, "expected_salary_currency": { "description": "ISO 4217 currency code (e.g. EUR, USD, RON) for expected_salary_amount. Optional.", "maxLength": 3, "type": "string" }, "availability_date": { "description": "Date (YYYY-MM-DD) from which the candidate is available to start. Optional.", "type": "string" }, "interview_date": { "description": "Scheduled interview date (YYYY-MM-DD) for the candidate. Optional.", "type": "string" }, "stage_id": { "description": "ULID foreign key referencing a CandidateStage (candidate-stages repository) that positions this candidate in the hiring pipeline. Optional.", "type": "integer" }, "hiring_manager_id": { "description": "ULID foreign key referencing the Employee (employees repository) responsible for this candidate as hiring manager. Optional.", "type": "string" }, "job_id": { "description": "ULID foreign key referencing the Job vacancy (jobs repository) this candidate applied to or is being considered for. Optional.", "type": "string" }, "source": { "description": "How the candidate entered the pipeline. One of: manual, pdf_upload, linkedin, referral, job_board, website, other. Defaults to manual.", "enum": [ "manual", "pdf_upload", "linkedin", "referral", "job_board", "website", "other" ], "type": "string" }, "score_overall": { "description": "Overall AI-generated fit score for the candidate, numeric between 0 and 10 (higher is better). Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_education": { "description": "AI-generated score for the candidate education, numeric between 0 and 10. Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_skills": { "description": "AI-generated score for the candidate skills, numeric between 0 and 10. Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_role_fit": { "description": "AI-generated score for how well the candidate fits the target role, numeric between 0 and 10. Optional.", "minimum": 0, "maximum": 10, "type": "number" }, "score_reasoning": { "description": "Free-text explanation from the AI justifying the scores above. Optional.", "type": "string" }, "education": { "description": "Education history as a JSON array of entries, each typically with from, till, institution and description keys. Optional.", "type": "array" }, "work_history": { "description": "Work experience as a JSON array of entries, each typically with from, till, company_name, position and description keys. Optional.", "type": "array" }, "skills": { "description": "Candidate skills as a JSON array; entries may be plain skill strings or objects with category and skills keys. Optional.", "type": "array" }, "languages": { "description": "Spoken languages as a JSON array; entries may be language name strings or objects with language/name and level/proficiency keys. Optional.", "type": "array" }, "tags": { "description": "Free-form labels for organizing/filtering candidates, as a JSON array of strings. Optional.", "type": "array" }, "notes": { "description": "Free-text internal notes about the candidate. Optional.", "type": "string" }, "cv_filename": { "description": "Original filename of the uploaded CV. You can keep it empty or provide an intuitive name if there is a file.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CandidateResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "candidates-destroy", "summary": "Delete a candidate", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/candidates/getters/sources": { "get": { "operationId": "candidates-getter-sources", "summary": "Sources", "description": "Returns the read-only list of candidate source options available in the hiring pipeline, each as a `{label, value}` pair where the value is the enum key and the label is the localized display text. The possible source values are: manual, pdf_upload, linkedin, referral, job_board, website, and other. This is a read-only lookup that changes no state and takes no payload. Call this to populate a source dropdown or to validate/interpret the `source` field of a candidate before creating or filtering candidate records.", "tags": [ "Hiring" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/candidates/{id}/actions": { "post": { "operationId": "candidates-record-actions", "summary": "Actions: import-from-linkedin, share, hire-candidate, ...", "description": "Perform an action on a single candidate. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`import-from-linkedin`** - Create a new candidate by scraping a public LinkedIn profile. This is a standalone action: pass linkedin_url (required, a valid https://linkedin.com/in/... URL) and optionally job_id (existing job ULID) to attach the new candidate to a vacancy. Side effects: calls the external Apify scraping service (can take up to ~5 minutes) and inserts a new candidate record populated with the scraped name, contact, work history and skills. Requires the manageHiring permission. Use this to add a sourced candidate directly from their LinkedIn URL instead of typing their details manually.\n- **`share`** - Generate a shareable public link for a candidate so an external stakeholder (e.g. a hiring manager without an account) can view their profile. Creates a shareable token and returns the token plus its configuration. Optional payload: a configuration object with custom_name (string label) and the booleans show_contact_info, show_cv and show_ai_scores that control which sections of the profile are visible via the link. Requires the manageHiring permission. Use this when you need to share a candidate outside the app.\n- **`hire-candidate`** - Convert a candidate into a hired Employee, creating the employee record (and linked user) from the candidate profile. Side effects: consumes one available plan seat and fails with 422 if none remain or if an employee already exists with the candidate email. Payload: start_date (required, YYYY-MM-DD, today or later); optional contract_type (a ContractTypeEnum value), position_id, manager_employee_id, level_id (existing IDs), and first_name/last_name overrides. Requires the manageHiring permission. Call this once a candidate has accepted an offer to onboard them as an employee.\n- **`archive-candidate`** - Archive a single candidate, hiding them from the active pipeline while preserving the record (soft, reversible). Runs against the candidate identified in the request; no payload is required. Requires the manageHiring permission. Use this to remove a candidate who is no longer being considered without deleting their data; call unarchive-candidate to restore them.\n- **`unarchive-candidate`** - Restore a previously archived candidate back into the active hiring pipeline. This is a standalone action: pass candidate_id (the ULID of the archived candidate) in the payload; the candidate is looked up including archived records and un-archived. Requires the manageHiring permission. Use this to reverse an archive-candidate call.", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "import-from-linkedin", "share", "hire-candidate", "archive-candidate", "unarchive-candidate" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "import-from-linkedin", "type": "object", "properties": { "linkedin_url": { "description": "This field is required", "type": "string" }, "job_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "share", "type": "object", "properties": {} }, { "title": "hire-candidate", "type": "object", "properties": { "start_date": { "description": "Must be after or equal to: today", "type": "string" }, "contract_type": { "description": "This field is optional", "type": "string" }, "position_id": { "description": "Must exist in the database", "type": "string" }, "manager_employee_id": { "description": "Must exist in the database", "type": "string" }, "level_id": { "description": "Must exist in the database", "type": "string" }, "first_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "last_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" } } }, { "title": "archive-candidate", "type": "object", "properties": {} }, { "title": "unarchive-candidate", "type": "object", "properties": { "candidate_id": { "description": "Must exist in the database", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/candidate-stages": { "get": { "operationId": "candidate-stages-index", "summary": "List candidate stages", "description": "Candidate stages are the ordered columns of the tenant hiring pipeline (like a Kanban board), stored in the candidate_stages table. Each stage has a name, a numeric position that determines its order, and optional color and description. Candidates reference a stage via their stage_id, and a stage cannot be deleted while candidates are still assigned to it. Use this repository to list, search by name and sort the pipeline stages; use the candidates repository to see or move the candidates within them.", "tags": [ "Hiring" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of candidate-stages per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter candidate-stages by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the candidate-stages. Available options: name, position, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Filter candidate-stages resource. Description: This is a exact match for name (e.g., name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateStageResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 17, "path": "https://demo.growee.test/api/restify/candidate-stages", "per_page": 1, "to": 1, "total": 17 }, "links": { "first": "https://demo.growee.test/api/restify/candidate-stages?page=1", "next": "https://demo.growee.test/api/restify/candidate-stages?page=2", "path": "https://demo.growee.test/api/restify/candidate-stages", "prev": null, "filters": "/api/restify/candidate-stages/filters" }, "data": [ { "id": "17", "type": "candidate_stages", "attributes": { "id": 17, "name": "On Hold", "position": 16, "created_at": "2025-12-28T10:00:04.000000Z", "updated_at": "2025-12-28T10:00:04.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "candidate-stages-store", "summary": "Create a candidate stage", "tags": [ "Hiring" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Display name of the pipeline stage (e.g. \"Applied\", \"Interview\", \"Offer\"). Required and must be unique within the tenant.", "maxLength": 100, "type": "string" }, "position": { "description": "Zero-based integer that orders this stage within the pipeline; lower values appear first. Required when creating.", "minimum": 0, "type": "integer" }, "color": { "description": "Optional color used to visually distinguish the stage in the UI, e.g. a hex code or color name.", "maxLength": 50, "type": "string" }, "description": { "description": "Optional free-text explanation of what this stage represents in the hiring process.", "type": "string" } }, "required": [ "name", "position" ] }, "example": { "name": "On Hold", "position": 16 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CandidateStageResource" } } }, "example": { "data": { "id": "17", "type": "candidate_stages", "attributes": { "id": 17, "name": "On Hold", "position": 16, "created_at": "2025-12-28T10:00:04.000000Z", "updated_at": "2025-12-28T10:00:04.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/candidate-stages/{id}": { "get": { "operationId": "candidate-stages-show", "summary": "Retrieve a candidate stage", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate stage ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Candidate stage detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CandidateStageResource" } } }, "example": { "data": { "id": "17", "type": "candidate_stages", "attributes": { "id": 17, "name": "On Hold", "position": 16, "created_at": "2025-12-28T10:00:04.000000Z", "updated_at": "2025-12-28T10:00:04.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "candidate-stages-update", "summary": "Update a candidate stage", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate stage ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Display name of the pipeline stage (e.g. \"Applied\", \"Interview\", \"Offer\"). Required and must be unique within the tenant.", "type": "string" }, "position": { "description": "Zero-based integer that orders this stage within the pipeline; lower values appear first. Required when creating.", "minimum": 0, "type": "integer" }, "color": { "description": "Optional color used to visually distinguish the stage in the UI, e.g. a hex code or color name.", "maxLength": 50, "type": "string" }, "description": { "description": "Optional free-text explanation of what this stage represents in the hiring process.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CandidateStageResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "candidate-stages-destroy", "summary": "Delete a candidate stage", "tags": [ "Hiring" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate stage ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/leads": { "get": { "operationId": "leads-index", "summary": "List leads", "description": "Sales leads: the core CRM pipeline record, one row per prospect (person or company) the tenant is trying to sell to, stored in the \"leads\" table and scoped to the current tenant. Each lead sits in exactly one pipeline stage (lead_stage_id), may belong to an outreach campaign, has an owning employee, and carries deal economics (expected_revenue, expected_close_date, probability) plus AI intelligence (fit_score, enrichment_summary) and a verification_status for its email. A won lead is converted into a Client (see convertedToClient / the convert-to-client action); its timeline of notes and system events lives in the sibling lead-activities repository, and the columns it can occupy are defined by lead-stages. Use this repository to list, search (name, email, phone, company_name), filter (by stage, campaign, source, owner, forecast bucket, has-email, archived), sort, and drive lead-level actions such as scoring, enrichment, message generation, email sending, and archiving.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of leads per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- campaign (fields: auto_personalize, auto_send_enabled, channel, created_at, created_by, deleted_at, description, ending_at, id, include_risky, is_demo, leads_count, name, owner_id, project_ids, started_at, status, tenant_id, updated_at, updated_by)\n- organization (fields: city, company_name, country, created_at, created_by, custom_fields, domain, id, industry, is_demo, lifecycle_stage, meta, owner_id, size, tenant_id, updated_at, updated_by, website)\n- stage (fields: campaign_id, color, created_at, description, id, name, position, updated_at)\n- owner (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- convertedToClient (fields: bank_account, bank_name, bank_swift, city, company_address, company_identifier, company_name, company_vat, country, created_at, custom_fields, description, domain, id, industry, is_used, lifecycle_stage, logo_path, meta, owner_id, prefered_currency, representative_name, representative_position, size, website)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- editor (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- activities (fields: body, causer_id, created_at, id, lead_id, meta, type, updated_at)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=campaign,organization (include all fields)\n- include=campaign[auto_personalize,auto_send_enabled] (selective fields with comma syntax)\n- include=campaign[auto_personalize|auto_send_enabled] (selective fields with pipe syntax)\n- include=campaign.posts (nested relationship - all fields)\n- include=campaign[name].posts[title] (nested with field selection at each level)\n- include=campaign[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=campaign.posts[title],campaign.comments[body] (multiple nested from same parent)\n- include=campaign[name],organization[id] (multiple relationships with field selection)\n- include=campaign[email|name].posts[title],organization[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter leads by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the leads. Available options: name, email, company_name, created_at, updated_at, last_contacted_at, fit_score (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "lead_stage_id", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for lead_stage_id (e.g., lead_stage_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -lead_stage_id=some_value). The filter type is string.", "schema": { "type": "integer" } }, { "name": "stage_name", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for stage_name (e.g., stage_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -stage_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for campaign_id (e.g., campaign_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -campaign_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for source (e.g., source=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -source=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for owner_id (e.g., owner_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -owner_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for industry (e.g., industry=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -industry=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "company_size", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for company_size (e.g., company_size=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -company_size=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "lost_reason", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for lost_reason (e.g., lost_reason=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -lost_reason=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a range match for updated_at (e.g., updated_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -updated_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for archived (e.g., archived=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -archived=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "archived_at", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a range match for archived_at (e.g., archived_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -archived_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "has_email", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for has_email (e.g., has_email=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -has_email=some_value). The filter type is string.", "schema": { "type": "boolean" } }, { "name": "forecast_bucket", "in": "query", "required": false, "description": "Filter leads resource. Description: This is a exact match for forecast_bucket (e.g., forecast_bucket=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -forecast_bucket=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 30, "path": "https://demo.growee.test/api/restify/leads", "per_page": 1, "to": 1, "total": 30 }, "links": { "first": "https://demo.growee.test/api/restify/leads?page=1", "next": "https://demo.growee.test/api/restify/leads?page=2", "path": "https://demo.growee.test/api/restify/leads", "prev": null, "filters": "/api/restify/leads/filters" }, "data": [ { "id": "01kwt1y3d1v31d6z3hee7atw2k", "type": "leads", "attributes": { "id": "01kwt1y3d1v31d6z3hee7atw2k", "name": "Aoife Murphy", "email": "aoife.murphy@dublin.example.com", "phone": "+40 710 918 146", "linkedin_url": "https://linkedin.com/in/aoife-murphy", "company_name": "Dublin Compliance Cloud", "company_website": "https://dublin.example.com", "industry": "Healthcare", "company_size": "51-200", "title": "CEO", "lead_stage_id": 7, "source": "linkedin", "owner_id": "01kwt1xp69e0rhapkzb65nmxe5", "last_contacted_at": "2026-06-25T21:11:03.000000Z", "lost_reason": "competitor", "overdue_follow_up": false, "due_today_follow_up": false, "tags": [ "vip" ], "created_at": "2025-11-27T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "leads-store", "summary": "Create a lead", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name of the lead (the prospect person), or the primary contact when the lead represents a company. Required, max 200 characters.", "maxLength": 200, "type": "string" }, "email": { "description": "Primary email address of the lead. Optional; when present it is used for outreach and for the deliverability verification_status lookup.", "maxLength": 200, "type": "string" }, "phone": { "description": "Contact phone number for the lead, free-form string (max 50 characters).", "maxLength": 50, "type": "string" }, "linkedin_url": { "description": "Full URL of the lead's LinkedIn profile (e.g. https://www.linkedin.com/in/…). Used to enrich or import the lead from LinkedIn.", "maxLength": 500, "type": "string" }, "location": { "description": "Free-text geographic location of the lead (city, region, or country).", "maxLength": 200, "type": "string" }, "company_name": { "description": "Name of the company the lead works for or represents.", "maxLength": 200, "type": "string" }, "company_website": { "description": "URL of the lead's company website.", "maxLength": 500, "type": "string" }, "industry": { "description": "Free-text industry or vertical of the lead's company (e.g. \"SaaS\", \"Manufacturing\").", "maxLength": 100, "type": "string" }, "company_size": { "description": "Headcount band of the lead's company. One of: \"1-10\", \"11-50\", \"51-200\", \"201-1000\", \"1000+\".", "enum": [ "1-10", "11-50", "51-200", "201-1000", "1000+" ], "type": "string" }, "title": { "description": "Job title of the lead at their company (e.g. \"Head of Sales\", \"CTO\").", "maxLength": 150, "type": "string" }, "lead_stage_id": { "description": "Integer foreign key to the pipeline stage (lead-stages repository / lead_stages table) this lead currently sits in. Required. The stage must belong to the lead's campaign, or be a tenant-default stage (campaign_id NULL) when the lead has no campaign.", "type": "integer" }, "campaign_id": { "description": "ULID foreign key to the outreach campaign (campaigns table) this lead is enrolled in. Null for leads not attached to any campaign.", "type": "string" }, "organization_id": { "description": "ULID foreign key to the linked organization, stored as a Client record (clients table). Associates the lead with an existing organization/company account. Null when unlinked.", "type": "string" }, "source": { "description": "Acquisition channel the lead came from. One of: \"manual\", \"linkedin\", \"cold_email\", \"referral\", \"event\", \"inbound\", \"hubspot\", \"other\". Defaults to \"manual\".", "enum": [ "manual", "linkedin", "cold_email", "referral", "event", "inbound", "other" ], "type": "string" }, "owner_id": { "description": "ULID foreign key to the employee (employees table) who owns / is responsible for this lead. Null when unassigned.", "type": "string" }, "last_contacted_at": { "description": "Timestamp (ISO 8601) of the most recent outbound contact with the lead. Drives the stale-lead detection.", "type": "string" }, "lost_reason": { "description": "Why the lead was lost / disqualified; setting this marks the lead as lost. One of: \"no_budget\", \"not_interested\", \"competitor\", \"bad_timing\", \"no_response\", \"other\". Null while the lead is still open.", "enum": [ "no_budget", "not_interested", "competitor", "bad_timing", "no_response", "other" ], "type": "string" }, "expected_revenue": { "description": "Expected deal value, in the tenant default currency.", "minimum": 0, "maximum": 9999999999, "type": "number" }, "expected_close_date": { "description": "Date (YYYY-MM-DD) the deal is expected to close. Used to bucket the lead in the revenue forecast.", "type": "string" }, "probability": { "description": "Manual win probability 0–100. Falls back to the AI fit_score when unset.", "minimum": 0, "maximum": 100, "type": "integer" }, "enriched_at": { "description": "Timestamp of the last enrichment run. External enrichers (Hermes, MCP callers) write this when pushing fresh research into the lead.", "type": "string" }, "enrichment_summary": { "description": "Free-text research summary about the lead and their company. Written by EnrichLeadJob or by external callers (Hermes, MCP) that already did the research themselves.", "maxLength": 10000, "type": "string" }, "tags": { "description": "Array of free-form string tags applied to the lead for segmentation and filtering.", "type": "array" }, "metadata": { "description": "Arbitrary caller-defined JSON object stored verbatim on the lead. Any keys and nested structures (strings, numbers, arrays, objects) are accepted.", "type": "object" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" }, "notes": { "description": "Legacy single free-text notes field on the lead. New threaded notes should be created as lead-activities of type \"note\"; this column is a fallback for leads with no timeline notes.", "type": "string" } }, "required": [ "name", "lead_stage_id" ] }, "example": { "name": "Aoife Murphy", "email": "aoife.murphy@dublin.example.com", "phone": "+40 710 918 146", "linkedin_url": "https://linkedin.com/in/aoife-murphy", "company_name": "Dublin Compliance Cloud", "company_website": "https://dublin.example.com", "industry": "Healthcare", "company_size": "51-200", "title": "CEO", "lead_stage_id": 7, "source": "linkedin", "owner_id": "01kwt1xp69e0rhapkzb65nmxe5", "last_contacted_at": "2026-06-25T21:11:03.000000Z", "lost_reason": "competitor", "tags": [ "vip" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadResource" } } }, "example": { "data": { "id": "01kwt1y3d1v31d6z3hee7atw2k", "type": "leads", "attributes": { "id": "01kwt1y3d1v31d6z3hee7atw2k", "name": "Aoife Murphy", "email": "aoife.murphy@dublin.example.com", "phone": "+40 710 918 146", "linkedin_url": "https://linkedin.com/in/aoife-murphy", "company_name": "Dublin Compliance Cloud", "company_website": "https://dublin.example.com", "industry": "Healthcare", "company_size": "51-200", "title": "CEO", "lead_stage_id": 7, "source": "linkedin", "owner_id": "01kwt1xp69e0rhapkzb65nmxe5", "last_contacted_at": "2026-06-25T21:11:03.000000Z", "lost_reason": "competitor", "overdue_follow_up": false, "due_today_follow_up": false, "tags": [ "vip" ], "created_at": "2025-11-27T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/leads/{id}": { "get": { "operationId": "leads-show", "summary": "Retrieve a lead", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lead detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadResource" } } }, "example": { "data": { "id": "01kwt1y3d1v31d6z3hee7atw2k", "type": "leads", "attributes": { "id": "01kwt1y3d1v31d6z3hee7atw2k", "name": "Aoife Murphy", "email": "aoife.murphy@dublin.example.com", "phone": "+40 710 918 146", "linkedin_url": "https://linkedin.com/in/aoife-murphy", "company_name": "Dublin Compliance Cloud", "company_website": "https://dublin.example.com", "industry": "Healthcare", "company_size": "51-200", "title": "CEO", "lead_stage_id": 7, "source": "linkedin", "owner_id": "01kwt1xp69e0rhapkzb65nmxe5", "last_contacted_at": "2026-06-25T21:11:03.000000Z", "lost_reason": "competitor", "overdue_follow_up": false, "due_today_follow_up": false, "tags": [ "vip" ], "created_at": "2025-11-27T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "leads-update", "summary": "Update a lead", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name of the lead (the prospect person), or the primary contact when the lead represents a company. Required, max 200 characters.", "maxLength": 200, "type": "string" }, "email": { "description": "Primary email address of the lead. Optional; when present it is used for outreach and for the deliverability verification_status lookup.", "maxLength": 200, "type": "string" }, "phone": { "description": "Contact phone number for the lead, free-form string (max 50 characters).", "maxLength": 50, "type": "string" }, "linkedin_url": { "description": "Full URL of the lead's LinkedIn profile (e.g. https://www.linkedin.com/in/…). Used to enrich or import the lead from LinkedIn.", "maxLength": 500, "type": "string" }, "location": { "description": "Free-text geographic location of the lead (city, region, or country).", "maxLength": 200, "type": "string" }, "company_name": { "description": "Name of the company the lead works for or represents.", "maxLength": 200, "type": "string" }, "company_website": { "description": "URL of the lead's company website.", "maxLength": 500, "type": "string" }, "industry": { "description": "Free-text industry or vertical of the lead's company (e.g. \"SaaS\", \"Manufacturing\").", "maxLength": 100, "type": "string" }, "company_size": { "description": "Headcount band of the lead's company. One of: \"1-10\", \"11-50\", \"51-200\", \"201-1000\", \"1000+\".", "enum": [ "1-10", "11-50", "51-200", "201-1000", "1000+" ], "type": "string" }, "title": { "description": "Job title of the lead at their company (e.g. \"Head of Sales\", \"CTO\").", "maxLength": 150, "type": "string" }, "lead_stage_id": { "description": "Integer foreign key to the pipeline stage (lead-stages repository / lead_stages table) this lead currently sits in. Required. The stage must belong to the lead's campaign, or be a tenant-default stage (campaign_id NULL) when the lead has no campaign.", "type": "integer" }, "campaign_id": { "description": "ULID foreign key to the outreach campaign (campaigns table) this lead is enrolled in. Null for leads not attached to any campaign.", "type": "string" }, "organization_id": { "description": "ULID foreign key to the linked organization, stored as a Client record (clients table). Associates the lead with an existing organization/company account. Null when unlinked.", "type": "string" }, "source": { "description": "Acquisition channel the lead came from. One of: \"manual\", \"linkedin\", \"cold_email\", \"referral\", \"event\", \"inbound\", \"hubspot\", \"other\". Defaults to \"manual\".", "enum": [ "manual", "linkedin", "cold_email", "referral", "event", "inbound", "other" ], "type": "string" }, "owner_id": { "description": "ULID foreign key to the employee (employees table) who owns / is responsible for this lead. Null when unassigned.", "type": "string" }, "last_contacted_at": { "description": "Timestamp (ISO 8601) of the most recent outbound contact with the lead. Drives the stale-lead detection.", "type": "string" }, "lost_reason": { "description": "Why the lead was lost / disqualified; setting this marks the lead as lost. One of: \"no_budget\", \"not_interested\", \"competitor\", \"bad_timing\", \"no_response\", \"other\". Null while the lead is still open.", "enum": [ "no_budget", "not_interested", "competitor", "bad_timing", "no_response", "other" ], "type": "string" }, "expected_revenue": { "description": "Expected deal value, in the tenant default currency.", "minimum": 0, "maximum": 9999999999, "type": "number" }, "expected_close_date": { "description": "Date (YYYY-MM-DD) the deal is expected to close. Used to bucket the lead in the revenue forecast.", "type": "string" }, "probability": { "description": "Manual win probability 0–100. Falls back to the AI fit_score when unset.", "minimum": 0, "maximum": 100, "type": "integer" }, "enriched_at": { "description": "Timestamp of the last enrichment run. External enrichers (Hermes, MCP callers) write this when pushing fresh research into the lead.", "type": "string" }, "enrichment_summary": { "description": "Free-text research summary about the lead and their company. Written by EnrichLeadJob or by external callers (Hermes, MCP) that already did the research themselves.", "maxLength": 10000, "type": "string" }, "tags": { "description": "Array of free-form string tags applied to the lead for segmentation and filtering.", "type": "array" }, "metadata": { "description": "Arbitrary caller-defined JSON object stored verbatim on the lead. Any keys and nested structures (strings, numbers, arrays, objects) are accepted.", "type": "object" }, "custom_fields": { "description": "Tenant-defined custom field values keyed by slug. Discover available slugs, types and options via the custom-field-definitions tools.", "type": "object" }, "notes": { "description": "Legacy single free-text notes field on the lead. New threaded notes should be created as lead-activities of type \"note\"; this column is a fallback for leads with no timeline notes.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "leads-destroy", "summary": "Delete a lead", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/leads/getters/download-leads-csv-template": { "get": { "operationId": "leads-getter-download-leads-csv-template", "summary": "Download leads csv template", "description": "Download the blank leads CSV template: a single header row with the exact column names the import-leads-csv action expects (name, email, phone, linkedin_url, title, company_name, company_website, industry, company_size, location, notes, expected_revenue, expected_close_date, probability). Takes no parameters and returns a text/csv attachment. Requires the manageCrm permission. Use this to obtain the correct file format before performing a CSV lead import.", "tags": [ "Leads" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-forecast": { "get": { "operationId": "leads-getter-lead-forecast", "summary": "Lead forecast", "description": "Revenue forecast aggregated into buckets for kanban column headers and the analytics dashboard. Query params: grouping (optional — \"stage\" default, or \"month\" by expected close date), campaign_id, owner_id, include_archived (optional filters). Returns per-bucket { count, expected_sum, prorated_sum }, where prorated_sum weights expected_revenue by each lead's probability (falling back to fit_score). On the global board (no campaign) stage buckets group by stage name; month grouping counts only open leads. Requires the manageCrm permission and the CRM analytics feature. Use this to total pipeline value per stage or per expected-close month.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-analytics-overview": { "get": { "operationId": "leads-getter-lead-analytics-overview", "summary": "Lead analytics overview", "description": "CRM dashboard KPI summary for a date range: new leads, won count and revenue, lost count, win rate, average days to close, a snapshot of open pipeline (count, expected and probability-prorated revenue), stale-lead count, and a monthly won-revenue trend series. Query params: start_date and end_date (required, ISO dates), plus optional campaign_id and owner_id filters. Won metrics key off converted_at; new/lost metrics off created_at. Requires the manageCrm permission and the CRM analytics feature. Use this for the top-level CRM performance overview.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-funnel": { "get": { "operationId": "leads-getter-lead-funnel", "summary": "Lead funnel", "description": "Stage-by-stage conversion funnel for leads over a date range, computed from \"stage_changed\" activities. Query params: start_date and end_date (required, ISO dates), plus optional campaign_id and owner_id filters. Returns one row per stage with: entered (distinct leads that moved into the stage), conversion_from_previous, and median_days_in_stage. Note it measures stage movement, not initial creation (first-stage volume lives in the overview's new_leads). Requires the manageCrm permission and the CRM analytics feature. Use this to see where leads progress or drop off across the pipeline.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-sources": { "get": { "operationId": "leads-getter-lead-sources", "summary": "Lead sources", "description": "Source-attribution breakdown of leads over a date range. Query params: start_date and end_date (required, ISO dates), plus optional campaign_id and owner_id filters. Returns one row per source (manual, linkedin, cold_email, referral, event, inbound, hubspot, other) with { source, leads (created in range), won (converted in range), won_revenue, win_rate = won/leads }. Requires the manageCrm permission and the CRM analytics feature. Use this to compare which acquisition channels produce and convert the most leads.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-lost-reasons": { "get": { "operationId": "leads-getter-lead-lost-reasons", "summary": "Lead lost reasons", "description": "Breakdown of lost leads by lost_reason over a date range (the analytics donut). Query params: start_date and end_date (required, ISO dates), plus optional campaign_id and owner_id filters. Counts leads whose lost_reason is set (created in range), returning { lost_reason, count } rows sorted by count desc — reasons are one of no_budget, not_interested, competitor, bad_timing, no_response, other. Requires the manageCrm permission and the CRM analytics feature. Use this to see why deals are being lost.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-stale": { "get": { "operationId": "leads-getter-lead-stale", "summary": "Lead stale", "description": "Paginated list of stale leads that need attention: open leads (not converted, no lost reason) with no recent contact and no pending follow-up, older than the tenant's configured stale threshold. Query params: campaign_id, owner_id (optional filters) and per_page (optional, 1–100, default 20). Each row returns { id, name, company_name, owner, last_contacted_at, created_at, stage }, oldest-contacted first. Requires the manageCrm permission and the CRM analytics feature. Use this to surface neglected leads a rep should follow up on.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-team-performance": { "get": { "operationId": "leads-getter-lead-team-performance", "summary": "Lead team performance", "description": "Per-owner CRM leaderboard over a date range. Query params: start_date and end_date (required, ISO dates), plus an optional campaign_id filter. Returns one row per lead owner (plus an unassigned row when ownerless leads exist), sorted by won revenue desc, with new_leads, won (count + revenue), lost, win_rate, open_pipeline (count + prorated revenue), avg_days_to_close, and interaction volume (outbound/inbound). Requires the manageCrm permission and the CRM analytics feature. Use this to compare sales performance across team members.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-activity-report": { "get": { "operationId": "leads-getter-lead-activity-report", "summary": "Lead activity report", "description": "CRM lead interaction volume over a time range, split into outbound vs inbound and bucketed by day, week, or month, plus a per-channel breakdown. Query params: start_date and end_date (required, ISO dates), granularity (optional — \"day\", \"week\", or \"month\"; auto-chosen from the range when omitted), owner_id and campaign_id (optional filters). Counts logged interactions whose subject is a lead. Requires the manageCrm permission and the CRM analytics feature. Use this to chart how much outreach and inbound activity leads received over time.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/getters/lead-analytics-export": { "get": { "operationId": "leads-getter-lead-analytics-export", "summary": "Lead analytics export", "description": "Download a CRM analytics report as a CSV file. Query params: report (required — one of \"sources\", \"lost_reasons\", \"team\", \"campaigns\", \"stale\"), start_date and end_date (required, ISO dates), plus optional owner_id and campaign_id filters. Each report mirrors the corresponding JSON getter (lead-sources, lead-lost-reasons, lead-team-performance, campaign performance, and stale leads) and returns a downloadable text/csv attachment. Requires the manageCrm permission and the CRM analytics feature. Use this to export analytics for spreadsheets or offline reporting.", "tags": [ "CRM Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/{id}/actions": { "post": { "operationId": "leads-record-actions", "summary": "Actions: import-from-linkedin, import-leads-csv, convert-to-client, ...", "description": "Perform an action on a single lead. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`import-from-linkedin`** - Import a new lead by scraping a public LinkedIn profile. Standalone action (no target lead). Payload: linkedin_url (required — a linkedin.com/in/… profile URL) and campaign_id (optional — enroll the imported lead into this campaign). Scrapes name, title, company, and location via the LinkedIn provider and creates a lead with source \"linkedin\", placed in the campaign's first stage (or the tenant-default first stage). If a lead with the same LinkedIn URL already exists it returns that lead with duplicate=true instead of scraping again. Enforces the plan lead cap and requires the manageCrm permission. Use this to add a specific prospect from their LinkedIn profile.\n- **`import-leads-csv`** - Bulk-import leads from an uploaded CSV file (synchronous). Standalone action. Payload: multipart form-data with \"file\" (required — a .csv whose header exactly matches the template: name, email, phone, linkedin_url, title, company_name, company_website, industry, company_size, location, notes, expected_revenue, expected_close_date, probability) and \"campaign_id\" (optional — assign every imported lead to this campaign). Max 200 data rows and 256 KB per file; rate-limited to 10 imports per hour per user. Returns a per-row created/skipped summary. Download the blank template via the download-leads-csv-template getter. Requires the manageCrm permission.\n- **`convert-to-client`** - Convert a won lead into a Client (an actual customer/organization account), marking the deal as closed-won. Creates a new Client from the lead and links it back via the lead's converted_to_client_id / converted_at. Optional payload keys: lead_role (the lead's role at the new client, string), contact_name, contact_email, contact_phone (details for the primary contact created on the client). Returns the created client. Requires the manageCrm permission. Use this once a lead has agreed to buy and should graduate out of the sales pipeline into the client base.\n- **`score-lead`** - AI-score a single lead against a campaign's ideal customer profile, writing the result into the lead's fit_score (0–100) and fit_reasoning. Payload: campaign_id (optional — the campaign whose ICP to score against; defaults to the lead's own campaign, and a campaign is required either way). Runs inline when possible so the response includes fit_score and fit_reasoning immediately (queued=false); on provider failure it falls back to an async job and returns HTTP 202 with queued=true. Consumes AI credits and requires the manageCrm permission and the CRM ai_actions feature; returns HTTP 402 when the AI balance is below minimum. Use this to prioritize a lead by how well it fits the campaign.\n- **`enrich-lead`** - Queue an AI enrichment job for a single lead: it researches the lead and their company and writes the result back into the lead's enrichment_summary and enriched_at. Asynchronous — returns immediately with the queued lead_id; results appear shortly after. Takes no payload beyond the target lead in the URL. Consumes AI credits and requires the manageCrm permission and the CRM ai_actions feature; returns HTTP 402 when the tenant's AI balance is below minimum. Use this to auto-populate research context before scoring or messaging a lead.\n- **`generate-message-for-lead`** - Generate (or regenerate) a per-lead outreach message for a specific campaign stage using AI, returning the final message ({subject, body}) ready to send. The prompt blends: caller-supplied research (highest priority — see \"context\" below), the campaign brief, the linked offering (projects + clients), the lead profile, and any prior stage briefs. The result is upserted into campaign_messages as a per-lead override (unique by campaign_id + lead_stage_id + lead_id), so calling the action again replaces the previous draft for the same lead/stage. Inputs (JSON body): resources (array of one lead id, required — Restify-standard, identifies the lead in the URL/{lead}), campaign_id (string, required — the campaign whose cadence the message is for; must belong to the lead tenant), lead_stage_id (integer, required — the stage in the cadence the message is for), context (string, optional — free-form markdown/plain-text enrichment from the caller, e.g. verified LinkedIn title, recent activity/posts, hiring signals, mutual connections, company signals, operator notes (pain hypothesis, recommended hook, case study hints), and style/touch-type hints (e.g. \"touch_type: inmail\", \"no em dashes\", \"avoid phrases: Hope this finds you well\"). The block is rendered as PRIMARY CONTEXT at the top of the user prompt and instructed to take precedence over the lead profile and offering blocks for personalization decisions when they conflict — treated as untrusted data, never as instructions to the model), length (object, optional — hard character limits enforced on the AI output via the Prism schema and the system prompt. Shape: { \"subject_max\": int?, \"body_max\": int? }. Use these to match the touch-type you are about to send, e.g. LinkedIn connection note → { \"body_max\": 280 }; LinkedIn InMail → { \"subject_max\": 50, \"body_max\": 1700 }; cold email typically does not need this. Omitting either key keeps the channel default for that field). Route: POST /api/restify/leads/{lead}/actions?action=generate-message-for-lead. Requires the manageCrm permission. Rate-limited per tenant (60/min, 1000/day); may return HTTP 429 if the workspace or the AI provider is throttled — in that case the response includes retry=true and the caller should back off. Response: { data: CampaignMessage (with campaign + lead relations loaded), message: { id, subject, body, campaign_id, lead_id, lead_stage_id } } — \"message\" is the convenience copy for callers (e.g. Hermes/Brian) that just want to send subject+body without re-reading the persisted record.\n- **`send-email`** - Send an email to a single lead (queued for delivery). Payload: subject (required, max 300 chars), body (required, max 20000 chars), and campaign_message_id (optional — the ULID of a campaign_messages record this send fulfills; its presence marks the send as campaign context rather than one-to-one). The lead must have an email address. Resolves the sending domain/identity, enforces per-tenant and per-user rate limits and daily send caps, then dispatches the send job (returns HTTP 202). Requires the manageCrm permission and the CRM email_sending feature. Use this to actually deliver an outreach or reply message to a lead — typically after generating it with the generate-message-for-lead action.\n- **`archive-lead`** - Archive a single lead, hiding it from the default pipeline and lists while preserving all its data. Stamps archived_at and archived_by; the lead can be restored later with the unarchive-lead action. Takes no payload beyond the target lead in the URL. Requires the manageCrm permission. Use this to clear out dead or irrelevant leads without deleting them.\n- **`unarchive-lead`** - Restore a previously archived lead back into the active pipeline. Standalone action. Payload: lead_id (required — the ULID of the archived lead to restore). Clears archived_at, archived_by, and status_before_archive so the lead reappears in normal lists and boards. Requires the manageCrm permission. Use this to undo an archive performed with the archive-lead action.\n- **`pause-sequence`** - Pause the automated drip email sequence for a single lead: sets the lead's drip_status to \"paused\" and stamps drip_paused_at, so no further scheduled sequence emails go out until it is resumed. Takes no payload beyond the target lead in the URL. Requires the manageCrm permission. Use this to temporarily hold outreach to a lead without removing it from the sequence; resume later with the resume-sequence action.\n- **`resume-sequence`** - Resume a paused drip email sequence for a single lead: sets the lead's drip_status back to \"active\" and clears drip_paused_at, so scheduled sequence emails resume. Takes no payload beyond the target lead in the URL. Requires the manageCrm permission. Use this to re-enable outreach that was previously paused with the pause-sequence action.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "import-from-linkedin", "import-leads-csv", "convert-to-client", "score-lead", "enrich-lead", "generate-message-for-lead", "send-email", "archive-lead", "unarchive-lead", "pause-sequence", "resume-sequence" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "import-from-linkedin", "type": "object", "properties": { "linkedin_url": { "description": "This field is required", "type": "string" }, "campaign_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "import-leads-csv", "type": "object", "properties": {} }, { "title": "convert-to-client", "type": "object", "properties": { "lead_role": { "description": "Maximum length: 150 characters", "maxLength": 150, "type": "string" }, "contact_name": { "description": "Maximum length: 200 characters", "maxLength": 200, "type": "string" }, "contact_email": { "description": "Maximum length: 200 characters", "maxLength": 200, "type": "string" }, "contact_phone": { "description": "Maximum length: 50 characters", "maxLength": 50, "type": "string" } } }, { "title": "score-lead", "type": "object", "properties": { "campaign_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "enrich-lead", "type": "object", "properties": {} }, { "title": "generate-message-for-lead", "type": "object", "properties": { "campaign_id": { "description": "Must exist in the database", "type": "string" }, "lead_stage_id": { "description": "Must exist in the database", "type": "integer" }, "context": { "description": "This field is optional", "type": "string" }, "length": { "description": "Must be an array", "type": "array" }, "length.subject_max": { "type": "string" }, "length.body_max": { "type": "string" } } }, { "title": "send-email", "type": "object", "properties": {} }, { "title": "archive-lead", "type": "object", "properties": {} }, { "title": "unarchive-lead", "type": "object", "properties": { "lead_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "pause-sequence", "type": "object", "properties": {} }, { "title": "resume-sequence", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/lead-stages": { "get": { "operationId": "lead-stages-index", "summary": "List lead stages", "description": "Lead pipeline stages: the ordered columns of the CRM kanban board, stored in the \"lead_stages\" table and scoped to the tenant. Each stage has a name, a numeric position (leads are always returned position-ascending), and an optional color/description. A stage is either scoped to a single campaign (campaign_id set) or a tenant-default template stage (campaign_id NULL) used by leads with no campaign. Leads reference a stage via lead.lead_stage_id; a stage cannot be deleted while any lead still occupies it. Use this repository to list, search by name, and manage the columns that structure the leads pipeline.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of lead-stages per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter lead-stages by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the lead-stages. Available options: name, position, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Filter lead-stages resource. Description: This is a exact match for name (e.g., name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Filter lead-stages resource. Description: This is a exact match for campaign_id (e.g., campaign_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -campaign_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadStageResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 8, "path": "https://demo.growee.test/api/restify/lead-stages", "per_page": 1, "to": 1, "total": 8 }, "links": { "first": "https://demo.growee.test/api/restify/lead-stages?page=1", "next": "https://demo.growee.test/api/restify/lead-stages?page=2", "path": "https://demo.growee.test/api/restify/lead-stages", "prev": null, "filters": "/api/restify/lead-stages/filters" }, "data": [ { "id": "8", "type": "lead_stages", "attributes": { "id": 8, "name": "On Hold", "position": 8, "color": "yellow", "created_at": "2026-07-05T18:03:54.000000Z", "updated_at": "2026-07-05T18:03:54.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "lead-stages-store", "summary": "Create a lead stage", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Display name of the pipeline stage / kanban column (e.g. \"New\", \"Contacted\", \"Qualified\"). Required, max 100 characters, and unique within the stage's campaign scope.", "maxLength": 100, "type": "string" }, "campaign_id": { "description": "ULID foreign key to the campaign (campaigns table) this stage belongs to. Null makes it a tenant-default stage shared by leads with no campaign. Set only on creation; it cannot be changed afterwards.", "type": "string" }, "position": { "description": "Zero-based integer sort order of the stage within its pipeline; lower numbers appear first. Required.", "minimum": 0, "type": "integer" }, "color": { "description": "Optional UI color for the stage column (a color name or hex string, max 50 characters).", "maxLength": 50, "type": "string" }, "description": { "description": "Optional free-text description explaining what the stage represents.", "type": "string" } }, "required": [ "name", "position" ] }, "example": { "name": "On Hold", "position": 8, "color": "yellow" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadStageResource" } } }, "example": { "data": { "id": "8", "type": "lead_stages", "attributes": { "id": 8, "name": "On Hold", "position": 8, "color": "yellow", "created_at": "2026-07-05T18:03:54.000000Z", "updated_at": "2026-07-05T18:03:54.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/lead-stages/{id}": { "get": { "operationId": "lead-stages-show", "summary": "Retrieve a lead stage", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead stage ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lead stage detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadStageResource" } } }, "example": { "data": { "id": "8", "type": "lead_stages", "attributes": { "id": 8, "name": "On Hold", "position": 8, "color": "yellow", "created_at": "2026-07-05T18:03:54.000000Z", "updated_at": "2026-07-05T18:03:54.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "lead-stages-update", "summary": "Update a lead stage", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead stage ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Display name of the pipeline stage / kanban column (e.g. \"New\", \"Contacted\", \"Qualified\"). Required, max 100 characters, and unique within the stage's campaign scope.", "maxLength": 100, "type": "string" }, "campaign_id": { "description": "ULID foreign key to the campaign (campaigns table) this stage belongs to. Null makes it a tenant-default stage shared by leads with no campaign. Set only on creation; it cannot be changed afterwards.", "type": "string" }, "position": { "description": "Zero-based integer sort order of the stage within its pipeline; lower numbers appear first. Required.", "minimum": 0, "type": "integer" }, "color": { "description": "Optional UI color for the stage column (a color name or hex string, max 50 characters).", "maxLength": 50, "type": "string" }, "description": { "description": "Optional free-text description explaining what the stage represents.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadStageResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "lead-stages-destroy", "summary": "Delete a lead stage", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead stage ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/lead-activities": { "get": { "operationId": "lead-activities-index", "summary": "List lead activities", "description": "Lead activities: the append-only timeline of a lead, stored in the \"lead_activities\" table and scoped to the tenant. Each row is either a manually authored \"note\" or a system event automatically emitted when the lead changes (stage_changed, owner_changed, field_changed, lost_reason_changed, converted, message_sent, email_blocked, interaction_logged, follow_up_completed, lead_created). Rows carry the parent lead_id, the activity type, an optional causer (the employee who triggered it), a text body (mainly for notes), and a meta JSON bag with event-specific details (e.g. from/to stage ids on a stage change). Use this repository to read a lead's history (filter by lead_id and/or type) or to add a note; note that only notes can be created here.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of lead-activities per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- causer (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=causer (include all fields)\n- include=causer[about,address] (selective fields with comma syntax)\n- include=causer[about|address] (selective fields with pipe syntax)\n- include=causer.posts (nested relationship - all fields)\n- include=causer[name].posts[title] (nested with field selection at each level)\n- include=causer[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=causer.posts[title],causer.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter lead-activities by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the lead-activities. Available options: created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "lead_id", "in": "query", "required": false, "description": "Filter lead-activities resource. Description: This is a exact match for lead_id (e.g., lead_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -lead_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter lead-activities resource. Description: This is a exact match for type (e.g., type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadActivityResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 54, "path": "https://demo.growee.test/api/restify/lead-activities", "per_page": 1, "to": 1, "total": 54 }, "links": { "first": "https://demo.growee.test/api/restify/lead-activities?page=1", "next": "https://demo.growee.test/api/restify/lead-activities?page=2", "path": "https://demo.growee.test/api/restify/lead-activities", "prev": null, "filters": "/api/restify/lead-activities/filters" }, "data": [ { "id": "01kwt1y3d6zzdbwfnr432zy6xf", "type": "lead_activities", "attributes": { "id": "01kwt1y3d6zzdbwfnr432zy6xf", "lead_id": "01kwt1y3d1v31d6z3hee7atw2k", "type": "note", "body": "Waiting on their procurement to confirm timeline.", "causer_id": "01kwt1xp69e0rhapkzb65nmxe5", "created_at": "2026-07-02T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "lead-activities-store", "summary": "Create a lead activity", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_id": { "description": "ULID foreign key to the lead (leads table) this activity belongs to. Required when creating a note.", "type": "string" }, "body": { "description": "The text content of the activity — the note body for notes, or a human-readable summary for system events. Required when creating a note.", "type": "string" } }, "required": [ "lead_id", "body" ] }, "example": { "lead_id": "01kwt1y3d1v31d6z3hee7atw2k", "body": "Waiting on their procurement to confirm timeline." } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadActivityResource" } } }, "example": { "data": { "id": "01kwt1y3d6zzdbwfnr432zy6xf", "type": "lead_activities", "attributes": { "id": "01kwt1y3d6zzdbwfnr432zy6xf", "lead_id": "01kwt1y3d1v31d6z3hee7atw2k", "type": "note", "body": "Waiting on their procurement to confirm timeline.", "causer_id": "01kwt1xp69e0rhapkzb65nmxe5", "created_at": "2026-07-02T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/lead-activities/{id}": { "get": { "operationId": "lead-activities-show", "summary": "Retrieve a lead activity", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead activity ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lead activity detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadActivityResource" } } }, "example": { "data": { "id": "01kwt1y3d6zzdbwfnr432zy6xf", "type": "lead_activities", "attributes": { "id": "01kwt1y3d6zzdbwfnr432zy6xf", "lead_id": "01kwt1y3d1v31d6z3hee7atw2k", "type": "note", "body": "Waiting on their procurement to confirm timeline.", "causer_id": "01kwt1xp69e0rhapkzb65nmxe5", "created_at": "2026-07-02T21:11:03.000000Z", "updated_at": "2026-07-05T21:11:18.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "lead-activities-update", "summary": "Update a lead activity", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead activity ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_id": { "description": "ULID foreign key to the lead (leads table) this activity belongs to. Required when creating a note.", "type": "string" }, "body": { "description": "The text content of the activity — the note body for notes, or a human-readable summary for system events. Required when creating a note.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadActivityResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "lead-activities-destroy", "summary": "Delete a lead activity", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead activity ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/activities": { "get": { "operationId": "activities-index", "summary": "List activities", "description": "Manages CRM activities: the chronological log of interactions with clients, leads, and client contacts, stored in the crm_activities table. Each row is one logged touchpoint (email, call, LinkedIn message, meeting, or note) attached to a polymorphic parent via record_type/record_id, authored by an employee, with an optional direction and a happened_at timestamp; pinned rows float to the top of the timeline. Use this to read or write the relationship history feed shown on a contact/lead/client. This is distinct from FollowUps (future scheduled tasks) and from the Timeline repository (employee lifecycle events); activities are past interactions in the CRM.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of activities per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- author (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=author (include all fields)\n- include=author[about,address] (selective fields with comma syntax)\n- include=author[about|address] (selective fields with pipe syntax)\n- include=author.posts (nested relationship - all fields)\n- include=author[name].posts[title] (nested with field selection at each level)\n- include=author[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=author.posts[title],author.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter activities by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the activities. Available options: happened_at, created_at, pinned (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "record_type", "in": "query", "required": false, "description": "Filter activities resource. Description: This is a exact match for record_type (e.g., record_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -record_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "record_id", "in": "query", "required": false, "description": "Filter activities resource. Description: This is a exact match for record_id (e.g., record_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -record_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter activities resource. Description: This is a exact match for type (e.g., type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "pinned", "in": "query", "required": false, "description": "Filter activities resource. Description: This is a boolean match for pinned (e.g., pinned=true or pinned=false). It accepts negation by prefixing the column with a hyphen (e.g., -pinned=true or -pinned=false). Accepted values are boolean.", "schema": { "type": "boolean" } }, { "name": "author_id", "in": "query", "required": false, "description": "Filter activities resource. Description: This is a exact match for author_id (e.g., author_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -author_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "required": false, "description": "Filter activities resource. Description: This is a exact match for organization_id (e.g., organization_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -organization_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 }, "links": { "first": "https://your-company.growee.net/api/restify/activities?page=1", "prev": null, "next": null }, "data": [ { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "activities", "attributes": { "id": 0, "record_type": "string", "record_id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "string", "direction": "string", "subject": "string", "body": "string", "happened_at": "2026-07-14", "author_id": "01jz9x8p4a3vn4dxyp71zsakqm", "pinned": "string", "meta": "string", "tenant_id": "01jz9x8p4a3vn4dxyp71zsakqm", "is_demo": false, "created_at": "2026-07-14", "updated_at": "2026-07-14" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "activities-store", "summary": "Create an activity", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_type": { "description": "The kind of parent record this activity is attached to; one of 'client', 'lead', or 'client_contact'. Set once at creation together with record_id and immutable afterwards.", "enum": [ "client_contact", "lead", "client" ], "type": "string" }, "record_id": { "description": "The ULID of the parent record (a client, lead, or client contact, as determined by record_type) that this activity belongs to. Must reference an existing record in the current tenant; immutable after creation.", "maxLength": 26, "type": "string" }, "type": { "description": "The kind of interaction being logged. Allowed values: 'email', 'call', 'linkedin_message', 'meeting', 'note'.", "type": "string" }, "direction": { "description": "Whether the interaction came from the contact or went out to them; one of 'inbound' or 'outbound'. Nullable/irrelevant for interaction types like a plain note.", "type": "string" }, "subject": { "description": "Short one-line summary or title of the interaction (e.g. an email subject or call topic), up to 255 characters. Optional.", "maxLength": 255, "type": "string" }, "body": { "description": "The full free-text content of the interaction: the email body, call notes, or the text of the note. Optional plain-text/markdown string with no length limit.", "type": "string" }, "happened_at": { "description": "When the interaction actually occurred, as an ISO 8601 datetime. Defaults to the current time on creation when omitted; drives the chronological ordering of the timeline.", "type": "string" }, "author_id": { "description": "ULID of the Employee (see the employees repository) who logged this activity. Set automatically server-side to the acting employee; any client-supplied value is ignored and the field is immutable.", "type": "string" }, "pinned": { "description": "Boolean flag; when true this activity is pinned and floats to the top of the record timeline regardless of its happened_at date. Defaults to false.", "type": "boolean" }, "meta": { "description": "Optional free-form JSON object holding extra structured metadata about the interaction (e.g. provider message ids or channel details). Arbitrary key/value array.", "type": "array" } }, "required": [ "record_type", "record_id", "type" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ActivityResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "activities", "attributes": { "id": 0, "record_type": "string", "record_id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "string", "direction": "string", "subject": "string", "body": "string", "happened_at": "2026-07-14", "author_id": "01jz9x8p4a3vn4dxyp71zsakqm", "pinned": "string", "meta": "string", "tenant_id": "01jz9x8p4a3vn4dxyp71zsakqm", "is_demo": false, "created_at": "2026-07-14", "updated_at": "2026-07-14" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/activities/{id}": { "get": { "operationId": "activities-show", "summary": "Retrieve an activity", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The activity ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ActivityResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "activities", "attributes": { "id": 0, "record_type": "string", "record_id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "string", "direction": "string", "subject": "string", "body": "string", "happened_at": "2026-07-14", "author_id": "01jz9x8p4a3vn4dxyp71zsakqm", "pinned": "string", "meta": "string", "tenant_id": "01jz9x8p4a3vn4dxyp71zsakqm", "is_demo": false, "created_at": "2026-07-14", "updated_at": "2026-07-14" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "activities-update", "summary": "Update an activity", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The activity ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "The kind of interaction being logged. Allowed values: 'email', 'call', 'linkedin_message', 'meeting', 'note'.", "type": "string" }, "direction": { "description": "Whether the interaction came from the contact or went out to them; one of 'inbound' or 'outbound'. Nullable/irrelevant for interaction types like a plain note.", "type": "string" }, "subject": { "description": "Short one-line summary or title of the interaction (e.g. an email subject or call topic), up to 255 characters. Optional.", "maxLength": 255, "type": "string" }, "body": { "description": "The full free-text content of the interaction: the email body, call notes, or the text of the note. Optional plain-text/markdown string with no length limit.", "type": "string" }, "happened_at": { "description": "When the interaction actually occurred, as an ISO 8601 datetime. Defaults to the current time on creation when omitted; drives the chronological ordering of the timeline.", "type": "string" }, "pinned": { "description": "Boolean flag; when true this activity is pinned and floats to the top of the record timeline regardless of its happened_at date. Defaults to false.", "type": "boolean" }, "meta": { "description": "Optional free-form JSON object holding extra structured metadata about the interaction (e.g. provider message ids or channel details). Arbitrary key/value array.", "type": "array" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ActivityResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "activities-destroy", "summary": "Delete an activity", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The activity ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/meetings": { "get": { "operationId": "meetings-index", "summary": "List meetings", "description": "Manages meeting records in Growee (the \"meetings\" table): logged 1:1s and client meetings together with their notes. Each row polymorphically references its subject via meetingable_type + meetingable_id (an employee or client), records the met_at date, free-text notes, and an optional linked calendar event (calendar_event_id/title). Use this to list, search (by notes), filter (by subject or met_at), or create meeting logs; it complements the Feedback repository — meetings capture that a conversation happened and its notes, while feedback captures evaluative commentary. Non-managers only see meetings they created (plus their direct reports' meetings if they manage those).", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of meetings per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- employeeCreator (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- meetingable (fields: id)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=creator,employeeCreator (include all fields)\n- include=creator[archived_at,avatar] (selective fields with comma syntax)\n- include=creator[archived_at|avatar] (selective fields with pipe syntax)\n- include=creator.posts (nested relationship - all fields)\n- include=creator[name].posts[title] (nested with field selection at each level)\n- include=creator[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=creator.posts[title],creator.comments[body] (multiple nested from same parent)\n- include=creator[name],employeeCreator[id] (multiple relationships with field selection)\n- include=creator[email|name].posts[title],employeeCreator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter meetings by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the meetings. Available options: met_at, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "met_at", "in": "query", "required": false, "description": "Filter meetings resource. Description: This is a range match for met_at (e.g., met_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -met_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "meetingable_id", "in": "query", "required": false, "description": "Filter meetings resource. Description: This is a exact match for meetingable_id (e.g., meetingable_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -meetingable_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "meetingable_type", "in": "query", "required": false, "description": "Filter meetings resource. Description: This is a exact match for meetingable_type (e.g., meetingable_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -meetingable_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 5, "path": "https://demo.growee.test/api/restify/meetings", "per_page": 1, "to": 1, "total": 5 }, "links": { "first": "https://demo.growee.test/api/restify/meetings?page=1", "next": "https://demo.growee.test/api/restify/meetings?page=2", "path": "https://demo.growee.test/api/restify/meetings", "prev": null, "filters": "/api/restify/meetings/filters" }, "data": [ { "id": "01kwt1y3dbvqzn7wh0spxrswpg", "type": "meetings", "attributes": { "id": "01kwt1y3dbvqzn7wh0spxrswpg", "meetingable_type": "client", "meetingable_id": "01kwt1xszttmp3jwatej49q4qe", "met_at": "2026-06-20T00:00:00.000000Z", "notes": "Kick-off for milestone 3 — launch checklist agreed.", "created_by": "01kwt1xnc4c15beb3jr1109trm", "created_by_employee_id": "01kwt1xncps2bcdqep555p1300" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "meetings-store", "summary": "Create a meeting", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "meetingable_type": { "description": "Polymorphic subject type the meeting was with: \"employee\" or \"client\". Required when creating.", "type": "string" }, "meetingable_id": { "description": "ULID of the subject the meeting was with — an Employee or a Client depending on meetingable_type. Required when creating, max 26 chars.", "maxLength": 26, "type": "string" }, "met_at": { "description": "Date the meeting took place (YYYY-MM-DD). Defaults to today when not provided on creation.", "type": "string" }, "notes": { "description": "Free-text notes captured about the meeting. May be null.", "type": "string" }, "calendar_event_id": { "description": "Optional identifier of an external calendar event this meeting is linked to (e.g. a Google Calendar event id). Max 255 chars, may be null.", "maxLength": 255, "type": "string" }, "calendar_event_title": { "description": "Optional title of the linked external calendar event. Max 500 chars, may be null.", "maxLength": 500, "type": "string" } }, "required": [ "meetingable_type", "meetingable_id" ] }, "example": { "meetingable_type": "client", "meetingable_id": "01kwt1xszttmp3jwatej49q4qe", "met_at": "2026-06-20T00:00:00.000000Z", "notes": "Kick-off for milestone 3 — launch checklist agreed." } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeetingResource" } } }, "example": { "data": { "id": "01kwt1y3dbvqzn7wh0spxrswpg", "type": "meetings", "attributes": { "id": "01kwt1y3dbvqzn7wh0spxrswpg", "meetingable_type": "client", "meetingable_id": "01kwt1xszttmp3jwatej49q4qe", "met_at": "2026-06-20T00:00:00.000000Z", "notes": "Kick-off for milestone 3 — launch checklist agreed.", "created_by": "01kwt1xnc4c15beb3jr1109trm", "created_by_employee_id": "01kwt1xncps2bcdqep555p1300" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/meetings/{id}": { "get": { "operationId": "meetings-show", "summary": "Retrieve a meeting", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The meeting ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Meeting detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeetingResource" } } }, "example": { "data": { "id": "01kwt1y3dbvqzn7wh0spxrswpg", "type": "meetings", "attributes": { "id": "01kwt1y3dbvqzn7wh0spxrswpg", "meetingable_type": "client", "meetingable_id": "01kwt1xszttmp3jwatej49q4qe", "met_at": "2026-06-20T00:00:00.000000Z", "notes": "Kick-off for milestone 3 — launch checklist agreed.", "created_by": "01kwt1xnc4c15beb3jr1109trm", "created_by_employee_id": "01kwt1xncps2bcdqep555p1300" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "meetings-update", "summary": "Update a meeting", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The meeting ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "meetingable_type": { "description": "Polymorphic subject type the meeting was with: \"employee\" or \"client\". Required when creating.", "type": "string" }, "meetingable_id": { "description": "ULID of the subject the meeting was with — an Employee or a Client depending on meetingable_type. Required when creating, max 26 chars.", "type": "string" }, "met_at": { "description": "Date the meeting took place (YYYY-MM-DD). Defaults to today when not provided on creation.", "type": "string" }, "notes": { "description": "Free-text notes captured about the meeting. May be null.", "type": "string" }, "calendar_event_id": { "description": "Optional identifier of an external calendar event this meeting is linked to (e.g. a Google Calendar event id). Max 255 chars, may be null.", "maxLength": 255, "type": "string" }, "calendar_event_title": { "description": "Optional title of the linked external calendar event. Max 500 chars, may be null.", "maxLength": 500, "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeetingResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "meetings-destroy", "summary": "Delete a meeting", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The meeting ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/crm-tickets": { "get": { "operationId": "crm-tickets-index", "summary": "List crm tickets", "description": "Lists and inspects support tickets (crm_tickets table) for the current tenant, newest inbound activity first. A ticket is a durable customer conversation thread opened from mail on a support-type inbox address (crm-inbox-addresses) or created manually; each carries a per-tenant `number`, a workflow `stage` (crm-ticket-stages), a `priority`, an optional assigned `owner` (employee), and links to the requesting `contact` (client_contacts) and `organization` (clients). An AI agent uses this to triage the support queue, find tickets by stage/priority/owner/organization/contact, check SLA timing (first_response_due_at), and read the conversation via the `thread` getter. Tickets differ from crm-inbound-emails: an inbound email is a single received message, whereas a ticket is the ongoing thread that support mail is grouped into.", "tags": [ "Tickets" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of crm-tickets per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- stage (fields: color, created_at, id, name, position, semantic, updated_at)\n- owner (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- organization (fields: city, company_name, country, created_at, created_by, custom_fields, domain, id, industry, is_demo, lifecycle_stage, meta, owner_id, size, tenant_id, updated_at, updated_by, website)\n- contact (fields: client_id, custom_fields, email, id, name, phone, position, verification_status)\n- inboxAddress (fields: address, created_at, display_name, id, is_active, sla_first_response_hours, tenant_id, type, updated_at)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=stage,owner (include all fields)\n- include=stage[color,created_at] (selective fields with comma syntax)\n- include=stage[color|created_at] (selective fields with pipe syntax)\n- include=stage.posts (nested relationship - all fields)\n- include=stage[name].posts[title] (nested with field selection at each level)\n- include=stage[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=stage.posts[title],stage.comments[body] (multiple nested from same parent)\n- include=stage[name],owner[id] (multiple relationships with field selection)\n- include=stage[email|name].posts[title],owner[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter crm-tickets by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the crm-tickets. Available options: number, created_at, last_inbound_at, first_response_due_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "ticket_stage_id", "in": "query", "required": false, "description": "Filter crm-tickets resource. Description: This is a exact match for ticket_stage_id (e.g., ticket_stage_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -ticket_stage_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "description": "Filter crm-tickets resource. Description: This is a exact match for priority (e.g., priority=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -priority=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Filter crm-tickets resource. Description: This is a exact match for owner_id (e.g., owner_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -owner_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "required": false, "description": "Filter crm-tickets resource. Description: This is a exact match for organization_id (e.g., organization_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -organization_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "client_contact_id", "in": "query", "required": false, "description": "Filter crm-tickets resource. Description: This is a exact match for client_contact_id (e.g., client_contact_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -client_contact_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTicketResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 }, "links": { "first": "https://your-company.growee.net/api/restify/crm-tickets?page=1", "prev": null, "next": null }, "data": [ { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "crm_tickets", "attributes": { "id": 0, "number": "string", "subject": "string", "ticket_stage_id": "01jz9x8p4a3vn4dxyp71zsakqm", "priority": "string", "owner_id": "01jz9x8p4a3vn4dxyp71zsakqm", "organization_id": "01jz9x8p4a3vn4dxyp71zsakqm", "client_contact_id": "01jz9x8p4a3vn4dxyp71zsakqm", "inbox_address_id": "01jz9x8p4a3vn4dxyp71zsakqm", "source": "string", "first_response_due_at": "2026-07-14", "first_responded_at": "2026-07-14", "closed_at": "2026-07-14", "last_inbound_at": "2026-07-14", "meta": "string", "created_at": "2026-07-14", "updated_at": "2026-07-14" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "crm-tickets-store", "summary": "Create a crm ticket", "tags": [ "Tickets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "description": "The ticket subject/title summarizing the request. Max 255 characters.", "maxLength": 255, "type": "string" }, "ticket_stage_id": { "description": "ULID of the current workflow stage (column), referencing a crm-ticket-stages record belonging to this tenant. Set to move the ticket across the kanban board.", "type": "string" }, "priority": { "description": "Ticket priority. One of: `low`, `normal`, `high`, `urgent`. Defaults to `normal`.", "type": "string" }, "owner_id": { "description": "ULID of the employee (employees table) assigned to handle this ticket, or null if unassigned. Must belong to the current tenant.", "type": "string" } }, "required": [ "ticket_stage_id" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTicketResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "crm_tickets", "attributes": { "id": 0, "number": "string", "subject": "string", "ticket_stage_id": "01jz9x8p4a3vn4dxyp71zsakqm", "priority": "string", "owner_id": "01jz9x8p4a3vn4dxyp71zsakqm", "organization_id": "01jz9x8p4a3vn4dxyp71zsakqm", "client_contact_id": "01jz9x8p4a3vn4dxyp71zsakqm", "inbox_address_id": "01jz9x8p4a3vn4dxyp71zsakqm", "source": "string", "first_response_due_at": "2026-07-14", "first_responded_at": "2026-07-14", "closed_at": "2026-07-14", "last_inbound_at": "2026-07-14", "meta": "string", "created_at": "2026-07-14", "updated_at": "2026-07-14" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/crm-tickets/{id}": { "get": { "operationId": "crm-tickets-show", "summary": "Retrieve a crm ticket", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Crm ticket detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTicketResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "crm_tickets", "attributes": { "id": 0, "number": "string", "subject": "string", "ticket_stage_id": "01jz9x8p4a3vn4dxyp71zsakqm", "priority": "string", "owner_id": "01jz9x8p4a3vn4dxyp71zsakqm", "organization_id": "01jz9x8p4a3vn4dxyp71zsakqm", "client_contact_id": "01jz9x8p4a3vn4dxyp71zsakqm", "inbox_address_id": "01jz9x8p4a3vn4dxyp71zsakqm", "source": "string", "first_response_due_at": "2026-07-14", "first_responded_at": "2026-07-14", "closed_at": "2026-07-14", "last_inbound_at": "2026-07-14", "meta": "string", "created_at": "2026-07-14", "updated_at": "2026-07-14" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "crm-tickets-update", "summary": "Update a crm ticket", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "description": "The ticket subject/title summarizing the request. Max 255 characters.", "maxLength": 255, "type": "string" }, "ticket_stage_id": { "description": "ULID of the current workflow stage (column), referencing a crm-ticket-stages record belonging to this tenant. Set to move the ticket across the kanban board.", "type": "string" }, "priority": { "description": "Ticket priority. One of: `low`, `normal`, `high`, `urgent`. Defaults to `normal`.", "type": "string" }, "owner_id": { "description": "ULID of the employee (employees table) assigned to handle this ticket, or null if unassigned. Must belong to the current tenant.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTicketResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "crm-tickets-destroy", "summary": "Delete a crm ticket", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/crm-tickets/getters/thread": { "get": { "operationId": "crm-tickets-getter-thread", "summary": "Thread", "description": "Returns the full conversation of a single support ticket, oldest message first. Each entry includes its `direction` (inbound/outbound/note), from/to addresses, subject, body, RFC message-id, the authoring agent summary, and timestamp. Read-only and takes no payload. Use this to read the entire back-and-forth before replying, closing, or summarizing a ticket.", "tags": [ "Tickets" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/crm-tickets/{id}/actions": { "post": { "operationId": "crm-tickets-record-actions", "summary": "Actions: reply, add-note, close", "description": "Perform an action on a single crm ticket. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`reply`** - Sends a customer-facing reply on a support ticket: emails the message to the ticket contact and appends it to the thread as an outbound message authored by the current employee, updating first-response timing. Use this to answer the customer. Payload: `body` (required string, the reply text). This action sends mail — for a private team-only note that is not emailed, use add-note instead.\n- **`add-note`** - Adds an internal note to a support ticket's thread. The note is authored by the current employee and stored as an internal-direction message; it is NOT emailed to the customer. Use this to record private context, hand-off information, or investigation findings visible only to the team. Payload: `body` (required string, the note text). To send a customer-facing message instead, use the reply action.\n- **`close`** - Closes a support ticket: moves it to the tenant's `closed`-semantic stage and stamps closed_at. Use this when the customer request is resolved. Takes no payload. A subsequent inbound reply reopens the ticket automatically, so closing is safe even if the customer might respond again.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "reply", "add-note", "close" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "reply", "type": "object", "properties": { "body": { "description": "This field is required", "type": "string" } } }, { "title": "add-note", "type": "object", "properties": { "body": { "description": "This field is required", "type": "string" } } }, { "title": "close", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/crm-ticket-stages": { "get": { "operationId": "crm-ticket-stages-index", "summary": "List crm ticket stages", "description": "Lists the support-ticket kanban stages (columns) for the current tenant from the crm_ticket_stages table, ordered by position. Each stage is a status column that tickets (crm-tickets) move through; the four default stages are auto-seeded on first read. An AI agent uses this to discover valid ticket_stage_id values before creating or moving a ticket, and to understand the tenant's support workflow. The optional `semantic` flag marks the four behaviour-relevant stages (new, open, waiting, closed) that drive SLA and auto-close logic; other stages are purely organizational.", "tags": [ "Tickets" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of crm-ticket-stages per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter crm-ticket-stages by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the crm-ticket-stages. Available options: name, position, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Filter crm-ticket-stages resource. Description: This is a exact match for name (e.g., name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "semantic", "in": "query", "required": false, "description": "Filter crm-ticket-stages resource. Description: This is a exact match for semantic (e.g., semantic=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -semantic=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTicketStageResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 4, "path": "https://demo.growee.test/api/restify/crm-ticket-stages", "per_page": 1, "to": 1, "total": 4 }, "links": { "first": "https://demo.growee.test/api/restify/crm-ticket-stages?page=1", "next": "https://demo.growee.test/api/restify/crm-ticket-stages?page=2", "path": "https://demo.growee.test/api/restify/crm-ticket-stages", "prev": null, "filters": "/api/restify/crm-ticket-stages/filters" }, "data": [ { "id": "01kx5nszqzg6hg9gxjbf27gj2e", "type": "crm_ticket_stages", "attributes": { "id": "01kx5nszqzg6hg9gxjbf27gj2e", "name": "Closed", "position": 3, "color": "#10B981", "semantic": "closed", "created_at": "2026-07-10T09:30:13.000000Z", "updated_at": "2026-07-10T09:30:13.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "crm-ticket-stages-store", "summary": "Create a crm ticket stage", "tags": [ "Tickets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The user-facing name of the kanban column (e.g. \"Waiting on customer\"). Must be unique within the tenant; max 100 characters.", "maxLength": 100, "type": "string" }, "position": { "description": "0-based sort order of this column on the kanban board; lower numbers appear first. Non-negative integer.", "minimum": 0, "type": "integer" }, "color": { "description": "Optional display color for the column (e.g. a hex code or CSS color name), used for the board UI. Null when unset.", "maxLength": 50, "type": "string" } }, "required": [ "name", "position" ] }, "example": { "name": "Closed", "position": 3, "color": "#10B981" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTicketStageResource" } } }, "example": { "data": { "id": "01kx5nszqzg6hg9gxjbf27gj2e", "type": "crm_ticket_stages", "attributes": { "id": "01kx5nszqzg6hg9gxjbf27gj2e", "name": "Closed", "position": 3, "color": "#10B981", "semantic": "closed", "created_at": "2026-07-10T09:30:13.000000Z", "updated_at": "2026-07-10T09:30:13.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/crm-ticket-stages/{id}": { "get": { "operationId": "crm-ticket-stages-show", "summary": "Retrieve a crm ticket stage", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket stage ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Crm ticket stage detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTicketStageResource" } } }, "example": { "data": { "id": "01kx5nszqzg6hg9gxjbf27gj2e", "type": "crm_ticket_stages", "attributes": { "id": "01kx5nszqzg6hg9gxjbf27gj2e", "name": "Closed", "position": 3, "color": "#10B981", "semantic": "closed", "created_at": "2026-07-10T09:30:13.000000Z", "updated_at": "2026-07-10T09:30:13.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "crm-ticket-stages-update", "summary": "Update a crm ticket stage", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket stage ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The user-facing name of the kanban column (e.g. \"Waiting on customer\"). Must be unique within the tenant; max 100 characters.", "maxLength": 100, "type": "string" }, "position": { "description": "0-based sort order of this column on the kanban board; lower numbers appear first. Non-negative integer.", "minimum": 0, "type": "integer" }, "color": { "description": "Optional display color for the column (e.g. a hex code or CSS color name), used for the board UI. Null when unset.", "maxLength": 50, "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTicketStageResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "crm-ticket-stages-destroy", "summary": "Delete a crm ticket stage", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The crm ticket stage ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/offers": { "get": { "operationId": "offers-index", "summary": "List offers", "description": "Manages offers: sales quotes/proposals a tenant sends to clients, stored in the crm_offers table with ULID primary keys. Each offer belongs to one organization (a client) and optionally a lead, carries a set of priced line items (crm_offer_lines, exposed via the offer-lines repository) that drive its subtotal, vat_amount and total, and moves through a lifecycle: draft -> sent -> viewed -> signed/declined/expired. Offers can be previewed as a shareable PDF, sent to a signer for e-signature (creating a signing envelope_id), and converted into a formal agreement document. Use this repository to look up, search by title/organization, filter by status or valid_until, and report on the quoting pipeline; use the show-only actions to preview, send for signature, or generate an agreement.", "tags": [ "Offers" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of offers per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- organization (fields: city, company_name, country, created_at, created_by, custom_fields, domain, id, industry, is_demo, lifecycle_stage, meta, owner_id, size, tenant_id, updated_at, updated_by, website)\n- lead (fields: archived_at, archived_by, campaign_id, company_name, company_size, company_website, converted_at, converted_to_client_id, created_at, created_by, custom_fields, drip_paused_at, drip_status, due_today_follow_up, email, enriched_at, expected_close_date, expected_revenue, fit_score, id, industry, last_contacted_at, lead_stage_id, linkedin_url, location, lost_reason, metadata, name, organization_id, overdue_follow_up, owner_id, phone, probability, source, status_before_archive, tags, title, updated_at, updated_by, verification_status)\n- signerContact (fields: client_id, custom_fields, email, id, name, phone, position, verification_status)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- lines (fields: created_at, description, id, offer_id, quantity, sort_order, tenant_id, total, unit_price, updated_at, vat_rate)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=organization,lead (include all fields)\n- include=organization[city,company_name] (selective fields with comma syntax)\n- include=organization[city|company_name] (selective fields with pipe syntax)\n- include=organization.posts (nested relationship - all fields)\n- include=organization[name].posts[title] (nested with field selection at each level)\n- include=organization[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=organization.posts[title],organization.comments[body] (multiple nested from same parent)\n- include=organization[name],lead[id] (multiple relationships with field selection)\n- include=organization[email|name].posts[title],lead[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter offers by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the offers. Available options: created_at, total, valid_until, status (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "required": false, "description": "Filter offers resource. Description: This is a exact match for organization_id (e.g., organization_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -organization_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "lead_id", "in": "query", "required": false, "description": "Filter offers resource. Description: This is a exact match for lead_id (e.g., lead_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -lead_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter offers resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "valid_until", "in": "query", "required": false, "description": "Filter offers resource. Description: This is a range match for valid_until (e.g., valid_until=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -valid_until=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 }, "links": { "first": "https://your-company.growee.net/api/restify/offers?page=1", "prev": null, "next": null }, "data": [ { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "offers", "attributes": { "id": 0, "organization_id": "01jz9x8p4a3vn4dxyp71zsakqm", "lead_id": "01jz9x8p4a3vn4dxyp71zsakqm", "signer_contact_id": "01jz9x8p4a3vn4dxyp71zsakqm", "signer_name": "string", "signer_email": "string", "title": "string", "offer_number": 0, "currency": "string", "valid_until": "string", "terms": "string", "notes": "string", "status": "string", "subtotal": "string", "vat_amount": 0, "total": "string", "envelope_id": "01jz9x8p4a3vn4dxyp71zsakqm", "sent_at": "2026-07-14", "viewed_at": "2026-07-14", "signed_at": "2026-07-14", "declined_at": "2026-07-14", "tenant_id": "01jz9x8p4a3vn4dxyp71zsakqm", "created_by": "string", "created_at": "2026-07-14", "updated_at": "2026-07-14" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "offers-store", "summary": "Create an offer", "tags": [ "Offers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "description": "ULID foreign key to the client this offer is addressed to (references the ClientRepository / clients table, also surfaced as an organization). Required on create and cannot be changed afterwards.", "type": "string" }, "lead_id": { "description": "Optional ULID foreign key to the sales lead this offer originated from (references the LeadRepository / leads table). Null when the offer is not tied to a specific lead.", "type": "string" }, "signer_contact_id": { "description": "Optional ULID foreign key to the client contact (person) designated to sign this offer (references the ClientContactRepository / client_contacts table). Used to pre-fill signer details when sending for signature.", "type": "string" }, "signer_name": { "description": "Full name of the person who will sign the offer. Free text, up to 255 characters; typically taken from the signer contact but can be set manually.", "maxLength": 255, "type": "string" }, "signer_email": { "description": "Email address of the signer, where the e-signature request is delivered. Must be a valid email.", "type": "string" }, "title": { "description": "Human-readable title of the offer shown to the client (e.g. \"Website redesign proposal\"). Required, up to 255 characters.", "maxLength": 255, "type": "string" }, "offer_number": { "description": "Optional human-facing reference number for the offer (e.g. \"OFF-2026-001\"), up to 100 characters. Null if not assigned.", "maxLength": 100, "type": "integer" }, "currency": { "description": "ISO 4217 three-letter currency code (exactly 3 characters, e.g. \"EUR\", \"USD\") in which all line-item prices and totals are expressed. Defaults to \"EUR\".", "minLength": 3, "maxLength": 3, "type": "string" }, "valid_until": { "description": "Date (Y-m-d) until which the offer remains valid; after this date it may be treated as expired. Null when the offer has no expiry.", "type": "string" }, "terms": { "description": "Free-text terms and conditions displayed on the offer (e.g. payment terms, scope caveats). Null when none are set.", "type": "string" }, "notes": { "description": "Free-text internal or client-facing notes attached to the offer. Null when none are set.", "type": "string" } }, "required": [ "organization_id", "title" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OfferResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "offers", "attributes": { "id": 0, "organization_id": "01jz9x8p4a3vn4dxyp71zsakqm", "lead_id": "01jz9x8p4a3vn4dxyp71zsakqm", "signer_contact_id": "01jz9x8p4a3vn4dxyp71zsakqm", "signer_name": "string", "signer_email": "string", "title": "string", "offer_number": 0, "currency": "string", "valid_until": "string", "terms": "string", "notes": "string", "status": "string", "subtotal": "string", "vat_amount": 0, "total": "string", "envelope_id": "01jz9x8p4a3vn4dxyp71zsakqm", "sent_at": "2026-07-14", "viewed_at": "2026-07-14", "signed_at": "2026-07-14", "declined_at": "2026-07-14", "tenant_id": "01jz9x8p4a3vn4dxyp71zsakqm", "created_by": "string", "created_at": "2026-07-14", "updated_at": "2026-07-14" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/offers/{id}": { "get": { "operationId": "offers-show", "summary": "Retrieve an offer", "tags": [ "Offers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The offer ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OfferResource" } } }, "example": { "data": { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "offers", "attributes": { "id": 0, "organization_id": "01jz9x8p4a3vn4dxyp71zsakqm", "lead_id": "01jz9x8p4a3vn4dxyp71zsakqm", "signer_contact_id": "01jz9x8p4a3vn4dxyp71zsakqm", "signer_name": "string", "signer_email": "string", "title": "string", "offer_number": 0, "currency": "string", "valid_until": "string", "terms": "string", "notes": "string", "status": "string", "subtotal": "string", "vat_amount": 0, "total": "string", "envelope_id": "01jz9x8p4a3vn4dxyp71zsakqm", "sent_at": "2026-07-14", "viewed_at": "2026-07-14", "signed_at": "2026-07-14", "declined_at": "2026-07-14", "tenant_id": "01jz9x8p4a3vn4dxyp71zsakqm", "created_by": "string", "created_at": "2026-07-14", "updated_at": "2026-07-14" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "offers-update", "summary": "Update an offer", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Offers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The offer ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_id": { "description": "Optional ULID foreign key to the sales lead this offer originated from (references the LeadRepository / leads table). Null when the offer is not tied to a specific lead.", "type": "string" }, "signer_contact_id": { "description": "Optional ULID foreign key to the client contact (person) designated to sign this offer (references the ClientContactRepository / client_contacts table). Used to pre-fill signer details when sending for signature.", "type": "string" }, "signer_name": { "description": "Full name of the person who will sign the offer. Free text, up to 255 characters; typically taken from the signer contact but can be set manually.", "maxLength": 255, "type": "string" }, "signer_email": { "description": "Email address of the signer, where the e-signature request is delivered. Must be a valid email.", "type": "string" }, "title": { "description": "Human-readable title of the offer shown to the client (e.g. \"Website redesign proposal\"). Required, up to 255 characters.", "maxLength": 255, "type": "string" }, "offer_number": { "description": "Optional human-facing reference number for the offer (e.g. \"OFF-2026-001\"), up to 100 characters. Null if not assigned.", "maxLength": 100, "type": "integer" }, "currency": { "description": "ISO 4217 three-letter currency code (exactly 3 characters, e.g. \"EUR\", \"USD\") in which all line-item prices and totals are expressed. Defaults to \"EUR\".", "minLength": 3, "maxLength": 3, "type": "string" }, "valid_until": { "description": "Date (Y-m-d) until which the offer remains valid; after this date it may be treated as expired. Null when the offer has no expiry.", "type": "string" }, "terms": { "description": "Free-text terms and conditions displayed on the offer (e.g. payment terms, scope caveats). Null when none are set.", "type": "string" }, "notes": { "description": "Free-text internal or client-facing notes attached to the offer. Null when none are set.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OfferResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "offers-destroy", "summary": "Delete an offer", "tags": [ "Offers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The offer ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/offers/{id}/actions": { "post": { "operationId": "offers-record-actions", "summary": "Actions: send-for-signature, preview-pdf, generate-agreement, ...", "description": "Perform an action on a single offer. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`send-for-signature`** - Sends this offer to the designated signer for e-signature, creating a signing envelope and advancing the offer status from draft to sent. Required payload keys: signer_name and signer_email (the recipient of the signature request); optional signer_contact_id (ULID of a client_contacts row). Returns the new status and the created envelope_id. Requires the manage-CRM permission. Call this when a draft offer is ready to be signed by the client.\n- **`preview-pdf`** - Generates a fresh public share token for this offer and returns a share_url pointing to the client-facing offer details page (where it can be viewed and downloaded as a PDF). Takes no payload. Side effect: creates a new shareable link each time it is called. Requires the manage-CRM permission. Call this to obtain a shareable/preview link for an offer without sending it for signature.\n- **`generate-agreement`** - Generates a formal agreement (contract) document from this offer by rendering an agreement template with the offer data, and persists it as a CRM document. Optional payload key: template_id (ULID of a crm_agreement_templates row to use); when omitted the tenant default template (or the most recent one) is used. Returns document_id and a download_url. Requires the manage-CRM permission. Call this after an offer is agreed to produce the signable contract, then use send-agreement-for-signature to route it to the signer.\n- **`send-agreement-for-signature`** - Sends a previously generated agreement (contract) document tied to this offer to the signer for e-signature, creating a signing envelope and advancing the offer status. Required payload keys: agreement_document_id (ULID of a crm_documents row whose source is \"agreement\"), signer_name and signer_email; optional signer_contact_id (ULID of a client_contacts row). Returns the new status and envelope_id. Requires the manage-CRM permission. Call this after generate-agreement to route the formal contract for signing (as opposed to send-for-signature, which signs the offer itself).", "tags": [ "Offers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The offer ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "send-for-signature", "preview-pdf", "generate-agreement", "send-agreement-for-signature" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "send-for-signature", "type": "object", "properties": { "signer_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "signer_email": { "description": "This field is required", "type": "string" }, "signer_contact_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "preview-pdf", "type": "object", "properties": {} }, { "title": "generate-agreement", "type": "object", "properties": { "template_id": { "description": "Must exist in the database", "type": "string" } } }, { "title": "send-agreement-for-signature", "type": "object", "properties": { "signer_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "signer_email": { "description": "This field is required", "type": "string" }, "signer_contact_id": { "description": "Must exist in the database", "type": "string" }, "agreement_document_id": { "description": "Must exist in the database", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/documents": { "get": { "operationId": "documents-index", "summary": "List documents", "description": "Manages employee and client documents stored in the documents table: uploaded files (contracts, IDs, certificates, payslips) plus generated HTML documents, each classified by a document type and optionally owned by an employee or a client. Every document tracks its file (path, file_name, size, storage disk), an optional validity window (start_date/end_date, used for expiry reminders), free-form tags, and e-signature state (is_signed, signature_count). Documents may be generated from a Template (see the templates repository, which holds the reusable HTML blueprints) and can be shared for external signing. Use this repository to list, search (by employee, document type, or name), filter (by status, tags, client, expiry), upload, retag, sign, and download an employee's or client's files.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of documents per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- documentType (fields: description, id, is_used, name)\n- tags (fields: color, name, type)\n- client (fields: bank_account, bank_name, bank_swift, city, company_address, company_identifier, company_name, company_vat, country, created_at, custom_fields, description, domain, id, industry, is_used, lifecycle_stage, logo_path, meta, owner_id, prefered_currency, representative_name, representative_position, size, website)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,documentType (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],documentType[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],documentType[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter documents by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the documents. Available options: name, created_at, documentType, documentable_type, end_date, start_date (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for client_id (e.g., client_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -client_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type_id", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for type_id (e.g., type_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a range match for start_date (e.g., start_date=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -start_date=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a range match for end_date (e.g., end_date=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -end_date=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "documentable_type", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for documentable_type (e.g., documentable_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -documentable_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "expired", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for expired (e.g., expired=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -expired=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "active_employee", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for active_employee (e.g., active_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -active_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "required": false, "description": "Filter documents resource. Description: This is a exact match for tags (e.g., tags=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -tags=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 167, "path": "https://demo.growee.test/api/restify/documents", "per_page": 1, "to": 1, "total": 167 }, "links": { "first": "https://demo.growee.test/api/restify/documents?page=1", "next": "https://demo.growee.test/api/restify/documents?page=2", "path": "https://demo.growee.test/api/restify/documents", "prev": null, "filters": "/api/restify/documents/filters" }, "data": [ { "id": "01kwt1y34bxq95sfwszsk8byam", "type": "documents", "attributes": { "id": "01kwt1y34bxq95sfwszsk8byam", "name": "Master service agreement — Craft Media Inc", "description": "Signed MSA covering all engagements", "type_id": "01kwt1y1yvkxz68ye23e91m37d", "client_id": "01kwt1xszttmp3jwatej49q4qe", "path": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "file_name": "master-service-agreement-craft-media-inc.pdf", "size": 1740374, "start_date": "2025-01-01T00:00:00.000000Z", "documentable_type": "client", "status": "new", "is_signed": false, "signature_count": 0, "created_at": "2026-07-05T21:11:17.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "documents-store", "summary": "Create a document", "tags": [ "Documents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable title of the document (e.g. \"Employment Contract\", \"ID Card\"). Required when creating a document.", "type": "string" }, "description": { "description": "Optional free-text note describing the document or its purpose.", "type": "string" }, "content": { "description": "Optional HTML body of the document, used for documents generated from a template rather than an uploaded file; can be converted to a Word/PDF file on demand.", "type": "string" }, "type_id": { "description": "Required ULID foreign key to a document_types record (managed by the document-types repository) that classifies this document, e.g. contract, ID, certificate.", "type": "string" }, "employee_id": { "description": "Optional ULID foreign key to the employee (employees repository) this document belongs to; if omitted on write it defaults to the current user's own employee unless they manage documents.", "type": "string" }, "client_id": { "description": "Optional ULID foreign key to the client (clients repository) this document belongs to; used for client-owned documents instead of employee-owned ones.", "type": "string" }, "path": { "description": "The uploaded file itself: send the raw file or a base64-encoded string when creating a document. Allowed types are pptx, pdf, docx, doc, txt, csv, rtf, jpg, jpeg, png, svg, gif, bmp, xls, xlsx, ppt (max 20MB). On read it resolves to a temporary download URL.", "maxLength": 20480, "type": "string" }, "file_name": { "description": "The original name of the uploaded file including its extension (e.g. \"contract.pdf\"). Send this alongside \"path\" when uploading.", "type": "string" }, "start_date": { "description": "Optional validity start date of the document (ISO 8601 / Y-m-d datetime).", "type": "string" }, "end_date": { "description": "Optional validity/expiry end date (ISO 8601 / Y-m-d datetime); when set the system can send expiration reminders to the owner.", "type": "string" }, "status": { "description": "Read-only lifecycle status of the document (currently always \"new\").", "type": "string" } }, "required": [ "name", "type_id", "path" ] }, "example": { "name": "Master service agreement — Craft Media Inc", "description": "Signed MSA covering all engagements", "type_id": "01kwt1y1yvkxz68ye23e91m37d", "client_id": "01kwt1xszttmp3jwatej49q4qe", "path": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "file_name": "master-service-agreement-craft-media-inc.pdf", "start_date": "2025-01-01T00:00:00.000000Z", "status": "new" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentResource" } } }, "example": { "data": { "id": "01kwt1y34bxq95sfwszsk8byam", "type": "documents", "attributes": { "id": "01kwt1y34bxq95sfwszsk8byam", "name": "Master service agreement — Craft Media Inc", "description": "Signed MSA covering all engagements", "type_id": "01kwt1y1yvkxz68ye23e91m37d", "client_id": "01kwt1xszttmp3jwatej49q4qe", "path": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "file_name": "master-service-agreement-craft-media-inc.pdf", "size": 1740374, "start_date": "2025-01-01T00:00:00.000000Z", "documentable_type": "client", "status": "new", "is_signed": false, "signature_count": 0, "created_at": "2026-07-05T21:11:17.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/documents/{id}": { "get": { "operationId": "documents-show", "summary": "Retrieve a document", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentResource" } } }, "example": { "data": { "id": "01kwt1y34bxq95sfwszsk8byam", "type": "documents", "attributes": { "id": "01kwt1y34bxq95sfwszsk8byam", "name": "Master service agreement — Craft Media Inc", "description": "Signed MSA covering all engagements", "type_id": "01kwt1y1yvkxz68ye23e91m37d", "client_id": "01kwt1xszttmp3jwatej49q4qe", "path": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "file_name": "master-service-agreement-craft-media-inc.pdf", "size": 1740374, "start_date": "2025-01-01T00:00:00.000000Z", "documentable_type": "client", "status": "new", "is_signed": false, "signature_count": 0, "created_at": "2026-07-05T21:11:17.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "documents-update", "summary": "Update a document", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable title of the document (e.g. \"Employment Contract\", \"ID Card\"). Required when creating a document.", "type": "string" }, "description": { "description": "Optional free-text note describing the document or its purpose.", "type": "string" }, "content": { "description": "Optional HTML body of the document, used for documents generated from a template rather than an uploaded file; can be converted to a Word/PDF file on demand.", "type": "string" }, "type_id": { "description": "Required ULID foreign key to a document_types record (managed by the document-types repository) that classifies this document, e.g. contract, ID, certificate.", "type": "string" }, "employee_id": { "description": "Optional ULID foreign key to the employee (employees repository) this document belongs to; if omitted on write it defaults to the current user's own employee unless they manage documents.", "type": "string" }, "client_id": { "description": "Optional ULID foreign key to the client (clients repository) this document belongs to; used for client-owned documents instead of employee-owned ones.", "type": "string" }, "path": { "description": "The uploaded file itself: send the raw file or a base64-encoded string when creating a document. Allowed types are pptx, pdf, docx, doc, txt, csv, rtf, jpg, jpeg, png, svg, gif, bmp, xls, xlsx, ppt (max 20MB). On read it resolves to a temporary download URL.", "type": "string" }, "file_name": { "description": "The original name of the uploaded file including its extension (e.g. \"contract.pdf\"). Send this alongside \"path\" when uploading.", "type": "string" }, "start_date": { "description": "Optional validity start date of the document (ISO 8601 / Y-m-d datetime).", "type": "string" }, "end_date": { "description": "Optional validity/expiry end date (ISO 8601 / Y-m-d datetime); when set the system can send expiration reminders to the owner.", "type": "string" }, "status": { "description": "Read-only lifecycle status of the document (currently always \"new\").", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "documents-destroy", "summary": "Delete a document", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents/{id}/actions": { "post": { "operationId": "documents-record-actions", "summary": "Actions: sign, share-document, signatures, ...", "description": "Perform an action on a single document. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`sign`** - Applies an e-signature to a single PDF document and embeds it into the file, creating a document_signatures record and returning a temporary URL to the newly signed PDF. Provide either \"signature_id\" (an existing saved signature belonging to the current user) or \"signature_data\" (a base64 signature image); \"page\" (1-based), \"position_x\", \"position_y\", \"width\" and \"height\" locate the signature on the page; \"signer_email\" and \"signer_name\" are required and identify the signer; set \"save_signature\" true to store the drawn signature for reuse. Call this when a user wants to sign a document.\n- **`share-document`** - Generates a public shareable signing link for a single PDF document so an external recipient can sign it. Requires the manage-documents permission and the document must be a PDF. Provide the recipient \"email\"; the action creates a shareable token and returns a frontend \"/share/sign/{token}\" URL to send them. Use this to request a signature from someone outside the workspace.\n- **`signatures`** - Lists all e-signatures recorded on a single document, newest first, with a total count. For each signature it returns its id, the page and position/size (position_x, position_y, width, height) where it was placed, the signed_at timestamp, the signer user (id, name, email), and a temporary URL to the signature image. Read-only. Use this to inspect who signed a document and where.\n- **`pdf-dimensions`** - Returns the pixel width and height of each page of a single PDF document. Read-only and only valid for PDF documents (returns an error otherwise). Use this to compute where a signature should be placed on a page before calling the sign action.\n- **`convert-in-word`** - Converts a document's HTML \"content\" into a downloadable Word (.docx) file and streams it back. Applies to documents that carry HTML content (typically generated from a template) rather than an uploaded binary file. Use this when a user wants to export a generated document to Word.\n- **`download-all-documents`** - Bundles all of an employee's documents into a ZIP archive and emails it, dispatched as a background job (nothing is returned inline besides a confirmation message). This is a standalone action not tied to a single document. Optional payload: \"employee_id\" (ULID of the target employee, defaults to the current employee), \"email\" (recipient, defaults to that employee's email), and \"archive_name\". Requires the manage-download-all-documents permission. Use this when a user asks to export or download all of an employee's files at once.\n- **`create-upload-url`** - Start a large-file upload for an employee document without sending the bytes through the model. This is step 1 of a 3-step flow: (1) call this action with file_name and type_id (optionally employee_id, client_id, name, start_date, end_date) to receive an upload_url and upload_token; (2) PUT the raw file bytes to upload_url exactly once (method PUT, using the returned headers); send a Content-Type header matching the file (e.g. application/pdf) so it is recorded on the stored object, though the server sniffs the real mime from the stored bytes regardless of what you send; (3) call the finalize-upload action with the upload_token to create the document. Only office/document/image types are accepted and the file must be 20 MB or smaller. Optionally pass sha256 and size so finalize can verify the stored bytes.\n- **`finalize-upload`** - Finalize a pre-signed employee document upload: pass the upload_token returned by create-upload-url after you have PUT the file bytes to the upload_url. Creates and returns the document.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "sign", "share-document", "signatures", "pdf-dimensions", "convert-in-word", "download-all-documents", "create-upload-url", "finalize-upload" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "sign", "type": "object", "properties": {} }, { "title": "share-document", "type": "object", "properties": {} }, { "title": "signatures", "type": "object", "properties": {} }, { "title": "pdf-dimensions", "type": "object", "properties": {} }, { "title": "convert-in-word", "type": "object", "properties": {} }, { "title": "download-all-documents", "type": "object", "properties": {} }, { "title": "create-upload-url", "type": "object", "properties": { "file_name": { "description": "Maximum length: 255 characters", "maxLength": 255, "type": "string" }, "type_id": { "description": "Must exist in the database", "type": "string" }, "employee_id": { "description": "Must exist in the database", "type": "string" }, "client_id": { "description": "Must exist in the database", "type": "string" }, "name": { "type": "string" }, "start_date": { "description": "This field is optional", "type": "string" }, "end_date": { "description": "This field is optional", "type": "string" }, "sha256": { "description": "This field is optional", "type": "string" }, "size": { "description": "Maximum value: 20971520", "minimum": 1, "maximum": 20971520, "type": "integer" } } }, { "title": "finalize-upload", "type": "object", "properties": { "upload_token": { "description": "This field is required", "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/document-types": { "get": { "operationId": "document-types-index", "summary": "List document types", "description": "Document types are the tenant-scoped catalog of categories used to classify documents in Growee (rows in the document_types table), such as \"Employment Contract\", \"NDA\" or \"Payslip\". Each document type is soft-deletable and has many documents attached to it via the type_id foreign key. Use this repository to list or search the available document-type categories when generating, uploading, or organizing documents, and to know which categories are currently in use.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of document-types per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter document-types by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the document-types. Available options: document_types.id (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter document-types resource. Description: This is a exact match for id (e.g., id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTypeResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 7, "path": "https://demo.growee.test/api/restify/document-types", "per_page": 1, "to": 1, "total": 7 }, "links": { "first": "https://demo.growee.test/api/restify/document-types?page=1", "next": "https://demo.growee.test/api/restify/document-types?page=2", "path": "https://demo.growee.test/api/restify/document-types", "prev": null, "filters": "/api/restify/document-types/filters" }, "data": [ { "id": "01kwt1y1yvkxz68ye23e91m37d", "type": "document_types", "attributes": { "id": "01kwt1y1yvkxz68ye23e91m37d", "name": "Client Agreement", "description": "Master service agreements and client contracts", "is_used": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "document-types-store", "summary": "Create a document type", "tags": [ "Documents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the document category, e.g. \"Employment Contract\", \"NDA\" or \"Payslip\". Required free-text string, unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional longer free-text explanation of what this document category is used for. Nullable.", "type": "string" } }, "required": [ "name" ] }, "example": { "name": "Client Agreement", "description": "Master service agreements and client contracts" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentTypeResource" } } }, "example": { "data": { "id": "01kwt1y1yvkxz68ye23e91m37d", "type": "document_types", "attributes": { "id": "01kwt1y1yvkxz68ye23e91m37d", "name": "Client Agreement", "description": "Master service agreements and client contracts", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/document-types/{id}": { "get": { "operationId": "document-types-show", "summary": "Retrieve a document type", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document type ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document type detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentTypeResource" } } }, "example": { "data": { "id": "01kwt1y1yvkxz68ye23e91m37d", "type": "document_types", "attributes": { "id": "01kwt1y1yvkxz68ye23e91m37d", "name": "Client Agreement", "description": "Master service agreements and client contracts", "is_used": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "document-types-update", "summary": "Update a document type", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document type ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name of the document category, e.g. \"Employment Contract\", \"NDA\" or \"Payslip\". Required free-text string, unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional longer free-text explanation of what this document category is used for. Nullable.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentTypeResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "document-types-destroy", "summary": "Delete a document type", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The document type ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/evaluations": { "get": { "operationId": "evaluations-index", "summary": "List evaluations", "description": "Evaluations are the performance-review records of Growee employees (rows in the evaluations table). Each evaluation belongs to one employee and one evaluation type, was created by a user, and captures the review date, next-review date, salary before/requested/after with currency, optional notes, an optional attached file, and career progression via position-before/after and level-before/after references. Visibility is scoped: users with manageEvaluations see all, managers see their direct reports, and everyone else sees only their own. Use this repository to list an employee's review history, track salary and promotion changes over time, or find upcoming evaluations; the evaluation type comes from EvaluationTypeRepository and levels from LevelRepository.", "tags": [ "Performance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of evaluations per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- type (fields: description, id, is_used, name)\n- positionBefore (fields: department_id, description, id, is_used, name)\n- positionAfter (fields: department_id, description, id, is_used, name)\n- levelBefore (fields: created_at, description, id, is_used, name)\n- levelAfter (fields: created_at, description, id, is_used, name)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,creator (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],creator[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],creator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter evaluations by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the evaluations. Available options: type, employee, positionBefore, positionAfter, evaluated_at, next_evaluation_at, salary_before, salary_after (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "evaluated_at", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a range match for evaluated_at (e.g., evaluated_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -evaluated_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "next_evaluation_at", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a range match for next_evaluation_at (e.g., next_evaluation_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -next_evaluation_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type_id", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a exact match for type_id (e.g., type_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "employee_name", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a exact match for employee_name (e.g., employee_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type_name", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a exact match for type_name (e.g., type_name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type_name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "assignees", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a exact match for assignees (e.g., assignees=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -assignees=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "active_employee", "in": "query", "required": false, "description": "Filter evaluations resource. Description: This is a exact match for active_employee (e.g., active_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -active_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 56, "path": "https://demo.growee.test/api/restify/evaluations", "per_page": 1, "to": 1, "total": 56 }, "links": { "first": "https://demo.growee.test/api/restify/evaluations?page=1", "next": "https://demo.growee.test/api/restify/evaluations?page=2", "path": "https://demo.growee.test/api/restify/evaluations", "prev": null, "filters": "/api/restify/evaluations/filters" }, "data": [ { "id": "01kwt1xz4f7t4vb8rcv20vsgwd", "type": "evaluations", "attributes": { "id": "01kwt1xz4f7t4vb8rcv20vsgwd", "employee_id": "01kwt1xqr8vpfzan9y457k6qbp", "type_id": "01kwt1xna4m4x9fy7ga1vyhgab", "evaluated_at": "2026-03-26T00:00:00.000000Z", "name": "Technical Evaluation", "next_evaluation_at": "2027-03-26T00:00:00.000000Z", "assignees": [ "01kwt1xngg4wdqf7x6c7s3yzy3" ], "notes": "Strong problem solving and code quality. Should get more exposure to client communication.", "position_before_id": "01kwt1xn9b4j365rmxe9gch2ez", "position_after_id": "01kwt1xn9b4j365rmxe9gch2ez" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "evaluations-store", "summary": "Create an evaluation", "tags": [ "Performance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key of the employee being evaluated (references EmployeeRepository). Required; for users without elevated permissions it is auto-resolved to the current employee.", "type": "string" }, "type_id": { "description": "ULID foreign key of the evaluation type/category (references EvaluationTypeRepository, e.g. \"Annual review\", \"Probation review\"). Required and must exist.", "type": "string" }, "evaluated_at": { "description": "Date the evaluation took place, in Y-m-d format. Required.", "type": "string" }, "name": { "description": "Optional free-text title/label for this specific evaluation. Nullable.", "type": "string" }, "notify_at": { "description": "Optional date (Y-m-d) on which a reminder about this evaluation should be sent; must be on or before evaluated_at. Nullable.", "type": "string" }, "next_evaluation_at": { "description": "Optional date (Y-m-d) scheduled for the employee's next evaluation. Used to surface upcoming reviews. Nullable.", "type": "string" }, "salary_before": { "description": "Employee's salary before this evaluation, as a numeric amount in the field \"currency\". Optional.", "maxLength": 6, "type": "string" }, "salary_request": { "description": "Salary the employee requested during the review, as a numeric amount in the field \"currency\". Optional.", "maxLength": 6, "type": "string" }, "salary_after": { "description": "Agreed salary after this evaluation, as a numeric amount in the field \"currency\". Optional.", "maxLength": 6, "type": "string" }, "currency": { "description": "Currency code (e.g. \"EUR\", \"RON\", \"USD\") that the salary_before/salary_request/salary_after amounts are expressed in.", "type": "string" }, "salary_type": { "description": "How the salary amounts are expressed, e.g. \"monthly\", \"yearly\" or \"hourly\". Free-text/enum-like string.", "type": "string" }, "external_evaluation_url": { "description": "Optional URL to an external evaluation document or form (e.g. a Google Form or shared doc) related to this review. Nullable.", "type": "string" }, "assignees": { "description": "Array of employee ULIDs assigned as evaluators/participants for this review; every id must belong to an employee in the current tenant. Optional.", "type": "array" }, "notes": { "description": "Free-text notes summarizing the evaluation discussion and outcome. Nullable.", "type": "string" }, "position_before_id": { "description": "ULID foreign key of the employee's position before the evaluation (references PositionRepository). Set together with position_after_id to record a role change/promotion. Nullable.", "type": "string" }, "position_after_id": { "description": "ULID foreign key of the employee's position after the evaluation (references PositionRepository). Nullable.", "type": "string" }, "level_before_id": { "description": "ULID foreign key of the employee's seniority level before the evaluation (references LevelRepository, e.g. \"Junior\", \"Mid\"). Nullable.", "type": "string" }, "level_after_id": { "description": "ULID foreign key of the employee's seniority level after the evaluation (references LevelRepository). Set with level_before_id to record a level change. Nullable.", "type": "string" }, "file": { "description": "Optional supporting document attached to the evaluation (uploaded to the tenant's documents disk, max 20 MB, allowed mime types only). On read it resolves to a URL to the stored file.", "maxLength": 20480, "type": "string" }, "file_name": { "description": "Original file name of the uploaded evaluation document (captured automatically from the \"file\" upload). Nullable.", "type": "string" } }, "required": [ "employee_id", "type_id", "evaluated_at" ] }, "example": { "employee_id": "01kwt1xqr8vpfzan9y457k6qbp", "type_id": "01kwt1xna4m4x9fy7ga1vyhgab", "evaluated_at": "2026-03-26T00:00:00.000000Z", "name": "Technical Evaluation", "next_evaluation_at": "2027-03-26T00:00:00.000000Z", "assignees": [ "01kwt1xngg4wdqf7x6c7s3yzy3" ], "notes": "Strong problem solving and code quality. Should get more exposure to client communication.", "position_before_id": "01kwt1xn9b4j365rmxe9gch2ez", "position_after_id": "01kwt1xn9b4j365rmxe9gch2ez" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvaluationResource" } } }, "example": { "data": { "id": "01kwt1xz4f7t4vb8rcv20vsgwd", "type": "evaluations", "attributes": { "id": "01kwt1xz4f7t4vb8rcv20vsgwd", "employee_id": "01kwt1xqr8vpfzan9y457k6qbp", "type_id": "01kwt1xna4m4x9fy7ga1vyhgab", "evaluated_at": "2026-03-26T00:00:00.000000Z", "name": "Technical Evaluation", "next_evaluation_at": "2027-03-26T00:00:00.000000Z", "assignees": [ "01kwt1xngg4wdqf7x6c7s3yzy3" ], "notes": "Strong problem solving and code quality. Should get more exposure to client communication.", "position_before_id": "01kwt1xn9b4j365rmxe9gch2ez", "position_after_id": "01kwt1xn9b4j365rmxe9gch2ez" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/evaluations/{id}": { "get": { "operationId": "evaluations-show", "summary": "Retrieve an evaluation", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The evaluation ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Evaluation detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvaluationResource" } } }, "example": { "data": { "id": "01kwt1xz4f7t4vb8rcv20vsgwd", "type": "evaluations", "attributes": { "id": "01kwt1xz4f7t4vb8rcv20vsgwd", "employee_id": "01kwt1xqr8vpfzan9y457k6qbp", "type_id": "01kwt1xna4m4x9fy7ga1vyhgab", "evaluated_at": "2026-03-26T00:00:00.000000Z", "name": "Technical Evaluation", "next_evaluation_at": "2027-03-26T00:00:00.000000Z", "assignees": [ "01kwt1xngg4wdqf7x6c7s3yzy3" ], "notes": "Strong problem solving and code quality. Should get more exposure to client communication.", "position_before_id": "01kwt1xn9b4j365rmxe9gch2ez", "position_after_id": "01kwt1xn9b4j365rmxe9gch2ez" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "evaluations-update", "summary": "Update an evaluation", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The evaluation ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key of the employee being evaluated (references EmployeeRepository). Required; for users without elevated permissions it is auto-resolved to the current employee.", "type": "string" }, "type_id": { "description": "ULID foreign key of the evaluation type/category (references EvaluationTypeRepository, e.g. \"Annual review\", \"Probation review\"). Required and must exist.", "type": "string" }, "evaluated_at": { "description": "Date the evaluation took place, in Y-m-d format. Required.", "type": "string" }, "name": { "description": "Optional free-text title/label for this specific evaluation. Nullable.", "type": "string" }, "notify_at": { "description": "Optional date (Y-m-d) on which a reminder about this evaluation should be sent; must be on or before evaluated_at. Nullable.", "type": "string" }, "next_evaluation_at": { "description": "Optional date (Y-m-d) scheduled for the employee's next evaluation. Used to surface upcoming reviews. Nullable.", "type": "string" }, "salary_before": { "description": "Employee's salary before this evaluation, as a numeric amount in the field \"currency\". Optional.", "maxLength": 6, "type": "string" }, "salary_request": { "description": "Salary the employee requested during the review, as a numeric amount in the field \"currency\". Optional.", "maxLength": 6, "type": "string" }, "salary_after": { "description": "Agreed salary after this evaluation, as a numeric amount in the field \"currency\". Optional.", "maxLength": 6, "type": "string" }, "currency": { "description": "Currency code (e.g. \"EUR\", \"RON\", \"USD\") that the salary_before/salary_request/salary_after amounts are expressed in.", "type": "string" }, "salary_type": { "description": "How the salary amounts are expressed, e.g. \"monthly\", \"yearly\" or \"hourly\". Free-text/enum-like string.", "type": "string" }, "external_evaluation_url": { "description": "Optional URL to an external evaluation document or form (e.g. a Google Form or shared doc) related to this review. Nullable.", "type": "string" }, "assignees": { "description": "Array of employee ULIDs assigned as evaluators/participants for this review; every id must belong to an employee in the current tenant. Optional.", "type": "array" }, "notes": { "description": "Free-text notes summarizing the evaluation discussion and outcome. Nullable.", "type": "string" }, "position_before_id": { "description": "ULID foreign key of the employee's position before the evaluation (references PositionRepository). Set together with position_after_id to record a role change/promotion. Nullable.", "type": "string" }, "position_after_id": { "description": "ULID foreign key of the employee's position after the evaluation (references PositionRepository). Nullable.", "type": "string" }, "level_before_id": { "description": "ULID foreign key of the employee's seniority level before the evaluation (references LevelRepository, e.g. \"Junior\", \"Mid\"). Nullable.", "type": "string" }, "level_after_id": { "description": "ULID foreign key of the employee's seniority level after the evaluation (references LevelRepository). Set with level_before_id to record a level change. Nullable.", "type": "string" }, "file": { "description": "Optional supporting document attached to the evaluation (uploaded to the tenant's documents disk, max 20 MB, allowed mime types only). On read it resolves to a URL to the stored file.", "type": "string" }, "file_name": { "description": "Original file name of the uploaded evaluation document (captured automatically from the \"file\" upload). Nullable.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvaluationResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "evaluations-destroy", "summary": "Delete an evaluation", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The evaluation ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/evaluations/getters/performance-analytics": { "get": { "operationId": "evaluations-getter-performance-analytics", "summary": "Performance analytics", "description": "", "tags": [ "People Reports" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/goals": { "get": { "operationId": "goals-index", "summary": "List goals", "description": "Manages employee goals and OKR-style objectives in Growee (the \"goals\" table): the targets an employee is working toward, with tracked progress. Each row belongs to one employee (employee_id), records who created/last-updated it, and stores a name, description, due date, numeric progress, a milestones checklist, and enum-backed priority, category, and progress_status, plus an optional attached file. Use this to list, search (by employee/name/description), filter (by category, priority, progress_status, due_date), sort, or update objectives. It complements Feedback: goals track forward-looking targets, while feedback captures reviews and ad-hoc notes. Visibility is scoped — non-managers see only their own goals (and their direct reports' goals if they manage those).", "tags": [ "Performance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of goals per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter goals by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the goals. Available options: progress, name, due_date, category, progress_status, priority (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a exact match for name (e.g., name=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -name=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "due_date", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a range match for due_date (e.g., due_date=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -due_date=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a range match for created_at (e.g., created_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -created_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a exact match for category (e.g., category=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -category=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "progress_status", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a exact match for progress_status (e.g., progress_status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -progress_status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a exact match for priority (e.g., priority=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -priority=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "active_employee", "in": "query", "required": false, "description": "Filter goals resource. Description: This is a exact match for active_employee (e.g., active_employee=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -active_employee=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoalResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 25, "path": "https://demo.growee.test/api/restify/goals", "per_page": 1, "to": 1, "total": 25 }, "links": { "first": "https://demo.growee.test/api/restify/goals?page=1", "next": "https://demo.growee.test/api/restify/goals?page=2", "path": "https://demo.growee.test/api/restify/goals", "prev": null, "filters": "/api/restify/goals/filters" }, "data": [ { "id": "01kwt1y1ttdz14ry3wf0rz1hbk", "type": "goals", "attributes": { "id": "01kwt1y1ttdz14ry3wf0rz1hbk", "employee_id": "01kwt1xrth7xtnjdrtbfs02795", "created_by_employee_id": "01kwt1xnm6ykcmhbar2x1haa7t", "progress": 31, "name": "Mentor a junior colleague", "description": "Run weekly pairing sessions and track progress", "due_date": "2026-07-11T00:00:00.000000Z", "priority": "medium", "progress_status": "in progress", "category": "long term", "created_at": "2026-07-05T21:11:16.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "goals-store", "summary": "Create a goal", "tags": [ "Performance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) who owns this goal. Defaults to the current employee unless the caller manages goals or the goals of direct reports.", "type": "string" }, "progress": { "description": "Completion percentage of the goal as a number, typically 0 to 100. Null means progress has not been recorded.", "type": "number" }, "milestones": { "description": "JSON array of milestone items (sub-steps toward the goal), each typically holding a label and completion state. May be null or empty.", "type": "array" }, "name": { "description": "Short title of the goal (e.g. \"Ship v2 onboarding flow\"). Required when creating, max 255 characters.", "maxLength": 255, "type": "string" }, "description": { "description": "Optional longer explanation of the goal, its context and success criteria. Free text up to 65535 characters.", "maxLength": 65535, "type": "string" }, "due_date": { "description": "Target date by which the goal should be achieved, as a date (YYYY-MM-DD). Required when creating.", "type": "string" }, "priority": { "description": "Importance of the goal. Allowed values: \"low\", \"medium\", \"high\". Required when creating.", "enum": [ "low", "medium", "high" ], "type": "string" }, "progress_status": { "description": "Lifecycle state of the goal. Allowed values: \"not started\", \"in progress\", \"completed\". May be null.", "enum": [ "not started", "in progress", "completed" ], "type": "string" }, "category": { "description": "Time-horizon classification of the goal. Allowed values: \"short term\", \"long term\". May be null.", "enum": [ "short term", "long term" ], "type": "string" }, "path": { "description": "Optional supporting file attached to the goal (uploaded to S3). On read this resolves to a temporary download URL valid for 30 minutes; the original filename is stored in file_name.", "type": "string" } }, "required": [ "name", "due_date", "priority" ] }, "example": { "employee_id": "01kwt1xrth7xtnjdrtbfs02795", "progress": 31, "name": "Mentor a junior colleague", "description": "Run weekly pairing sessions and track progress", "due_date": "2026-07-11T00:00:00.000000Z", "priority": "medium", "progress_status": "in progress", "category": "long term" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GoalResource" } } }, "example": { "data": { "id": "01kwt1y1ttdz14ry3wf0rz1hbk", "type": "goals", "attributes": { "id": "01kwt1y1ttdz14ry3wf0rz1hbk", "employee_id": "01kwt1xrth7xtnjdrtbfs02795", "created_by_employee_id": "01kwt1xnm6ykcmhbar2x1haa7t", "progress": 31, "name": "Mentor a junior colleague", "description": "Run weekly pairing sessions and track progress", "due_date": "2026-07-11T00:00:00.000000Z", "priority": "medium", "progress_status": "in progress", "category": "long term", "created_at": "2026-07-05T21:11:16.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/goals/{id}": { "get": { "operationId": "goals-show", "summary": "Retrieve a goal", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The goal ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Goal detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GoalResource" } } }, "example": { "data": { "id": "01kwt1y1ttdz14ry3wf0rz1hbk", "type": "goals", "attributes": { "id": "01kwt1y1ttdz14ry3wf0rz1hbk", "employee_id": "01kwt1xrth7xtnjdrtbfs02795", "created_by_employee_id": "01kwt1xnm6ykcmhbar2x1haa7t", "progress": 31, "name": "Mentor a junior colleague", "description": "Run weekly pairing sessions and track progress", "due_date": "2026-07-11T00:00:00.000000Z", "priority": "medium", "progress_status": "in progress", "category": "long term", "created_at": "2026-07-05T21:11:16.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "goals-update", "summary": "Update a goal", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The goal ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) who owns this goal. Defaults to the current employee unless the caller manages goals or the goals of direct reports.", "type": "string" }, "progress": { "description": "Completion percentage of the goal as a number, typically 0 to 100. Null means progress has not been recorded.", "type": "number" }, "milestones": { "description": "JSON array of milestone items (sub-steps toward the goal), each typically holding a label and completion state. May be null or empty.", "type": "array" }, "name": { "description": "Short title of the goal (e.g. \"Ship v2 onboarding flow\"). Required when creating, max 255 characters.", "type": "string" }, "description": { "description": "Optional longer explanation of the goal, its context and success criteria. Free text up to 65535 characters.", "maxLength": 65535, "type": "string" }, "due_date": { "description": "Target date by which the goal should be achieved, as a date (YYYY-MM-DD). Required when creating.", "type": "string" }, "priority": { "description": "Importance of the goal. Allowed values: \"low\", \"medium\", \"high\". Required when creating.", "type": "string" }, "progress_status": { "description": "Lifecycle state of the goal. Allowed values: \"not started\", \"in progress\", \"completed\". May be null.", "enum": [ "not started", "in progress", "completed" ], "type": "string" }, "category": { "description": "Time-horizon classification of the goal. Allowed values: \"short term\", \"long term\". May be null.", "enum": [ "short term", "long term" ], "type": "string" }, "path": { "description": "Optional supporting file attached to the goal (uploaded to S3). On read this resolves to a temporary download URL valid for 30 minutes; the original filename is stored in file_name.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GoalResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "goals-destroy", "summary": "Delete a goal", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The goal ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/feedback": { "get": { "operationId": "feedback-index", "summary": "List feedback", "description": "Manages feedback records in Growee (the \"feedback\" table): notes captured about an employee or a client, such as 1:1 summaries, praise, or coaching feedback. Each row polymorphically targets a subject via feedbackable_type + feedbackable_id, and stores a type label, the given_at date, free-text notes, optional file/audio attachments (with transcription), and a flag for whether the assessed employee may see it. It may also link to a 360 feedback cycle via feedback_request_id. Use this to list, search (by type/notes), filter, or create feedback; it complements Goals (objectives) by holding lighter, ad-hoc feedback. Non-managers only see feedback explicitly shared with them about themselves.", "tags": [ "Performance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of feedback per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- employeeCreator (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- feedbackable (fields: id)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=creator,employeeCreator (include all fields)\n- include=creator[archived_at,avatar] (selective fields with comma syntax)\n- include=creator[archived_at|avatar] (selective fields with pipe syntax)\n- include=creator.posts (nested relationship - all fields)\n- include=creator[name].posts[title] (nested with field selection at each level)\n- include=creator[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=creator.posts[title],creator.comments[body] (multiple nested from same parent)\n- include=creator[name],employeeCreator[id] (multiple relationships with field selection)\n- include=creator[email|name].posts[title],employeeCreator[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter feedback by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the feedback. Available options: type, given_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "given_at", "in": "query", "required": false, "description": "Filter feedback resource. Description: This is a range match for given_at (e.g., given_at=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -given_at=value1,value2). Accepted values can be any.", "schema": { "type": "string" } }, { "name": "created_by_employee_id", "in": "query", "required": false, "description": "Filter feedback resource. Description: This is a exact match for created_by_employee_id (e.g., created_by_employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -created_by_employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "feedbackable_id", "in": "query", "required": false, "description": "Filter feedback resource. Description: This is a exact match for feedbackable_id (e.g., feedbackable_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -feedbackable_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "feedbackable_type", "in": "query", "required": false, "description": "Filter feedback resource. Description: This is a exact match for feedbackable_type (e.g., feedbackable_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -feedbackable_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter feedback resource. Description: This is a exact match for type (e.g., type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 15, "path": "https://demo.growee.test/api/restify/feedback", "per_page": 1, "to": 1, "total": 15 }, "links": { "first": "https://demo.growee.test/api/restify/feedback?page=1", "next": "https://demo.growee.test/api/restify/feedback?page=2", "path": "https://demo.growee.test/api/restify/feedback", "prev": null, "filters": "/api/restify/feedback/filters" }, "data": [ { "id": "01kwt1y1yjxcfb7gr5pjyam19d", "type": "feedback", "attributes": { "id": "01kwt1y1yjxcfb7gr5pjyam19d", "created_by_employee_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "feedbackable_type": "employee", "feedbackable_id": "01kwt1xnvkjg93yxthp73ngqza", "type": "General Feedback", "given_at": "2026-05-14T00:00:00.000000Z", "notes": "Communicates clearly with the client and keeps the team in the loop.", "is_visible_to_employee": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "feedback-store", "summary": "Create a feedback", "tags": [ "Performance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedbackable_type": { "description": "Polymorphic subject type this feedback is about: \"employee\" or \"client\".", "type": "string" }, "feedbackable_id": { "description": "ULID of the subject the feedback is about — an Employee or a Client depending on feedbackable_type.", "maxLength": 26, "type": "string" }, "type": { "description": "Free-text label categorising the feedback interaction, e.g. \"1:1\", \"feedback\", \"review\".", "type": "string" }, "given_at": { "description": "Date the feedback was given/recorded (YYYY-MM-DD).", "type": "string" }, "notes": { "description": "The written content of the feedback.", "type": "string" } }, "required": [ "feedbackable_type", "feedbackable_id", "type", "given_at", "notes" ] }, "example": { "feedbackable_type": "employee", "feedbackable_id": "01kwt1xnvkjg93yxthp73ngqza", "type": "General Feedback", "given_at": "2026-05-14T00:00:00.000000Z", "notes": "Communicates clearly with the client and keeps the team in the loop." } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeedbackResource" } } }, "example": { "data": { "id": "01kwt1y1yjxcfb7gr5pjyam19d", "type": "feedback", "attributes": { "id": "01kwt1y1yjxcfb7gr5pjyam19d", "created_by_employee_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "feedbackable_type": "employee", "feedbackable_id": "01kwt1xnvkjg93yxthp73ngqza", "type": "General Feedback", "given_at": "2026-05-14T00:00:00.000000Z", "notes": "Communicates clearly with the client and keeps the team in the loop.", "is_visible_to_employee": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/feedback/{id}": { "get": { "operationId": "feedback-show", "summary": "Retrieve a feedback", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The feedback ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feedback detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeedbackResource" } } }, "example": { "data": { "id": "01kwt1y1yjxcfb7gr5pjyam19d", "type": "feedback", "attributes": { "id": "01kwt1y1yjxcfb7gr5pjyam19d", "created_by_employee_id": "01kwt1xngg4wdqf7x6c7s3yzy3", "feedbackable_type": "employee", "feedbackable_id": "01kwt1xnvkjg93yxthp73ngqza", "type": "General Feedback", "given_at": "2026-05-14T00:00:00.000000Z", "notes": "Communicates clearly with the client and keeps the team in the loop.", "is_visible_to_employee": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "feedback-update", "summary": "Update a feedback", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The feedback ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Free-text label categorising the feedback interaction, e.g. \"1:1\", \"feedback\", \"review\".", "type": "string" }, "given_at": { "description": "Date the feedback was given/recorded (YYYY-MM-DD).", "type": "string" }, "notes": { "description": "The written content of the feedback.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeedbackResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "feedback-destroy", "summary": "Delete a feedback", "tags": [ "Performance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The feedback ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/assets": { "get": { "operationId": "assets-index", "summary": "List assets", "description": "Manages the company asset inventory (the assets table), tenant-scoped records of equipment and items the company owns and assigns to employees. Each asset tracks its type and lifecycle status, optional assignment to an employee (employee relationship) plus who assigned it (assigner), purchase/acquisition details, and free-text notes. Use this repository to list, search (name/model/serial_number/supplier), and inspect assets; lifecycle changes go through the mark-as-lost, mark-as-decommissioned, and mark-as-maintenance actions rather than raw status edits.", "tags": [ "Assets" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of assets per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- employee (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n- assigner (fields: about, address, avatar, avatar_name, billed_rate, birth_date, company_address, company_identifier, company_name, company_position, company_vat, contract_bank_account, contract_bank_name, contract_bank_swift, contract_type, custom_fields, default_signature_id, direction_id, email, first_name, gender, general_information, identity_card_number, initial_vacation_balance, internal_cost_hourly_rate, internal_cost_monthly_rate, internal_cost_type, invite_immediately, last_name, level_id, manager_employee_id, name, personal_email, personal_identification_number, phone, position_code, position_id, quote, role_id, salary, salary_currency, salary_evaluation_assignees, salary_type, sensitive_information, start_date, status, technical_evaluation_assignees, termination_date, timezone, weekly_hours_capacity, work_location_ids)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=employee,assigner (include all fields)\n- include=employee[about,address] (selective fields with comma syntax)\n- include=employee[about|address] (selective fields with pipe syntax)\n- include=employee.posts (nested relationship - all fields)\n- include=employee[name].posts[title] (nested with field selection at each level)\n- include=employee[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=employee.posts[title],employee.comments[body] (multiple nested from same parent)\n- include=employee[name],assigner[id] (multiple relationships with field selection)\n- include=employee[email|name].posts[title],assigner[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter assets by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the assets. Available options: id, name, type, model, status, acquisition_date, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Filter assets resource. Description: This is a exact match for employee_id (e.g., employee_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -employee_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter assets resource. Description: This is a exact match for type (e.g., type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter assets resource. Description: This is a exact match for status (e.g., status=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -status=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "acquisition_date", "in": "query", "required": false, "description": "Filter assets resource. Description: This is a date match for acquisition_date (e.g., acquisition_date=YYYY-MM-DD or acquisition_date=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -acquisition_date=YYYY-MM-DD or -acquisition_date=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "assigned_at", "in": "query", "required": false, "description": "Filter assets resource. Description: This is a date match for assigned_at (e.g., assigned_at=YYYY-MM-DD or assigned_at=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -assigned_at=YYYY-MM-DD or -assigned_at=value1,value2 for range). Accepted values are date.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 10, "path": "https://demo.growee.test/api/restify/assets", "per_page": 1, "to": 1, "total": 10 }, "links": { "first": "https://demo.growee.test/api/restify/assets?page=1", "next": "https://demo.growee.test/api/restify/assets?page=2", "path": "https://demo.growee.test/api/restify/assets", "prev": null, "filters": "/api/restify/assets/filters" }, "data": [ { "id": "01kwt1y3hxchwqt49xf1mgxz93", "type": "assets", "attributes": { "name": "MacBook Pro 14\" M3", "type": "electronic", "model": "A2918", "serial_number": "BDG-699985", "supplier": "eMAG Business", "acquisition_date": "2025-02-05T00:00:00.000000Z", "purchase_value": "2344.63", "currency": "EUR", "status": "available", "is_demo": true } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "assets-store", "summary": "Create an asset", "tags": [ "Assets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) this asset is currently assigned to, or null if unassigned/in stock. Must reference an existing employee.", "type": "string" }, "name": { "description": "Human-readable label for the asset, e.g. \"MacBook Pro 16 (2023)\". Required string up to 255 characters.", "maxLength": 255, "type": "string" }, "type": { "description": "The asset category; one of: electronic, furniture, book, office, software, subscription, other. Required.", "enum": [ "electronic", "furniture", "book", "office", "software", "subscription", "other" ], "type": "string" }, "model": { "description": "Optional manufacturer model name/number of the asset, e.g. \"A2780\". Nullable string up to 255 characters.", "maxLength": 255, "type": "string" }, "serial_number": { "description": "Optional unique serial number of the physical asset for identification/warranty. Nullable string up to 255 characters.", "maxLength": 255, "type": "string" }, "supplier": { "description": "Optional name of the vendor/supplier the asset was purchased from. Nullable string up to 255 characters.", "maxLength": 255, "type": "string" }, "acquisition_date": { "description": "Optional date (date only, no time) the asset was acquired/purchased. Nullable, format YYYY-MM-DD.", "type": "string" }, "purchase_value": { "description": "Optional purchase cost of the asset as a decimal amount (2 decimal places) in the field-defined currency. Nullable, must be >= 0.", "minimum": 0, "type": "string" }, "currency": { "description": "ISO 4217 3-letter currency code for purchase_value, e.g. \"RON\", \"EUR\", \"USD\". Required, defaults to \"RON\".", "minLength": 3, "maxLength": 3, "type": "string" }, "notes": { "description": "Optional free-text notes about the asset (condition, history, maintenance log). Nullable string.", "type": "string" }, "status": { "description": "The asset lifecycle status; one of: available, in_use, maintenance, decommissioned, lost. Required. Prefer the mark-as-* actions for transitions to lost/decommissioned/maintenance.", "enum": [ "available", "in_use", "maintenance", "decommissioned", "lost" ], "type": "string" }, "is_demo": { "description": "Boolean flag; true marks the asset as demo/sample seed data rather than a real company asset. Defaults to false and is only visible to users with the manage-employees permission.", "type": "boolean" } }, "required": [ "name", "type", "currency", "status" ] }, "example": { "name": "MacBook Pro 14\" M3", "type": "electronic", "model": "A2918", "serial_number": "BDG-699985", "supplier": "eMAG Business", "acquisition_date": "2025-02-05T00:00:00.000000Z", "purchase_value": "2344.63", "currency": "EUR", "status": "available", "is_demo": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssetResource" } } }, "example": { "data": { "id": "01kwt1y3hxchwqt49xf1mgxz93", "type": "assets", "attributes": { "name": "MacBook Pro 14\" M3", "type": "electronic", "model": "A2918", "serial_number": "BDG-699985", "supplier": "eMAG Business", "acquisition_date": "2025-02-05T00:00:00.000000Z", "purchase_value": "2344.63", "currency": "EUR", "status": "available", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/assets/{id}": { "get": { "operationId": "assets-show", "summary": "Retrieve an asset", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The asset ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssetResource" } } }, "example": { "data": { "id": "01kwt1y3hxchwqt49xf1mgxz93", "type": "assets", "attributes": { "name": "MacBook Pro 14\" M3", "type": "electronic", "model": "A2918", "serial_number": "BDG-699985", "supplier": "eMAG Business", "acquisition_date": "2025-02-05T00:00:00.000000Z", "purchase_value": "2344.63", "currency": "EUR", "status": "available", "is_demo": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "assets-update", "summary": "Update an asset", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The asset ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) this asset is currently assigned to, or null if unassigned/in stock. Must reference an existing employee.", "type": "string" }, "name": { "description": "Human-readable label for the asset, e.g. \"MacBook Pro 16 (2023)\". Required string up to 255 characters.", "maxLength": 255, "type": "string" }, "type": { "description": "The asset category; one of: electronic, furniture, book, office, software, subscription, other. Required.", "enum": [ "electronic", "furniture", "book", "office", "software", "subscription", "other" ], "type": "string" }, "model": { "description": "Optional manufacturer model name/number of the asset, e.g. \"A2780\". Nullable string up to 255 characters.", "maxLength": 255, "type": "string" }, "serial_number": { "description": "Optional unique serial number of the physical asset for identification/warranty. Nullable string up to 255 characters.", "maxLength": 255, "type": "string" }, "supplier": { "description": "Optional name of the vendor/supplier the asset was purchased from. Nullable string up to 255 characters.", "maxLength": 255, "type": "string" }, "acquisition_date": { "description": "Optional date (date only, no time) the asset was acquired/purchased. Nullable, format YYYY-MM-DD.", "type": "string" }, "purchase_value": { "description": "Optional purchase cost of the asset as a decimal amount (2 decimal places) in the field-defined currency. Nullable, must be >= 0.", "minimum": 0, "type": "string" }, "currency": { "description": "ISO 4217 3-letter currency code for purchase_value, e.g. \"RON\", \"EUR\", \"USD\". Required, defaults to \"RON\".", "minLength": 3, "maxLength": 3, "type": "string" }, "notes": { "description": "Optional free-text notes about the asset (condition, history, maintenance log). Nullable string.", "type": "string" }, "status": { "description": "The asset lifecycle status; one of: available, in_use, maintenance, decommissioned, lost. Required. Prefer the mark-as-* actions for transitions to lost/decommissioned/maintenance.", "enum": [ "available", "in_use", "maintenance", "decommissioned", "lost" ], "type": "string" }, "is_demo": { "description": "Boolean flag; true marks the asset as demo/sample seed data rather than a real company asset. Defaults to false and is only visible to users with the manage-employees permission.", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssetResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "assets-destroy", "summary": "Delete an asset", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The asset ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/assets/{id}/actions": { "post": { "operationId": "assets-record-actions", "summary": "Actions: mark-asset-as-lost-restify-action, mark-asset-as-decommissioned-restify-action, mark-asset-as-maintenance-restify-action", "description": "Perform an action on a single asset. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`mark-asset-as-lost-restify-action`** - Marks a company asset as lost by setting its status to \"lost\". Takes no payload beyond the target asset. Use this when equipment can no longer be located or has been reported missing. Requires the markAsLost authorization on the asset; returns 403 if not permitted.\n- **`mark-asset-as-decommissioned-restify-action`** - Marks a company asset as decommissioned (retired from service) by setting its status to \"decommissioned\" and clearing its employee assignment (employee_id set to null). Takes no payload beyond the target asset. Use this when equipment is permanently taken out of use. Requires the markAsDecommissioned authorization on the asset; returns 403 if not permitted.\n- **`mark-asset-as-maintenance-restify-action`** - Sends a company asset for maintenance by setting its status to \"maintenance\" and appending a dated maintenance note to the asset. Accepts optional payload keys: \"notes\" (free-text description of the maintenance) and \"expected_return_date\" (a date that must be after today). Use this when equipment is temporarily out of service for repair/servicing. Requires the markAsUnderMaintenance authorization on the asset; returns 403 if not permitted.", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The asset ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "mark-asset-as-lost-restify-action", "mark-asset-as-decommissioned-restify-action", "mark-asset-as-maintenance-restify-action" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "mark-asset-as-lost-restify-action", "type": "object", "properties": {} }, { "title": "mark-asset-as-decommissioned-restify-action", "type": "object", "properties": {} }, { "title": "mark-asset-as-maintenance-restify-action", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/kb-pages": { "get": { "operationId": "kb-pages-index", "summary": "List kb pages", "description": "Knowledge base pages: rich, Notion-style documents that live inside knowledge-base teamspaces (see the kb-teamspaces repository) and are stored in the kb_pages table. Each page belongs to exactly one teamspace, can be nested under a parent page to form an infinitely deep tree, and carries a JSON block-based body plus title, icon and optional cover image. Pages can be regular documents or reusable templates (is_template=true, grouped by template_category such as hr/product/engineering/sales); the CreateKbPageFromTemplate action clones a template into a new page. Visibility is layered: the teamspace can be private or workspace-wide, and each page has its own access_level (restricted / workspace / anyone_with_link / published) plus per-user shares (see the kb-page-shares repository). Use this repository to browse, full-text and semantic search (the \"search\" getter), and walk the page hierarchy (the \"tree\" getter) so an AI agent can find and read the company documentation, playbooks, HR policies and product docs a tenant keeps in its knowledge base.", "tags": [ "Knowledge Base" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of kb-pages per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of relationships to include with optional field selection.\n\nAvailable relationships:\n- creator (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n- editor (fields: archived_at, avatar, email, first_name, has_password, id, is_tenant_owner, last_name, locale, onboarding_step, onboarding_token, status)\n\nField Selection:\nYou can specify which fields to include for each relationship using square brackets.\nSyntax: relationship[field1|field2]\n\nNested Relationships:\nYou can include deeply nested relationships using dot notation with field selection at each level.\nSyntax: relationship[fields].nested[fields].deeper[fields] - supports unlimited nesting depth\nNote: Field selection works at every nesting level independently.\n\nExamples:\n- include=creator,editor (include all fields)\n- include=creator[archived_at,avatar] (selective fields with comma syntax)\n- include=creator[archived_at|avatar] (selective fields with pipe syntax)\n- include=creator.posts (nested relationship - all fields)\n- include=creator[name].posts[title] (nested with field selection at each level)\n- include=creator[name|email].posts[title].tags[id] (deep nesting - 3 levels with field selection)\n- include=creator.posts[title],creator.comments[body] (multiple nested from same parent)\n- include=creator[name],editor[id] (multiple relationships with field selection)\n- include=creator[email|name].posts[title],editor[id] (mixing deep nested and simple relationships)", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter kb-pages by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the kb-pages. Available options: position, title, created_at, updated_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "teamspace_id", "in": "query", "required": false, "description": "Filter kb-pages resource. Description: This is a exact match for teamspace_id (e.g., teamspace_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -teamspace_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "required": false, "description": "Filter kb-pages resource. Description: This is a exact match for parent_id (e.g., parent_id=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -parent_id=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "is_template", "in": "query", "required": false, "description": "Filter kb-pages resource. Description: This is a boolean match for is_template (e.g., is_template=true or is_template=false). It accepts negation by prefixing the column with a hyphen (e.g., -is_template=true or -is_template=false). Accepted values are boolean.", "schema": { "type": "boolean" } }, { "name": "template_category", "in": "query", "required": false, "description": "Filter kb-pages resource. Description: This is a exact match for template_category (e.g., template_category=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -template_category=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbPageResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 12, "path": "https://demo.growee.test/api/restify/kb-pages", "per_page": 1, "to": 1, "total": 12 }, "links": { "first": "https://demo.growee.test/api/restify/kb-pages?page=1", "next": "https://demo.growee.test/api/restify/kb-pages?page=2", "path": "https://demo.growee.test/api/restify/kb-pages", "prev": null, "filters": "/api/restify/kb-pages/filters" }, "data": [ { "id": "01kxdn3pezncj3p5ypjh832x2g", "type": "kb_pages", "attributes": { "teamspace_id": "01kx1td9bqx527acyedn5vtjnh", "parent_id": "01kx266an7m25rcy6wjv6tw8y9", "position": 2, "title": "Untitled", "cover_position_y": 50, "is_template": false, "access_level": "workspace", "workspace_role": "edit", "slug": "page-6", "version": 1, "created_at": "2026-07-13T11:51:58.000000Z", "updated_at": "2026-07-13T11:51:58.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "kb-pages-store", "summary": "Create a kb page", "tags": [ "Knowledge Base" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "teamspace_id": { "description": "ULID foreign key to the KbTeamspace (kb-teamspaces repository) this page belongs to; every page lives in exactly one teamspace and is only settable on create.", "type": "string" }, "parent_id": { "description": "ULID foreign key to another KbPage in the same teamspace that acts as this page's parent in the tree; null means the page sits at the teamspace root.", "type": "string" }, "position": { "description": "Zero-based integer sort order of this page among its siblings under the same parent; lower numbers appear first.", "minimum": 0, "type": "integer" }, "title": { "description": "The human-readable page title (max 255 chars) shown in the sidebar and search results.", "maxLength": 255, "type": "string" }, "icon": { "description": "Optional icon shown next to the title, typically an emoji or icon identifier string (max 255 chars).", "maxLength": 255, "type": "string" }, "cover_image": { "description": "Optional URL (max 2048 chars) of the banner cover image displayed at the top of the page.", "maxLength": 2048, "type": "string" }, "cover_position_y": { "description": "Vertical focal point of the cover image as an integer percentage from 0 (top) to 100 (bottom) for cropping.", "minimum": 0, "maximum": 100, "type": "integer" }, "content": { "description": "The full page body as a JSON array of rich-text/editor blocks (headings, paragraphs, lists, embeds); this is the actual document content an agent should read to answer questions.", "type": "array" }, "is_template": { "description": "Boolean; true marks this page as a reusable template that can be cloned into new pages rather than a normal document.", "type": "boolean" }, "template_category": { "description": "For template pages, the grouping category. One of: hr, product, engineering, sales. Null for non-template pages.", "type": "string" } }, "required": [ "teamspace_id" ] }, "example": { "teamspace_id": "01kx1td9bqx527acyedn5vtjnh", "parent_id": "01kx266an7m25rcy6wjv6tw8y9", "position": 2, "title": "Untitled", "cover_position_y": 50, "is_template": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KbPageResource" } } }, "example": { "data": { "id": "01kxdn3pezncj3p5ypjh832x2g", "type": "kb_pages", "attributes": { "teamspace_id": "01kx1td9bqx527acyedn5vtjnh", "parent_id": "01kx266an7m25rcy6wjv6tw8y9", "position": 2, "title": "Untitled", "cover_position_y": 50, "is_template": false, "access_level": "workspace", "workspace_role": "edit", "slug": "page-6", "version": 1, "created_at": "2026-07-13T11:51:58.000000Z", "updated_at": "2026-07-13T11:51:58.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/kb-pages/{id}": { "get": { "operationId": "kb-pages-show", "summary": "Retrieve a kb page", "tags": [ "Knowledge Base" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kb page ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Kb page detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KbPageResource" } } }, "example": { "data": { "id": "01kxdn3pezncj3p5ypjh832x2g", "type": "kb_pages", "attributes": { "teamspace_id": "01kx1td9bqx527acyedn5vtjnh", "parent_id": "01kx266an7m25rcy6wjv6tw8y9", "position": 2, "title": "Untitled", "cover_position_y": 50, "is_template": false, "access_level": "workspace", "workspace_role": "edit", "slug": "page-6", "version": 1, "created_at": "2026-07-13T11:51:58.000000Z", "updated_at": "2026-07-13T11:51:58.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "kb-pages-update", "summary": "Update a kb page", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Knowledge Base" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kb page ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "description": "ULID foreign key to another KbPage in the same teamspace that acts as this page's parent in the tree; null means the page sits at the teamspace root.", "type": "string" }, "position": { "description": "Zero-based integer sort order of this page among its siblings under the same parent; lower numbers appear first.", "minimum": 0, "type": "integer" }, "title": { "description": "The human-readable page title (max 255 chars) shown in the sidebar and search results.", "maxLength": 255, "type": "string" }, "icon": { "description": "Optional icon shown next to the title, typically an emoji or icon identifier string (max 255 chars).", "maxLength": 255, "type": "string" }, "cover_image": { "description": "Optional URL (max 2048 chars) of the banner cover image displayed at the top of the page.", "maxLength": 2048, "type": "string" }, "cover_position_y": { "description": "Vertical focal point of the cover image as an integer percentage from 0 (top) to 100 (bottom) for cropping.", "minimum": 0, "maximum": 100, "type": "integer" }, "content": { "description": "The full page body as a JSON array of rich-text/editor blocks (headings, paragraphs, lists, embeds); this is the actual document content an agent should read to answer questions.", "type": "array" }, "is_template": { "description": "Boolean; true marks this page as a reusable template that can be cloned into new pages rather than a normal document.", "type": "boolean" }, "template_category": { "description": "For template pages, the grouping category. One of: hr, product, engineering, sales. Null for non-template pages.", "type": "string" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KbPageResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "kb-pages-destroy", "summary": "Delete a kb page", "tags": [ "Knowledge Base" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kb page ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/kb-pages/getters/tree": { "get": { "operationId": "kb-pages-getter-tree", "summary": "Tree", "description": "Returns the knowledge-base pages arranged as a nested hierarchy (each node carrying id, teamspace_id, parent_id, position, title and icon with its children), ordered by position. Payload: optional teamspace_id (ULID) to restrict the tree to a single teamspace; omit it to get the whole visible tree. Templates are excluded and the tree is scoped to pages the current user may view (managers see all). Use this to understand how a tenant's documentation is organized and to navigate the sidebar structure before drilling into a specific page.", "tags": [ "Knowledge Base" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/kb-pages/getters/search": { "get": { "operationId": "kb-pages-getter-search", "summary": "Search", "description": "Searches knowledge-base pages by combining keyword (title/text) matching with AI semantic (embedding) similarity, returning the most relevant documents for a natural-language question. Payload: query (the search string; must be at least 2 characters). Templates are excluded and results are scoped to pages the current user may view (managers see all). Returns up to 20 hits, each with id, teamspace_id, title, icon, a text snippet, and match type (\"keyword\" or \"semantic\"). This is the primary tool an AI agent should use to look up company documentation, policies or playbooks by topic before reading a specific page via show.", "tags": [ "Knowledge Base" ], "responses": { "200": { "description": "Getter payload (shape specific to this getter).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/kb-pages/{id}/actions": { "post": { "operationId": "kb-pages-record-actions", "summary": "Actions: move-page, duplicate-page, share-page, ...", "description": "Perform an action on a single kb page. Select the action with the `action` query parameter; the request body carries that action's payload.\n\n- **`move-page`** - Relocates a knowledge-base page within the tree by changing its teamspace, parent and/or sibling order. Payload (all optional): teamspace_id (ULID of a destination KbTeamspace the user may write to), parent_id (ULID of the new parent KbPage, or null to move to the teamspace root), and position (zero-based integer order among the new siblings). The caller must have edit access to the page or it is rejected with 403. Side effect: the page (and its descendant subtree) is re-parented/re-ordered. Returns the page id, teamspace_id, parent_id and position. Use this to reorganize documentation, nest a page under another, or reorder it in the sidebar.\n- **`duplicate-page`** - Creates a full copy of the target knowledge-base page (same teamspace, parent and content) as a new sibling KbPage. It runs on a single page (by id) and takes no payload. The caller must have edit access to the page or it is rejected with 403. Side effect: a new KbPage record is persisted. Returns the copy's id, teamspace_id, parent_id and title. Use this when the user wants to fork or reuse an existing document as a starting point.\n- **`share-page`** - Invites specific people to a knowledge-base page and emails them a link. Payload: invites, an array of 1 to 25 objects each with an optional user_id (existing workspace user), an optional email, and an optional role (view or edit, defaulting to view). Emails that match a workspace member become internal shares; other emails become guest shares with an anonymous share link. The caller must have edit access to the page or it is rejected with 403. Side effects: KbPageShare rows are created/updated and a \"page shared\" email is sent to each new recipient. Returns the created shares (id, user_id, email, role). Use this to grant named colleagues or external guests access to a page; use set-link-access instead for broad link/workspace/public visibility.\n- **`set-link-access`** - Sets the sharing visibility of a knowledge-base page. Payload: access_level (required, one of restricted / workspace / anyone_with_link / published) and optional workspace_role (view or edit, the default role for teamspace members when access_level is workspace). The caller must have edit access to the page or it is rejected with 403. Side effects: the page access_level/workspace_role are saved, and for anyone_with_link or published a public shareable link token is created (or reused). Returns the applied access_level, workspace_role, the share token, the tenant share URL, and (only when published and the teamspace is live) the public help-center URL. Use this to make a page public, generate a shareable link, restrict it, or open it to the whole workspace.\n- **`create-from-template`** - Creates a brand-new knowledge-base page by cloning an existing template page into a teamspace. Payload: template_id (ULID of a template KbPage the user may view), teamspace_id (ULID of the destination KbTeamspace the user may write to), and optional parent_id (ULID of a parent KbPage to nest the new page under). Side effect: a new KbPage is persisted with the template's content copied in. Returns the new page id, teamspace_id, parent_id and title. Use this when the user wants to start a document from a predefined template (e.g. an HR policy or onboarding doc) rather than from a blank page.", "tags": [ "Knowledge Base" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kb page ULID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": true, "description": "Which action to perform (see the list above for each action's behavior and payload).", "schema": { "type": "string", "enum": [ "move-page", "duplicate-page", "share-page", "set-link-access", "create-from-template" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "move-page", "type": "object", "properties": {} }, { "title": "duplicate-page", "type": "object", "properties": {} }, { "title": "share-page", "type": "object", "properties": {} }, { "title": "set-link-access", "type": "object", "properties": {} }, { "title": "create-from-template", "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Action result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/custom-field-definitions": { "get": { "operationId": "custom-field-definitions-index", "summary": "List custom field definitions", "description": "This repository manages custom field definitions (the `custom_field_definitions` table): tenant-scoped, admin-configured extra fields that extend built-in records for four entity types — CRM leads, clients, client contacts, and employees. Each definition describes one extra field: its owning `entity_type`, a server-generated immutable `slug`, a human `label`, a `type` (text, textarea, number, date, checkbox, select, multi_select, url), optional `options` for the select types, and flags for `required`, `show_on_card`, and `sort_order`. Use it to list which custom fields a tenant has configured for a given entity (filter by `entity_type`) before reading or writing custom values on the corresponding lead/client/contact/employee records. This defines the SCHEMA of custom fields; the actual per-record values live on the entity repositories themselves, not here.", "tags": [ "Custom Fields" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of custom-field-definitions per page", "schema": { "type": "number" } }, { "name": "include", "in": "query", "required": false, "description": "No relationships available for this resource.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter custom-field-definitions by name or description. Available searchable fields: No searchable fields available (e.g., search=term)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sorting criteria for the custom-field-definitions. Available options: sort_order, created_at (e.g., sort=field or sort=-field for descending)", "schema": { "type": "string" } }, { "name": "entity_type", "in": "query", "required": false, "description": "Filter custom-field-definitions resource. Description: This is a exact match for entity_type (e.g., entity_type=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -entity_type=some_value). The filter type is string.", "schema": { "type": "string" } }, { "name": "related", "in": "query", "required": false, "description": "Comma-separated list of relationships to include in the response (see `include` for available names).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDefinitionResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "https://demo.growee.test/api/restify/custom-field-definitions", "per_page": 1, "to": 1, "total": 1 }, "links": { "first": "https://demo.growee.test/api/restify/custom-field-definitions?page=1", "next": null, "path": "https://demo.growee.test/api/restify/custom-field-definitions", "prev": null, "filters": "/api/restify/custom-field-definitions/filters" }, "data": [ { "id": "01kwm8530stah74f1g3ggdj94h", "type": "custom_field_definitions", "attributes": { "id": "01kwm8530stah74f1g3ggdj94h", "entity_type": "employee", "slug": "custom-field-select", "label": "Custom Field Select", "type": "select", "options": [ "Option 1", "Option 2" ], "required": false, "show_on_card": false, "sort_order": 0, "created_at": "2026-07-03T15:04:32.000000Z" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "custom-field-definitions-store", "summary": "Create a custom field definition", "tags": [ "Custom Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "description": "The record type this custom field belongs to; immutable after creation. One of: `lead` (CRM leads), `client`, `client_contact`, or `employee`. Determines which permission is required to manage the definition and which entity the field appears on.", "type": "string" }, "label": { "description": "Human-readable display name of the custom field shown in the UI (max 200 characters). Editable at any time; changing it does not change the immutable slug.", "maxLength": 200, "type": "string" }, "type": { "description": "The data type of the field, immutable after creation. One of: `text`, `textarea`, `number`, `date` (Y-m-d), `checkbox` (boolean), `select` (single choice from options), `multi_select` (multiple choices from options), or `url`. The `select` and `multi_select` types require the `options` list.", "type": "string" }, "options": { "description": "The list of allowed string choices for `select` and `multi_select` fields (max 50 entries, each a non-empty string up to 200 characters); null/omitted for all other types. Required when the type is select or multi_select.", "maxItems": 50, "type": "array" }, "required": { "description": "When true, a value for this custom field is mandatory when creating or updating the underlying record. Defaults to false.", "type": "boolean" }, "show_on_card": { "description": "When true, this field is surfaced on the compact card/summary view of the entity (e.g. the CRM board card) in addition to the full detail view. Defaults to false.", "type": "boolean" }, "sort_order": { "description": "Non-negative integer controlling the display order of custom fields for the entity; lower values appear first.", "minimum": 0, "type": "integer" } }, "required": [ "entity_type", "label", "type" ] }, "example": { "entity_type": "employee", "label": "Custom Field Select", "type": "select", "options": [ "Option 1", "Option 2" ], "required": false, "show_on_card": false, "sort_order": 0 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinitionResource" } } }, "example": { "data": { "id": "01kwm8530stah74f1g3ggdj94h", "type": "custom_field_definitions", "attributes": { "id": "01kwm8530stah74f1g3ggdj94h", "entity_type": "employee", "slug": "custom-field-select", "label": "Custom Field Select", "type": "select", "options": [ "Option 1", "Option 2" ], "required": false, "show_on_card": false, "sort_order": 0, "created_at": "2026-07-03T15:04:32.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/custom-field-definitions/{id}": { "get": { "operationId": "custom-field-definitions-show", "summary": "Retrieve a custom field definition", "tags": [ "Custom Fields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The custom field definition ULID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Custom field definition detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinitionResource" } } }, "example": { "data": { "id": "01kwm8530stah74f1g3ggdj94h", "type": "custom_field_definitions", "attributes": { "id": "01kwm8530stah74f1g3ggdj94h", "entity_type": "employee", "slug": "custom-field-select", "label": "Custom Field Select", "type": "select", "options": [ "Option 1", "Option 2" ], "required": false, "show_on_card": false, "sort_order": 0, "created_at": "2026-07-03T15:04:32.000000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "custom-field-definitions-update", "summary": "Update a custom field definition", "description": "Both `PUT` and `PATCH` are accepted.", "tags": [ "Custom Fields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The custom field definition ULID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "description": "The record type this custom field belongs to; immutable after creation. One of: `lead` (CRM leads), `client`, `client_contact`, or `employee`. Determines which permission is required to manage the definition and which entity the field appears on.", "type": "string" }, "label": { "description": "Human-readable display name of the custom field shown in the UI (max 200 characters). Editable at any time; changing it does not change the immutable slug.", "maxLength": 200, "type": "string" }, "type": { "description": "The data type of the field, immutable after creation. One of: `text`, `textarea`, `number`, `date` (Y-m-d), `checkbox` (boolean), `select` (single choice from options), `multi_select` (multiple choices from options), or `url`. The `select` and `multi_select` types require the `options` list.", "type": "string" }, "options": { "description": "The list of allowed string choices for `select` and `multi_select` fields (max 50 entries, each a non-empty string up to 200 characters); null/omitted for all other types. Required when the type is select or multi_select.", "maxItems": 50, "type": "array" }, "required": { "description": "When true, a value for this custom field is mandatory when creating or updating the underlying record. Defaults to false.", "type": "boolean" }, "show_on_card": { "description": "When true, this field is surfaced on the compact card/summary view of the entity (e.g. the CRM board card) in addition to the full detail view. Defaults to false.", "type": "boolean" }, "sort_order": { "description": "Non-negative integer controlling the display order of custom fields for the entity; lower values appear first.", "minimum": 0, "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinitionResource" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } }, "delete": { "operationId": "custom-field-definitions-destroy", "summary": "Delete a custom field definition", "tags": [ "Custom Fields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The custom field definition ULID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api-keys": { "get": { "operationId": "api-keys-index", "summary": "List api keys", "description": "Lists the REST API keys of the current user (the `personal_access_tokens` table, filtered to rows that have `scopes` set). Each key grants programmatic access to the Growee REST API, restricted to the selected permission scopes and, optionally, to an IP allowlist. Keys are created, regenerated and revoked in Growee under Settings -> Integrations -> API Keys; for security, requests authenticated with an API key can only read key metadata, never create, modify or delete keys.", "tags": [ "API Keys" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "perPage", "in": "query", "required": false, "description": "Results per page.", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Search term.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort field; prefix with - for descending.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResource" } } } }, "example": { "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 }, "links": { "first": "https://your-company.growee.net/api/restify/api-keys?page=1", "prev": null, "next": null }, "data": [ { "id": "01jz9x8p4a3vn4dxyp71zsakqm", "type": "api_keys", "attributes": { "name": "string", "scopes": "string", "allowed_ips": "string", "last_used_at": "2026-07-14", "created_at": "2026-07-14" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key created in Growee under **Settings → Integrations → API Keys**. Send it as `Authorization: Bearer `." } }, "schemas": { "ActivityAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "number" }, "record_type": { "description": "The kind of parent record this activity is attached to; one of 'client', 'lead', or 'client_contact'. Set once at creation together with record_id and immutable afterwards.", "type": "string" }, "record_id": { "description": "The ULID of the parent record (a client, lead, or client contact, as determined by record_type) that this activity belongs to. Must reference an existing record in the current tenant; immutable after creation.", "type": "string" }, "type": { "description": "The kind of interaction being logged. Allowed values: 'email', 'call', 'linkedin_message', 'meeting', 'note'.", "type": "string" }, "direction": { "description": "Whether the interaction came from the contact or went out to them; one of 'inbound' or 'outbound'. Nullable/irrelevant for interaction types like a plain note.", "type": "string" }, "subject": { "description": "Short one-line summary or title of the interaction (e.g. an email subject or call topic), up to 255 characters. Optional.", "type": "string" }, "body": { "description": "The full free-text content of the interaction: the email body, call notes, or the text of the note. Optional plain-text/markdown string with no length limit.", "type": "string" }, "happened_at": { "description": "When the interaction actually occurred, as an ISO 8601 datetime. Defaults to the current time on creation when omitted; drives the chronological ordering of the timeline.", "type": "string" }, "author_id": { "description": "ULID of the Employee (see the employees repository) who logged this activity. Set automatically server-side to the acting employee; any client-supplied value is ignored and the field is immutable.", "type": "string" }, "pinned": { "description": "Boolean flag; when true this activity is pinned and floats to the top of the record timeline regardless of its happened_at date. Defaults to false.", "type": "string" }, "meta": { "description": "Optional free-form JSON object holding extra structured metadata about the interaction (e.g. provider message ids or channel details). Arbitrary key/value array.", "type": "string" }, "tenant_id": { "description": "ULID of the tenant that owns this activity. Set automatically from the tenant context; read-only.", "type": "string" }, "is_demo": { "description": "Boolean flag marking rows created as demo/seed data rather than real user data. Read-only.", "type": "boolean" }, "created_at": { "description": "Timestamp when the activity row was created (ISO 8601). Read-only.", "type": "string" }, "updated_at": { "description": "Timestamp when the activity row was last updated (ISO 8601). Read-only.", "type": "string" } }, "additionalProperties": true }, "ActivityResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ActivityAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ApiKeyAttributes": { "type": "object", "properties": { "name": { "description": "Human-readable label identifying the key (e.g. the integration it is issued for). Required on creation, max 100 characters.", "type": "string" }, "scopes": { "description": "Array of permission scope names this key is granted (e.g. [\"manageEmployees\", \"manageTimesheets\"]). Each entry must be a permission the creating user holds — a key can never exceed its owner's permissions. Required and non-empty on creation.", "type": "string" }, "allowed_ips": { "description": "Optional array of IP addresses or CIDR ranges (e.g. [\"203.0.113.7\", \"10.0.0.0/8\"]) the key may be used from. Empty or null allows all IPs.", "type": "string" }, "last_used_at": { "description": "Timestamp (ISO 8601) of the key's most recent use, or null if it has never been used. Read-only.", "type": "string" }, "created_at": { "description": "Timestamp (ISO 8601) when the key was created. Read-only.", "type": "string" } }, "additionalProperties": true }, "ApiKeyResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ApiKeyAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "AssetAttributes": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) this asset is currently assigned to, or null if unassigned/in stock. Must reference an existing employee.", "type": "number" }, "name": { "description": "Human-readable label for the asset, e.g. \"MacBook Pro 16 (2023)\". Required string up to 255 characters.", "type": "string" }, "type": { "description": "The asset category; one of: electronic, furniture, book, office, software, subscription, other. Required.", "type": "string" }, "model": { "description": "Optional manufacturer model name/number of the asset, e.g. \"A2780\". Nullable string up to 255 characters.", "type": "string" }, "serial_number": { "description": "Optional unique serial number of the physical asset for identification/warranty. Nullable string up to 255 characters.", "type": "string" }, "supplier": { "description": "Optional name of the vendor/supplier the asset was purchased from. Nullable string up to 255 characters.", "type": "string" }, "acquisition_date": { "description": "Optional date (date only, no time) the asset was acquired/purchased. Nullable, format YYYY-MM-DD.", "type": "string" }, "purchase_value": { "description": "Optional purchase cost of the asset as a decimal amount (2 decimal places) in the field-defined currency. Nullable, must be >= 0.", "type": "string" }, "currency": { "description": "ISO 4217 3-letter currency code for purchase_value, e.g. \"RON\", \"EUR\", \"USD\". Required, defaults to \"RON\".", "type": "string" }, "notes": { "description": "Optional free-text notes about the asset (condition, history, maintenance log). Nullable string.", "type": "string" }, "status": { "description": "The asset lifecycle status; one of: available, in_use, maintenance, decommissioned, lost. Required. Prefer the mark-as-* actions for transitions to lost/decommissioned/maintenance.", "type": "string" }, "assigned_at": { "description": "Read-only timestamp of when the asset was assigned to its current employee. Nullable; set automatically on assignment.", "type": "string" }, "assigned_by": { "description": "Read-only ULID foreign key to the Employee (EmployeeRepository) who performed the assignment, surfaced via the assigner relationship. Nullable.", "type": "string" }, "is_demo": { "description": "Boolean flag; true marks the asset as demo/sample seed data rather than a real company asset. Defaults to false and is only visible to users with the manage-employees permission.", "type": "boolean" } }, "additionalProperties": true }, "AssetResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/AssetAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "BenefitAttributes": { "type": "object", "properties": { "title": { "description": "Human-readable name of the benefit as shown to employees (e.g. \"Gym membership\", \"Meal vouchers\"). Required, max 255 characters.", "type": "string" }, "description": { "description": "Optional longer explanation of what the benefit includes or its eligibility terms. Free text, may be null.", "type": "string" }, "recurrence": { "description": "How often the benefit recurs. Allowed values: \"monthly\", \"quarterly\", \"yearly\", \"one_time\". Defaults to \"monthly\" when omitted.", "type": "string" }, "amount": { "description": "Optional monetary value of the benefit per recurrence, as a non-negative decimal (2 decimal places). Interpreted in the currency given by the currency field.", "type": "string" }, "currency": { "description": "ISO currency code for the amount (e.g. \"EUR\", \"USD\", \"RON\"). Max 8 characters; may be null when no amount applies.", "type": "string" }, "is_demo": { "description": "Read-only boolean flag; true means this benefit was created as sample/demo data rather than by a real user. Not writable.", "type": "boolean" } }, "additionalProperties": true }, "BenefitResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/BenefitAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "CandidateAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Full name of the candidate/applicant. Required when creating.", "type": "string" }, "email": { "description": "Primary email address of the candidate; must be a valid email. Required when creating and used to detect duplicate people when hiring.", "type": "string" }, "phone": { "description": "Candidate phone number as free-form text (any format), optional.", "type": "string" }, "linkedin_url": { "description": "URL of the candidate LinkedIn profile (e.g. https://linkedin.com/in/...), optional.", "type": "string" }, "portfolio_url": { "description": "URL to the candidate personal website, portfolio or GitHub, optional.", "type": "string" }, "location": { "description": "Candidate location as free-form text, e.g. city and country. Optional.", "type": "string" }, "expected_salary_amount": { "description": "Salary the candidate expects, as a non-negative decimal amount (2 decimal places). Interpret the currency from expected_salary_currency. Optional.", "type": "string" }, "expected_salary_currency": { "description": "ISO 4217 currency code (e.g. EUR, USD, RON) for expected_salary_amount. Optional.", "type": "string" }, "availability_date": { "description": "Date (YYYY-MM-DD) from which the candidate is available to start. Optional.", "type": "string" }, "interview_date": { "description": "Scheduled interview date (YYYY-MM-DD) for the candidate. Optional.", "type": "string" }, "stage_id": { "description": "ULID foreign key referencing a CandidateStage (candidate-stages repository) that positions this candidate in the hiring pipeline. Optional.", "type": "number" }, "hiring_manager_id": { "description": "ULID foreign key referencing the Employee (employees repository) responsible for this candidate as hiring manager. Optional.", "type": "string" }, "job_id": { "description": "ULID foreign key referencing the Job vacancy (jobs repository) this candidate applied to or is being considered for. Optional.", "type": "string" }, "source": { "description": "How the candidate entered the pipeline. One of: manual, pdf_upload, linkedin, referral, job_board, website, other. Defaults to manual.", "type": "string" }, "score_overall": { "description": "Overall AI-generated fit score for the candidate, numeric between 0 and 10 (higher is better). Optional.", "type": "integer" }, "score_education": { "description": "AI-generated score for the candidate education, numeric between 0 and 10. Optional.", "type": "integer" }, "score_skills": { "description": "AI-generated score for the candidate skills, numeric between 0 and 10. Optional.", "type": "integer" }, "score_role_fit": { "description": "AI-generated score for how well the candidate fits the target role, numeric between 0 and 10. Optional.", "type": "integer" }, "score_reasoning": { "description": "Free-text explanation from the AI justifying the scores above. Optional.", "type": "string" }, "education": { "description": "Education history as a JSON array of entries, each typically with from, till, institution and description keys. Optional.", "type": "array" }, "work_history": { "description": "Work experience as a JSON array of entries, each typically with from, till, company_name, position and description keys. Optional.", "type": "array" }, "skills": { "description": "Candidate skills as a JSON array; entries may be plain skill strings or objects with category and skills keys. Optional.", "type": "array" }, "languages": { "description": "Spoken languages as a JSON array; entries may be language name strings or objects with language/name and level/proficiency keys. Optional.", "type": "array" }, "tags": { "description": "Free-form labels for organizing/filtering candidates, as a JSON array of strings. Optional.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free-text internal notes about the candidate. Optional.", "type": "string" }, "cv_filename": { "description": "Original filename of the uploaded CV. You can keep it empty or provide an intuitive name if there is a file.", "type": "string" }, "cv_size": { "description": "Size in bytes of the uploaded CV file. Read-only, set automatically on upload.", "type": "string" }, "created_by": { "description": "ULID of the User who created this candidate record. Read-only, set automatically.", "type": "string" }, "updated_by": { "description": "ULID of the User who last updated this candidate record. Read-only, set automatically.", "type": "string" }, "archived_at": { "description": "Timestamp when the candidate was archived; null if active. Read-only, changed via the archive-candidate/unarchive-candidate actions.", "type": "string" }, "archived_by": { "description": "ULID of the User who archived the candidate. Read-only, set by the archive-candidate action.", "type": "string" }, "status_before_archive": { "description": "Snapshot of the candidate stage/status before archiving, used to restore it on unarchive. Read-only.", "type": "string" }, "created_at": { "description": "Timestamp when the candidate record was created. Read-only.", "type": "string" }, "updated_at": { "description": "Timestamp when the candidate record was last updated. Read-only.", "type": "string" } }, "additionalProperties": true }, "CandidateResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/CandidateAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "CandidateStageAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "number" }, "name": { "description": "Display name of the pipeline stage (e.g. \"Applied\", \"Interview\", \"Offer\"). Required and must be unique within the tenant.", "type": "string" }, "position": { "description": "Zero-based integer that orders this stage within the pipeline; lower values appear first. Required when creating.", "type": "integer" }, "color": { "description": "Optional color used to visually distinguish the stage in the UI, e.g. a hex code or color name.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this stage represents in the hiring process.", "type": "string" }, "created_at": { "description": "Timestamp when the stage was created. Read-only.", "type": "string" }, "updated_at": { "description": "Timestamp when the stage was last updated. Read-only.", "type": "string" } }, "additionalProperties": true }, "CandidateStageResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/CandidateStageAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ClientAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "company_name": { "description": "The legal or trading name of the client company. Required and must be unique per tenant; this is the primary human-readable identifier for the client.", "type": "string" }, "description": { "description": "Free-text notes about the client company (may contain HTML). Used for internal context and AI enrichment.", "type": "string" }, "website": { "description": "The client's full website URL (e.g. https://acme.com); a trailing slash is stripped on save. Nullable, max 255 characters.", "type": "string" }, "prefered_currency": { "description": "The client's preferred billing currency as an ISO 4217 code (e.g. EUR, USD, RON). Used as the default currency when invoicing this client.", "type": "string" }, "company_identifier": { "description": "The client's legal company registration number (e.g. trade register / company number), used on invoices and contracts.", "type": "string" }, "company_vat": { "description": "The client's VAT / tax identification number, printed on invoices for tax purposes.", "type": "string" }, "representative_name": { "description": "Full name of the client's legal representative or signatory used on generated documents and contracts.", "type": "string" }, "representative_position": { "description": "Job title of the client's legal representative (e.g. \"CEO\", \"Managing Director\"), shown alongside representative_name on documents.", "type": "string" }, "company_address": { "description": "The client's postal/billing address, stored as a JSON object (structured address parts). Appears on invoices and contracts.", "type": "object" }, "bank_name": { "description": "Name of the client's bank, used for payment details on invoices.", "type": "string" }, "bank_account": { "description": "The client's bank account number / IBAN. Stored encrypted at rest.", "type": "string" }, "bank_swift": { "description": "The SWIFT/BIC code of the client's bank for international transfers. Stored encrypted at rest.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom fields for the client, provided as a key/value object whose keys are the tenant's configured custom-field definitions for the \"client\" entity.", "type": "string" }, "domain": { "description": "The client's primary web domain without protocol (e.g. \"acme.com\"). CRM attribute used to match and deduplicate organizations. Nullable, max 200 characters.", "type": "string" }, "industry": { "description": "Free-text industry / sector of the client company (e.g. \"Software\", \"Manufacturing\"). CRM segmentation attribute. Nullable, max 100 characters.", "type": "string" }, "size": { "description": "Free-text company size, typically an employee-count band (e.g. \"1-10\", \"50-200\"). CRM segmentation attribute. Nullable, max 20 characters.", "type": "number" }, "city": { "description": "City where the client is located. CRM attribute. Nullable, max 100 characters.", "type": "string" }, "country": { "description": "Country where the client is located, as free text. CRM attribute. Nullable, max 100 characters.", "type": "string" }, "lifecycle_stage": { "description": "CRM lifecycle stage of the client. One of: \"lead\", \"marketing_qualified\", \"sales_qualified\", \"customer\", \"churned\". Defaults to \"lead\" on creation; advance it as the relationship progresses.", "type": "string" }, "owner_id": { "description": "ULID foreign key to the employees table (an EmployeeRepository record) identifying the account owner responsible for this client. Must reference a non-deleted employee in the current tenant. Nullable.", "type": "number" }, "meta": { "description": "Free-form JSON metadata bag for extra CRM attributes not modeled as columns. Nullable object.", "type": "string" }, "created_at": { "description": "Read-only timestamp (ISO 8601) of when the client record was created.", "type": "string" }, "is_used": { "description": "Read-only boolean; true when the client has at least one invoice or project, meaning it is actively in use and generally should not be deleted.", "type": "boolean" }, "logo_path": { "description": "The client's logo image file, stored on S3. On read it resolves to a temporary signed URL valid for 7 days; on write send an uploaded file.", "type": "string" } }, "additionalProperties": true }, "ClientContactAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Full name of the contact person. Required on create; the primary human-readable label for the contact.", "type": "string" }, "email": { "description": "The contact's primary email address. Required on create and must be a valid email. This is the display address; additional addresses are managed via the client-contact-emails repository.", "type": "string" }, "verification_status": { "description": "Read-only email deliverability status for this contact, derived from CRM email verification. One of \"deliverable\", \"risky\", \"undeliverable\", or \"unknown\", or null when not yet verified.", "type": "string" }, "phone": { "description": "The contact's phone number as free text. Optional.", "type": "string" }, "position": { "description": "The contact's job title or role at the company (e.g. \"Head of Procurement\"). Optional.", "type": "string" }, "custom_fields": { "description": "Tenant-defined custom fields for the contact, provided as a key/value object whose keys are the tenant's configured custom-field definitions for the \"client_contact\" entity.", "type": "string" }, "client_id": { "description": "ULID foreign key to the clients table (a ClientRepository / organization record) identifying the company this contact works at. Required on create; may be sent as organization_id, which is mirrored onto client_id.", "type": "string" } }, "additionalProperties": true }, "ClientContactResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ClientContactAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ClientResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ClientAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ContractTypeAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Human-readable label of the employment-contract category, e.g. \"Full-time\", \"Part-time\", \"B2B\" or \"Internship\". Free-text string, unique per tenant by convention.", "type": "string" }, "heading": { "description": "Read-only display heading derived from the name (title-cased headline form of \"name\"). Used purely for presentation; it is not stored and defaults from the name when omitted.", "type": "string" } }, "additionalProperties": true }, "ContractTypeResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ContractTypeAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "CrmTicketAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "number" }, "number": { "description": "The per-tenant sequential ticket number (integer), also echoed in the subject as `[#number]` so email replies re-thread. Assigned on creation. Read-only.", "type": "string" }, "subject": { "description": "The ticket subject/title summarizing the request. Max 255 characters.", "type": "string" }, "ticket_stage_id": { "description": "ULID of the current workflow stage (column), referencing a crm-ticket-stages record belonging to this tenant. Set to move the ticket across the kanban board.", "type": "string" }, "priority": { "description": "Ticket priority. One of: `low`, `normal`, `high`, `urgent`. Defaults to `normal`.", "type": "string" }, "owner_id": { "description": "ULID of the employee (employees table) assigned to handle this ticket, or null if unassigned. Must belong to the current tenant.", "type": "string" }, "organization_id": { "description": "ULID of the client company (clients table, exposed via crm-organizations) this ticket belongs to, or null. Set from the matched contact when opened from mail. Read-only.", "type": "string" }, "client_contact_id": { "description": "ULID of the requesting contact (client_contacts table) this ticket is with, or null. Set from the sender when opened from mail. Read-only.", "type": "string" }, "inbox_address_id": { "description": "ULID of the support inbox address (crm-inbox-addresses) the opening email arrived on, or null for manually-created tickets. Read-only.", "type": "string" }, "source": { "description": "How the ticket was created, e.g. `email` (opened from inbound mail) or `manual` (created by a user/agent). Read-only.", "type": "string" }, "first_response_due_at": { "description": "Timestamp (ISO 8601) by which the first agent response is due per the inbox address SLA, or null if no SLA applies. Read-only.", "type": "string" }, "first_responded_at": { "description": "Timestamp (ISO 8601) when an agent first replied, or null if not yet answered. Read-only.", "type": "string" }, "closed_at": { "description": "Timestamp (ISO 8601) when the ticket was closed, or null while still open. Read-only.", "type": "string" }, "last_inbound_at": { "description": "Timestamp (ISO 8601) of the most recent inbound (customer) message; the default sort key for the queue. Read-only.", "type": "string" }, "meta": { "description": "Free-form JSON metadata about the ticket (internal bookkeeping). Read-only.", "type": "string" }, "created_at": { "description": "Timestamp (ISO 8601) when the ticket was opened. Read-only.", "type": "string" }, "updated_at": { "description": "Timestamp (ISO 8601) when the ticket was last modified. Read-only.", "type": "string" } }, "additionalProperties": true }, "CrmTicketResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/CrmTicketAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "CrmTicketStageAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "The user-facing name of the kanban column (e.g. \"Waiting on customer\"). Must be unique within the tenant; max 100 characters.", "type": "string" }, "position": { "description": "0-based sort order of this column on the kanban board; lower numbers appear first. Non-negative integer.", "type": "integer" }, "color": { "description": "Optional display color for the column (e.g. a hex code or CSS color name), used for the board UI. Null when unset.", "type": "string" }, "semantic": { "description": "System-managed behaviour marker, set only on the seeded default stages. One of `new`, `open`, `waiting`, `closed`, or null for user-created stages; drives where new tickets land, which stage a reply reopens into, and which one closes a ticket. Read-only.", "type": "string" }, "created_at": { "description": "Timestamp (ISO 8601) when the stage was created. Read-only.", "type": "string" }, "updated_at": { "description": "Timestamp (ISO 8601) when the stage was last modified. Read-only.", "type": "string" } }, "additionalProperties": true }, "CrmTicketStageResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/CrmTicketStageAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "CustomFieldDefinitionAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "entity_type": { "description": "The record type this custom field belongs to; immutable after creation. One of: `lead` (CRM leads), `client`, `client_contact`, or `employee`. Determines which permission is required to manage the definition and which entity the field appears on.", "type": "string" }, "slug": { "description": "Server-generated, immutable machine key derived from the label (slugified, numeric-suffixed to stay unique per tenant and entity_type). This is the stable identifier used to store and read the field value on individual records; it is never sent on create/update.", "type": "string" }, "label": { "description": "Human-readable display name of the custom field shown in the UI (max 200 characters). Editable at any time; changing it does not change the immutable slug.", "type": "string" }, "type": { "description": "The data type of the field, immutable after creation. One of: `text`, `textarea`, `number`, `date` (Y-m-d), `checkbox` (boolean), `select` (single choice from options), `multi_select` (multiple choices from options), or `url`. The `select` and `multi_select` types require the `options` list.", "type": "string" }, "options": { "description": "The list of allowed string choices for `select` and `multi_select` fields (max 50 entries, each a non-empty string up to 200 characters); null/omitted for all other types. Required when the type is select or multi_select.", "type": "array" }, "required": { "description": "When true, a value for this custom field is mandatory when creating or updating the underlying record. Defaults to false.", "type": "boolean" }, "show_on_card": { "description": "When true, this field is surfaced on the compact card/summary view of the entity (e.g. the CRM board card) in addition to the full detail view. Defaults to false.", "type": "boolean" }, "sort_order": { "description": "Non-negative integer controlling the display order of custom fields for the entity; lower values appear first.", "type": "integer" }, "created_at": { "description": "Timestamp (ISO 8601) when this custom field definition was created. Read-only.", "type": "string" } }, "additionalProperties": true }, "CustomFieldDefinitionResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/CustomFieldDefinitionAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "DepartmentAttributes": { "type": "object", "properties": { "name": { "description": "The department name, e.g. \"Engineering\" or \"Sales\". Required plain string, unique per tenant in practice.", "type": "string" }, "description": { "description": "Optional free-text description of the department's purpose or scope. Nullable string.", "type": "string" }, "is_used": { "description": "Read-only boolean flag indicating whether the department is currently referenced by positions/employees; true means it cannot be safely deleted.", "type": "boolean" } }, "additionalProperties": true }, "DepartmentResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/DepartmentAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "DirectionAttributes": { "type": "object", "properties": { "name": { "description": "The direction name, e.g. \"Frontend\" or \"Recruiting\". Required plain string, unique within its department in practice.", "type": "string" }, "description": { "description": "Optional free-text description explaining what this direction covers. Nullable string.", "type": "string" }, "department_id": { "description": "ULID foreign key to the parent department (Department model / DepartmentRepository) this direction belongs to. Required.", "type": "string" }, "is_used": { "description": "Read-only boolean flag indicating whether this direction is currently referenced by employees/positions; true means it cannot be safely deleted.", "type": "boolean" } }, "additionalProperties": true }, "DirectionResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/DirectionAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "DocumentAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Human-readable title of the document (e.g. \"Employment Contract\", \"ID Card\"). Required when creating a document.", "type": "string" }, "description": { "description": "Optional free-text note describing the document or its purpose.", "type": "string" }, "content": { "description": "Optional HTML body of the document, used for documents generated from a template rather than an uploaded file; can be converted to a Word/PDF file on demand.", "type": "string" }, "type_id": { "description": "Required ULID foreign key to a document_types record (managed by the document-types repository) that classifies this document, e.g. contract, ID, certificate.", "type": "string" }, "employee_id": { "description": "Optional ULID foreign key to the employee (employees repository) this document belongs to; if omitted on write it defaults to the current user's own employee unless they manage documents.", "type": "number" }, "client_id": { "description": "Optional ULID foreign key to the client (clients repository) this document belongs to; used for client-owned documents instead of employee-owned ones.", "type": "string" }, "path": { "description": "The uploaded file itself: send the raw file or a base64-encoded string when creating a document. Allowed types are pptx, pdf, docx, doc, txt, csv, rtf, jpg, jpeg, png, svg, gif, bmp, xls, xlsx, ppt (max 20MB). On read it resolves to a temporary download URL.", "type": "string" }, "file_name": { "description": "The original name of the uploaded file including its extension (e.g. \"contract.pdf\"). Send this alongside \"path\" when uploading.", "type": "string" }, "size": { "description": "Size of the stored file in bytes; set automatically from the upload and read-only.", "type": "number" }, "start_date": { "description": "Optional validity start date of the document (ISO 8601 / Y-m-d datetime).", "type": "string" }, "end_date": { "description": "Optional validity/expiry end date (ISO 8601 / Y-m-d datetime); when set the system can send expiration reminders to the owner.", "type": "string" }, "documentable_type": { "description": "Read-only morph type of the entity this document is polymorphically attached to, when the document was generated for a specific record.", "type": "string" }, "status": { "description": "Read-only lifecycle status of the document (currently always \"new\").", "type": "string" }, "is_signed": { "description": "Read-only boolean; true when the document has at least one recorded e-signature.", "type": "boolean" }, "signature_count": { "description": "Read-only count of e-signatures recorded against this document.", "type": "number" }, "created_at": { "description": "Read-only timestamp of when the document was created (ISO 8601).", "type": "string" } }, "additionalProperties": true }, "DocumentResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/DocumentAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "DocumentTypeAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Human-readable name of the document category, e.g. \"Employment Contract\", \"NDA\" or \"Payslip\". Required free-text string, unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional longer free-text explanation of what this document category is used for. Nullable.", "type": "string" }, "is_used": { "description": "Read-only boolean flag; true when at least one document currently references this type. Indicates whether the category is safe to delete (false means unused).", "type": "boolean" } }, "additionalProperties": true }, "DocumentTypeResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/DocumentTypeAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "EmployeeAttributes": { "type": "object", "properties": { "position_id": { "description": "The position of the employee. Optional but recommended when creating a new employee. It must be a valid position ID. You can identify it using the positions tool.", "type": "string" }, "direction_id": { "description": "The direction/department the employee belongs to. Optional field. Must be a valid direction ID if provided.", "type": "number" }, "manager_employee_id": { "description": "The ID of the employee's manager. Optional field. Must be a valid employee ID from the same tenant if provided.", "type": "string" }, "level_id": { "description": "The level/seniority of the employee. Optional field. Must be a valid level ID if provided.", "type": "string" }, "email": { "description": "The employee's work email address. Required when creating a new employee. Must be unique and a valid email format.", "type": "string" }, "avatar": { "description": "The employee's profile picture. Optional field. Must be a string absolute image path.", "type": "string" }, "avatar_name": { "description": "The original filename of the employee's avatar. Automatically stored when an avatar is uploaded.", "type": "string" }, "default_signature_id": { "description": "The ID of the default signature to use for this employee when signing documents.", "type": "number" }, "status": { "description": "The employee status. This field is managed by the system and cannot be changed directly.", "type": "string" }, "personal_email": { "description": "The employee's personal email address. Optional field. Must be a valid email format if provided.", "type": "string" }, "first_name": { "description": "The employee's first name. Required when creating a new employee.", "type": "string" }, "name": { "description": "The employee's full name. This is a computed field combining first and last name. Read-only.", "type": "string" }, "last_name": { "description": "The employee's last name. Required when creating a new employee.", "type": "string" }, "general_information": { "description": "General information or notes about the employee. Optional text field.", "type": "string" }, "phone": { "description": "The employee's phone number. Optional field.", "type": "string" }, "birth_date": { "description": "The employee's date of birth. Optional field. Must be a valid date format if provided.", "type": "string" }, "identity_card_number": { "description": "The employee's identity card or passport number. Optional field for identification purposes.", "type": "string" }, "personal_identification_number": { "description": "The employee's national identification number (e.g., SSN, CNP). Optional field.", "type": "string" }, "address": { "description": "The employee's residential address. Optional field.", "type": "object" }, "timezone": { "description": "The employee's timezone. Optional field. Must be a valid timezone identifier if provided.", "type": "string" }, "about": { "description": "A brief description or bio about the employee. Optional text field.", "type": "string" }, "quote": { "description": "A favorite quote or motto of the employee. Optional field with maximum 500 characters.", "type": "string" }, "invite_immediately": { "description": "Whether to send an invitation email to the employee immediately upon creation. Boolean field.", "type": "boolean" }, "contract_type": { "description": "The type of employment contract. Available values:{\"employment_contract\":\"Used when the employee is hired under a standard employment contract. Usually offers full labor rights, paid holidays and benefits.\",\"internship\":\"Used for temporary training positions, often for students or recent graduates. May have limited benefits and a fixed duration.\",\"b2b_unpaid_holidays\":\"Used for contractors or freelancers working under a business-to-business agreement without paid holiday entitlements.\",\"b2b_paid_holidays\":\"Used for contractors or freelancers working under a business-to-business agreement with paid holiday entitlements.\"}", "type": "string" }, "company_position": { "description": "The official position title in the employee's company (for contractors). Optional field.", "type": "string" }, "company_name": { "description": "The name of the employee's company (for contractors). Optional field.", "type": "string" }, "company_vat": { "description": "The VAT number of the employee's company (for contractors). Optional field.", "type": "string" }, "company_identifier": { "description": "The registration number or identifier of the employee's company (for contractors). Optional field.", "type": "string" }, "company_address": { "description": "The address of the employee's company (for contractors). Optional field.", "type": "object" }, "contract_bank_name": { "description": "The name of the bank for contract payments. Optional field.", "type": "string" }, "contract_bank_swift": { "description": "The SWIFT/BIC code of the bank for contract payments. Optional field.", "type": "string" }, "contract_bank_account": { "description": "The bank account number for contract payments. Optional field.", "type": "string" }, "start_date": { "description": "The employee's start date. Required when creating a new employee. Must be a valid date format.", "type": "string" }, "termination_date": { "description": "The employee's termination date. Optional field. Must be after the start date if provided.", "type": "string" }, "salary_type": { "description": "The type of salary payment (e.g., monthly, hourly). Visible only to users with manage salaries permission. Available values: {\"hourly\":\"Hourly\",\"monthly\":\"Monthly\"}", "type": "string" }, "salary_currency": { "description": "The currency code for the salary (e.g., USD, EUR, RON). Visible only to users with manage salaries permission. Must be a 3-character currency code.", "type": "string" }, "salary": { "description": "The employee's salary amount. Visible only to users with manage salaries permission. Must be a positive number if provided.", "type": "integer" }, "sensitive_information": { "description": "Sensitive or confidential information about the employee. Optional text field with restricted access.", "type": "string" }, "weekly_hours_capacity": { "description": "The employee's weekly working hours capacity. Optional field. Must be between 0 and 168 hours if provided. Use 0 for overtime-only tracking (no expected weekly hours).", "type": "integer" }, "initial_vacation_balance": { "description": "The initial vacation days balance for the employee. Optional field. Must be a positive number if provided.", "type": "integer" }, "technical_evaluation_assignees": { "description": "Array of employee IDs who are assigned to perform technical evaluations for this employee. Optional field. All IDs must be valid employees from the same tenant.", "type": "array" }, "salary_evaluation_assignees": { "description": "Array of employee IDs who are assigned to perform salary evaluations for this employee. Optional field. All IDs must be valid employees from the same tenant.", "type": "array" }, "billed_rate": { "description": "The hourly rate at which the employee is billed to clients. Visible only to users with manage employees permission. Must be a positive number if provided.", "type": "integer" }, "internal_cost_hourly_rate": { "description": "The internal hourly cost rate for the employee. Visible only to users with manage employees permission. Must be a positive number if provided.", "type": "integer" }, "internal_cost_type": { "description": "The unit used to express the internal cost rate. Available values: hourly, monthly. Null is treated as hourly. Visible only to users with manage employees permission.", "type": "string" }, "internal_cost_monthly_rate": { "description": "The internal monthly cost for the employee, converted to an hourly equivalent using the weekly hours capacity. Required when internal_cost_type is monthly. Visible only to users with manage employees permission.", "type": "string" }, "position_code": { "description": "An internal code or reference for the employee's position. Optional field with maximum 50 characters.", "type": "string" }, "gender": { "description": "The employee's gender. Optional field.", "type": "string" }, "custom_fields": { "description": "Field: custom_fields. ", "type": "object" } }, "additionalProperties": true }, "EmployeeBenefitAttributes": { "type": "object", "properties": { "employee_id": { "description": "The employee receiving the benefit. Required. ULID referencing the employees repository.", "type": "string" }, "benefit_id": { "description": "The benefit being assigned. Required. ULID referencing the benefits repository, which holds the benefit definition (name, type, value).", "type": "string" }, "start_date": { "description": "The date from which the benefit applies to the employee. Optional date (Y-m-d).", "type": "string" }, "end_date": { "description": "The date on which the benefit stops applying. Optional date (Y-m-d); must be on or after start_date.", "type": "string" }, "is_demo": { "description": "Whether this assignment is seeded demo data rather than real data. Boolean, read-only and system-managed.", "type": "boolean" } }, "additionalProperties": true }, "EmployeeBenefitResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/EmployeeBenefitAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "EmployeeResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/EmployeeAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" } } }, "EvaluationAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "employee_id": { "description": "ULID foreign key of the employee being evaluated (references EmployeeRepository). Required; for users without elevated permissions it is auto-resolved to the current employee.", "type": "string" }, "type_id": { "description": "ULID foreign key of the evaluation type/category (references EvaluationTypeRepository, e.g. \"Annual review\", \"Probation review\"). Required and must exist.", "type": "string" }, "evaluated_at": { "description": "Date the evaluation took place, in Y-m-d format. Required.", "type": "string" }, "name": { "description": "Optional free-text title/label for this specific evaluation. Nullable.", "type": "string" }, "notify_at": { "description": "Optional date (Y-m-d) on which a reminder about this evaluation should be sent; must be on or before evaluated_at. Nullable.", "type": "string" }, "next_evaluation_at": { "description": "Optional date (Y-m-d) scheduled for the employee's next evaluation. Used to surface upcoming reviews. Nullable.", "type": "string" }, "salary_before": { "description": "Employee's salary before this evaluation, as a numeric amount in the field \"currency\". Optional.", "type": "string" }, "salary_request": { "description": "Salary the employee requested during the review, as a numeric amount in the field \"currency\". Optional.", "type": "string" }, "salary_after": { "description": "Agreed salary after this evaluation, as a numeric amount in the field \"currency\". Optional.", "type": "string" }, "currency": { "description": "Currency code (e.g. \"EUR\", \"RON\", \"USD\") that the salary_before/salary_request/salary_after amounts are expressed in.", "type": "string" }, "salary_type": { "description": "How the salary amounts are expressed, e.g. \"monthly\", \"yearly\" or \"hourly\". Free-text/enum-like string.", "type": "string" }, "external_evaluation_url": { "description": "Optional URL to an external evaluation document or form (e.g. a Google Form or shared doc) related to this review. Nullable.", "type": "string" }, "assignees": { "description": "Array of employee ULIDs assigned as evaluators/participants for this review; every id must belong to an employee in the current tenant. Optional.", "type": "array" }, "notes": { "description": "Free-text notes summarizing the evaluation discussion and outcome. Nullable.", "type": "string" }, "position_before_id": { "description": "ULID foreign key of the employee's position before the evaluation (references PositionRepository). Set together with position_after_id to record a role change/promotion. Nullable.", "type": "string" }, "position_after_id": { "description": "ULID foreign key of the employee's position after the evaluation (references PositionRepository). Nullable.", "type": "string" }, "level_before_id": { "description": "ULID foreign key of the employee's seniority level before the evaluation (references LevelRepository, e.g. \"Junior\", \"Mid\"). Nullable.", "type": "number" }, "level_after_id": { "description": "ULID foreign key of the employee's seniority level after the evaluation (references LevelRepository). Set with level_before_id to record a level change. Nullable.", "type": "number" }, "file": { "description": "Optional supporting document attached to the evaluation (uploaded to the tenant's documents disk, max 20 MB, allowed mime types only). On read it resolves to a URL to the stored file.", "type": "string" }, "file_name": { "description": "Original file name of the uploaded evaluation document (captured automatically from the \"file\" upload). Nullable.", "type": "string" } }, "additionalProperties": true }, "EvaluationResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/EvaluationAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "EvaluationTypeAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Human-readable name of the evaluation/review category, e.g. \"Annual review\" or \"Probation review\". Required free-text string, unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional longer free-text explanation of what this review category covers. Nullable.", "type": "string" }, "is_used": { "description": "Read-only boolean flag; true when at least one evaluation currently references this type. False means the category is unused and safe to delete.", "type": "boolean" } }, "additionalProperties": true }, "EvaluationTypeResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/EvaluationTypeAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ExpenseAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "employee_id": { "description": "The id of the employee submitting the expense. If not provided, it defaults to the currently authenticated employee.", "type": "string" }, "expense_bundle_id": { "description": "This is very important in order to be grouped with other expenses for approval and payment. Try to always provide it from the list of expense bundles.", "type": "number" }, "expense_category_id": { "description": "The ULID id of the ExpenseCategory (ExpenseCategories repository) this expense belongs to, e.g. transport, meals or accommodation. The category determines whether a receipt is required and any per-expense maximum amount.", "type": "string" }, "project_id": { "description": "If expense is related to a project, select it here.", "type": "number" }, "requested_approver_id": { "description": "The ULID id of the Employee (Employees repository) who is requested to approve this expense. Must be an employee of the current tenant; if omitted the organization approval workflow assigns the approver.", "type": "string" }, "date": { "description": "The calendar date the expense was incurred, in YYYY-MM-DD format. Defaults to today when not provided.", "type": "string" }, "amount": { "description": "The gross monetary amount of the expense as a positive decimal (two decimal places) expressed in the field currency, e.g. 42.50. Must be at least 0.01.", "type": "string" }, "currency": { "description": "The currency code in ISO 4217 format, e.g., USD, EUR. Must be one of: USD, EUR, GBP, AUD, CAD, JPY, BYR, AED, AFN, ALL, AMD, ANG, AOA, ARS, AWG, AZN, BAM, BBD, BCH, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BZD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, FJD, FKP, GBX, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMM, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZWD", "type": "string" }, "description": { "description": "Free-text note describing what the expense was for (merchant, purpose). Optional but recommended so approvers understand the cost.", "type": "string" }, "approved_at": { "description": "Read-only UTC timestamp of when the expense was approved; null until it is approved via the approve action.", "type": "string" }, "rejected_at": { "description": "Read-only UTC timestamp of when the expense was rejected; null until it is rejected via the reject action.", "type": "string" }, "paid_at": { "description": "Read-only UTC timestamp of when the expense was marked as reimbursed/paid; null until it is paid via the mark-as-paid action.", "type": "string" }, "status": { "description": "The approval lifecycle state of the expense. One of: pending (awaiting approval, the default), approved, rejected, or paid (reimbursed). Only users who can manage expenses may set it directly; otherwise it is driven by the approve/reject/mark-as-paid actions.", "type": "string" }, "status_changed_by": { "description": "Read-only ULID id of the Employee who last changed the status (approved, rejected or paid it).", "type": "string" }, "status_explanation": { "description": "Optional free-text reason recorded when the status changes, e.g. why the expense was rejected. Sent as the explanation payload by the approve/reject/mark-as-paid actions.", "type": "string" }, "receipt_filename": { "description": "Original filename of the uploaded receipt. You can keep it empty or provide an intuitive name if there is a file.", "type": "string" }, "is_demo": { "description": "Read-only boolean flag; true when this is seeded demo/sample data rather than a real expense.", "type": "boolean" } }, "additionalProperties": true }, "ExpenseCategoryAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Unique human-readable name of the category, e.g. \"Transport\" or \"Accommodation\". Required, up to 255 characters.", "type": "string" }, "description": { "description": "Optional free-text explanation of what expenses belong in this category.", "type": "string" }, "requires_receipt": { "description": "Boolean flag: when true, expenses in this category must have a receipt file attached. Defaults to true.", "type": "boolean" }, "max_amount": { "description": "Optional maximum allowed amount (positive decimal) per expense in this category, used as a spending ceiling. Null means no limit.", "type": "string" }, "document_template_path": { "description": "Optional uploaded document template file (stored on the documents disk) used when generating paperwork for expenses in this category. Provide an absolute file URL only if you have one.", "type": "string" }, "document_template_path_name": { "description": "Original filename of the uploaded document template, if any.", "type": "string" }, "color": { "description": "Display color used for this category in the UI, e.g. a hex code or named color.", "type": "string" } }, "additionalProperties": true }, "ExpenseCategoryResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ExpenseCategoryAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ExpenseResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ExpenseAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "FeedbackAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "created_by_employee_id": { "description": "Read-only ULID of the Employee who authored this feedback. Set automatically; not writable.", "type": "string" }, "feedback_request_id": { "description": "Optional ULID foreign key to a feedback_requests row, linking this entry to a 360-degree feedback cycle. Null for standalone feedback.", "type": "number" }, "feedbackable_type": { "description": "Polymorphic subject type this feedback is about: \"employee\" or \"client\". Required.", "type": "string" }, "feedbackable_id": { "description": "ULID of the subject the feedback is about — an Employee or a Client depending on feedbackable_type. Required, max 26 chars.", "type": "string" }, "type": { "description": "Free-text label categorising the feedback interaction, e.g. \"1:1\", \"feedback\", \"review\". Required.", "type": "string" }, "given_at": { "description": "Date the feedback was given/recorded (YYYY-MM-DD). Required.", "type": "string" }, "notes": { "description": "The written content of the feedback. Required free text.", "type": "string" }, "is_visible_to_employee": { "description": "Boolean; when true the feedback is shared with and visible to the assessed employee, otherwise it stays private to managers.", "type": "boolean" }, "file": { "description": "Optional document attached to the feedback (stored on the documents disk). On read resolves to a temporary download URL when temporary_urls is requested; the original filename is kept in file_name.", "type": "string" }, "file_name": { "description": "Original filename of the attached document (file field). Populated automatically from the upload.", "type": "string" }, "audio_file": { "description": "Optional audio recording of the feedback (max 20MB), later transcribed. On read resolves to a temporary URL when temporary_urls is requested; original filename stored in audio_file_name.", "type": "string" }, "audio_file_name": { "description": "Original filename of the uploaded audio recording (audio_file field).", "type": "string" }, "transcription": { "description": "Read-only text transcription generated from the uploaded audio recording. Not writable.", "type": "string" }, "transcription_status": { "description": "Read-only status of the audio transcription process (e.g. pending/processing/completed). Not writable.", "type": "string" }, "created_by": { "description": "Read-only ULID of the User account that created the feedback. Set automatically; not writable.", "type": "string" } }, "additionalProperties": true }, "FeedbackResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/FeedbackAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "GoalAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) who owns this goal. Defaults to the current employee unless the caller manages goals or the goals of direct reports.", "type": "string" }, "created_by_employee_id": { "description": "Read-only ULID of the Employee who created the goal. Set automatically; not writable.", "type": "string" }, "updated_by_employee_id": { "description": "Read-only ULID of the Employee who last updated the goal. Set automatically; not writable.", "type": "number" }, "progress": { "description": "Completion percentage of the goal as a number, typically 0 to 100. Null means progress has not been recorded.", "type": "integer" }, "milestones": { "description": "JSON array of milestone items (sub-steps toward the goal), each typically holding a label and completion state. May be null or empty.", "type": "string" }, "name": { "description": "Short title of the goal (e.g. \"Ship v2 onboarding flow\"). Required when creating, max 255 characters.", "type": "string" }, "description": { "description": "Optional longer explanation of the goal, its context and success criteria. Free text up to 65535 characters.", "type": "string" }, "due_date": { "description": "Target date by which the goal should be achieved, as a date (YYYY-MM-DD). Required when creating.", "type": "string" }, "priority": { "description": "Importance of the goal. Allowed values: \"low\", \"medium\", \"high\". Required when creating.", "type": "string" }, "progress_status": { "description": "Lifecycle state of the goal. Allowed values: \"not started\", \"in progress\", \"completed\". May be null.", "type": "string" }, "category": { "description": "Time-horizon classification of the goal. Allowed values: \"short term\", \"long term\". May be null.", "type": "string" }, "path": { "description": "Optional supporting file attached to the goal (uploaded to S3). On read this resolves to a temporary download URL valid for 30 minutes; the original filename is stored in file_name.", "type": "string" }, "created_at": { "description": "Read-only timestamp of when the goal was created. Not writable.", "type": "string" } }, "additionalProperties": true }, "GoalResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/GoalAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "HolidayAttributes": { "type": "object", "properties": { "start_date": { "description": "First calendar day of the absence (date, YYYY-MM-DD), inclusive.", "type": "string" }, "end_date": { "description": "Last calendar day of the absence (date, YYYY-MM-DD), inclusive.", "type": "string" }, "status": { "description": "Lifecycle status: draft, approved, rejected, or cancelled.", "type": "string" }, "notes": { "description": "Optional free-text note the requester added, e.g. the reason for the absence.", "type": "string" }, "days_off": { "description": "Number of working days deducted from the balance for this request, computed automatically.", "type": "integer" } }, "additionalProperties": true }, "HolidayBalanceAttributes": { "type": "object", "properties": { "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) who owns this balance. Read-only: set when the balance is created and never reassigned.", "type": "string" }, "holiday_policy_id": { "description": "ULID foreign key to the HolidayPolicy (HolidayPolicyRepository) this balance is measured against, e.g. paid vacation or sick leave. Together with employee_id and year it uniquely identifies the balance.", "type": "string" }, "balance": { "description": "Remaining leave days currently available to the employee under this policy for the given year (float, in days; decimals allowed for accrual-based policies). Decreases as holidays are approved and increases with accrual or manual credit.", "type": "integer" }, "year": { "description": "Calendar year (four-digit integer, e.g. 2026) this balance applies to. A new row exists per year because allowances reset annually.", "type": "string" }, "initial_balance": { "description": "The full allowance of days originally granted for the year before any holidays were taken (float, in days). Used as the baseline for reporting how many days were consumed versus remaining.", "type": "integer" }, "deleted_at": { "description": "Soft-delete timestamp; when set, the balance is archived and excluded from active queries unless the with_trashed matcher is used.", "type": "string" } }, "additionalProperties": true }, "HolidayBalanceResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/HolidayBalanceAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "HolidayPolicyAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Human-readable name of the leave type, e.g. \"Paid Vacation\" or \"Sick Leave\". Required. Well-known names are auto-translated to the current locale when read.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this leave type covers and any usage rules, shown to employees when they request leave.", "type": "string" }, "type": { "description": "Category of the policy. One of: \"timeoff\" (regular paid/unpaid time off), \"national\" (public/legal holiday), \"specialRequest\" (event-driven leave such as bereavement or marriage), \"other\".", "type": "string" }, "method": { "description": "How the yearly allowance is granted. \"given\" means the full days_per_year is available immediately at the start of the year; \"accrual\" means days accumulate daily at days_per_year/365. Defaults to \"given\".", "type": "string" }, "applicable_contract_types": { "description": "Array of contract type names (matching ContractType.name) this policy applies to; when set, only employees on those contract types can use it. Leave empty/null to apply to all contract types.", "type": "array" }, "timesheet_symbol": { "description": "Short code used on generated timesheets to mark days taken under this policy, drawn from the SheetSymbols enum (e.g. \"Co\" = paid vacation, \"CoN\" = unpaid vacation, \"Cm\" = medical, \"Cp\" = paternity, \"Zlp\" = paid days off).", "type": "string" }, "days_per_year": { "description": "Number of leave days granted per calendar year (integer, in days). A value of 0 means the policy is unlimited. Changing this can recalculate existing employee balances unless update_balances is set to false.", "type": "integer" }, "carry_over": { "description": "Boolean; when true, days left unused at year-end roll over into the next year instead of being forfeited.", "type": "boolean" }, "waiting_period_days": { "description": "Number of days (integer) a newly hired employee must wait after their start date before they are allowed to book leave under this policy.", "type": "integer" }, "paid": { "description": "Boolean; when true this leave is paid (salary continues while off). When false the time off is unpaid.", "type": "boolean" }, "document_template_path": { "description": "Uploaded Word/PDF template file (stored on the documents disk) used to generate a leave-request document when an employee books this type of leave. Optional.", "type": "string" }, "document_template_path_name": { "description": "Original file name of the uploaded document_template_path, preserved for display and download.", "type": "string" }, "is_used": { "description": "Read-only boolean indicating whether any holiday has ever been requested against this policy. When true the policy cannot be deleted.", "type": "boolean" }, "allow_advance_booking": { "description": "Boolean; when true employees may book leave for dates before their allowance for that period has fully accrued.", "type": "boolean" }, "can_cancel_own_holidays_until_start_date": { "description": "Boolean; when true employees can self-cancel an approved holiday under this policy any time up to its start date, without manager involvement.", "type": "boolean" } }, "additionalProperties": true }, "HolidayPolicyResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/HolidayPolicyAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "HolidayResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/HolidayAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "InvoiceAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "paid_at": { "description": "Date the invoice was fully paid (Y-m-d), or null if it is not yet fully paid. Set automatically when the invoice is marked as paid; a non-null value together with a paid status means the invoice is settled.", "type": "string" }, "issue_date": { "description": "The date the invoice was issued, in Y-m-d format (e.g. 2023-10-15).", "type": "string" }, "due_date": { "description": "The date payment is due, in Y-m-d format (e.g. 2023-11-15); typically 30 days after the issue date.", "type": "string" }, "title": { "description": "Short human-readable title or summary of what the invoice is for (e.g. \"Web Development Services for October 2023\").", "type": "string" }, "invoice_number": { "description": "The tenant-unique invoice number/reference shown to the client (e.g. \"INV-2023-001\"). Must be unique within the current tenant.", "type": "string" }, "notes": { "description": "Free-text notes or payment terms printed on the invoice (e.g. \"Payment is due within 30 days.\"). Empty by default.", "type": "string" }, "status": { "description": "Lifecycle status of the invoice. One of: draft, sent, late, partially_paid, paid.", "type": "string" }, "client_id": { "description": "ULID foreign key of the Client (clients repository) that is billed by this invoice. Required.", "type": "string" }, "project_id": { "description": "Optional ULID foreign key of the Project (projects repository) this invoice relates to. If set, the project must belong to the same client as client_id.", "type": "string" }, "subtotal": { "description": "Net amount before tax, as a decimal number in the invoice currency (e.g. 1000.00).", "type": "integer" }, "total": { "description": "Gross amount the client owes including tax, as a decimal number in the invoice currency (e.g. 1190.00).", "type": "integer" }, "tax": { "description": "Tax amount included in the total, as a decimal number in the invoice currency (e.g. 190.00). Optional.", "type": "integer" }, "paid_amount": { "description": "Read-only. Cumulative amount already paid on this invoice, in the invoice currency; equals total once fully paid.", "type": "number" }, "disable_payment_reminders": { "description": "When true, automatic overdue payment reminder emails are suppressed for this invoice. Defaults to false.", "type": "boolean" }, "from_address": { "description": "JSON object holding the sender/issuer address details (the tenant's billing-from address) shown on the invoice.", "type": "object" }, "to_address": { "description": "JSON object holding the recipient/client address details (bill-to address) shown on the invoice.", "type": "object" }, "created_at": { "description": "Read-only timestamp when the invoice record was created.", "type": "string" }, "share_token": { "description": "Read-only public token used to build a shareable link that lets the client view this invoice without logging in. Generated by the share-invoice action.", "type": "string" }, "currency": { "description": "ISO currency code for all monetary amounts on this invoice (e.g. EUR, USD, RON, GBP). Defaults to EUR when not provided.", "type": "string" } }, "additionalProperties": true }, "InvoiceLineAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Description of the billed product or service for this line (e.g. \"Senior developer hours\"). Required, max 500 characters.", "type": "string" }, "quantity": { "description": "Number of units billed on this line as a decimal (e.g. 10 for 10 hours). Optional.", "type": "integer" }, "unit_price": { "description": "Price per single unit as a decimal in the parent invoice currency (e.g. 50.00). Optional.", "type": "number" }, "total": { "description": "Line total as a decimal in the parent invoice currency, normally quantity multiplied by unit_price (e.g. 500.00). Required.", "type": "integer" }, "invoice_id": { "description": "ULID foreign key of the parent Invoice (invoices repository) this line belongs to.", "type": "string" }, "created_at": { "description": "Read-only timestamp when this line item was created.", "type": "string" } }, "additionalProperties": true }, "InvoiceLineResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/InvoiceLineAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "InvoiceResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/InvoiceAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "JobAttributes": { "type": "object", "properties": { "id": { "description": "The unique ULID identifier of this job posting.", "type": "string" }, "title": { "description": "The job title as shown to applicants (e.g. \"Senior Laravel Developer\"). Required, plain text up to 255 characters. Creating a job consumes one job-posting quota slot.", "type": "string" }, "content": { "description": "The full job description body as HTML (responsibilities, requirements, benefits). Required; HTML is sanitized on save. Use the generate-description action to draft this from the job attributes.", "type": "string" }, "status": { "description": "The lifecycle status of the job. Allowed values: \"active\" (open and accepting candidates) or \"inactive\" (paused/closed). Defaults to active.", "type": "string" }, "started_at": { "description": "The date the job opening starts, as a date string (YYYY-MM-DD). Optional; used for scheduling and reporting, not for publication.", "type": "string" }, "ending_at": { "description": "The date the job opening closes, as a date string (YYYY-MM-DD). Optional; must be on or after started_at.", "type": "string" }, "location": { "description": "The free-text location of the role (e.g. \"Cluj-Napoca, Romania\"). Optional, up to 255 characters. See the unique-locations getter for values already in use.", "type": "string" }, "salary_min": { "description": "The lower bound of the offered salary range, as a non-negative decimal amount in the currency given by salary_currency. Optional.", "type": "string" }, "salary_max": { "description": "The upper bound of the offered salary range, as a non-negative decimal amount in the currency given by salary_currency. Optional; must be greater than or equal to salary_min.", "type": "string" }, "salary_currency": { "description": "The ISO 4217 currency code for salary_min and salary_max (e.g. \"EUR\", \"USD\", \"RON\"). Optional, 3-letter code.", "type": "string" }, "salary_type": { "description": "The period the salary range refers to. Allowed values: \"hourly\" or \"monthly\". Optional.", "type": "string" }, "contract_type": { "description": "The employment arrangement offered. Allowed values: \"employment_contract\" (standard employment with full labor rights and paid holidays), \"internship\" (temporary training role, often fixed duration), \"b2b_unpaid_holidays\" (B2B contractor agreement without paid holidays), \"b2b_paid_holidays\" (B2B contractor agreement with paid holidays). Optional.", "type": "string" }, "is_remote": { "description": "Boolean flag: true if the role can be performed fully remotely, false if it is on-site or hybrid tied to the location.", "type": "boolean" }, "hiring_manager_id": { "description": "The ULID foreign key of the Employee (see EmployeeRepository) responsible for this hiring process. Optional; must reference an existing employee.", "type": "string" }, "candidates_count": { "description": "Read-only integer count of candidates who have applied to this job.", "type": "number" }, "slug": { "description": "Read-only URL slug generated when the job is published; used to build the public careers-page URL.", "type": "string" }, "published_at": { "description": "Read-only datetime the job was published to the public careers page, or null if unpublished. Set via the publish/unpublish actions, not directly.", "type": "string" }, "public_configuration": { "description": "Read-only JSON object holding public-page display options (show_salary, show_projects, show_positions_levels) chosen when publishing.", "type": "string" }, "public_url": { "description": "Read-only fully-qualified URL of the public careers-page listing, or null when the job is not published.", "type": "string" }, "created_at": { "description": "Read-only datetime the job record was created.", "type": "string" }, "updated_at": { "description": "Read-only datetime the job record was last updated.", "type": "string" } }, "additionalProperties": true }, "JobResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/JobAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "KbPageAttributes": { "type": "object", "properties": { "teamspace_id": { "description": "ULID foreign key to the KbTeamspace (kb-teamspaces repository) this page belongs to; every page lives in exactly one teamspace and is only settable on create.", "type": "string" }, "parent_id": { "description": "ULID foreign key to another KbPage in the same teamspace that acts as this page's parent in the tree; null means the page sits at the teamspace root.", "type": "string" }, "position": { "description": "Zero-based integer sort order of this page among its siblings under the same parent; lower numbers appear first.", "type": "integer" }, "title": { "description": "The human-readable page title (max 255 chars) shown in the sidebar and search results.", "type": "string" }, "icon": { "description": "Optional icon shown next to the title, typically an emoji or icon identifier string (max 255 chars).", "type": "string" }, "cover_image": { "description": "Optional URL (max 2048 chars) of the banner cover image displayed at the top of the page.", "type": "string" }, "cover_position_y": { "description": "Vertical focal point of the cover image as an integer percentage from 0 (top) to 100 (bottom) for cropping.", "type": "integer" }, "is_template": { "description": "Boolean; true marks this page as a reusable template that can be cloned into new pages rather than a normal document.", "type": "boolean" }, "template_category": { "description": "For template pages, the grouping category. One of: hr, product, engineering, sales. Null for non-template pages.", "type": "string" }, "access_level": { "description": "How broadly the page is shared, controlling who can view it. One of: restricted (only owner + explicitly shared users), workspace (all teamspace members), anyone_with_link (public share link), published (live on the public help center). Changed via the set-link-access action.", "type": "string" }, "workspace_role": { "description": "The default role granted to teamspace members when access_level is workspace. Either \"view\" (read only) or \"edit\" (can modify). Changed via the set-link-access action.", "type": "string" }, "slug": { "description": "URL-safe slug generated when the page is published to the public help center; used to build its public URL, otherwise null.", "type": "string" }, "version": { "description": "Integer autosave revision counter incremented on every save; clients send it as base_version to detect concurrent-edit conflicts (409).", "type": "integer" }, "created_at": { "description": "Timestamp when the page was created.", "type": "string" }, "updated_at": { "description": "Timestamp of the last modification to the page.", "type": "string" } }, "additionalProperties": true }, "KbPageResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/KbPageAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "LeadActivityAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "lead_id": { "description": "ULID foreign key to the lead (leads table) this activity belongs to. Required when creating a note.", "type": "string" }, "type": { "description": "Read-only kind of activity. One of: \"note\", \"lead_created\", \"stage_changed\", \"owner_changed\", \"field_changed\", \"lost_reason_changed\", \"converted\", \"message_sent\", \"email_blocked\", \"interaction_logged\", \"follow_up_completed\". Creating via the API always produces \"note\"; all other types are emitted automatically by the system.", "type": "string" }, "body": { "description": "The text content of the activity — the note body for notes, or a human-readable summary for system events. Required when creating a note.", "type": "string" }, "meta": { "description": "Read-only JSON bag of event-specific structured details (e.g. {\"from_stage_id\", \"to_stage_id\"} on a stage change). Null for plain notes.", "type": "string" }, "causer_id": { "description": "Read-only ULID foreign key to the employee (employees table) who authored the note or triggered the event. Null for system-generated activities with no actor.", "type": "string" }, "created_at": { "description": "Read-only timestamp (ISO 8601) of when the activity occurred; the timeline is ordered by this.", "type": "string" }, "updated_at": { "description": "Read-only timestamp (ISO 8601) of when the activity record was last updated.", "type": "string" } }, "additionalProperties": true }, "LeadActivityResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/LeadActivityAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "LeadAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Full name of the lead (the prospect person), or the primary contact when the lead represents a company. Required, max 200 characters.", "type": "string" }, "email": { "description": "Primary email address of the lead. Optional; when present it is used for outreach and for the deliverability verification_status lookup.", "type": "string" }, "phone": { "description": "Contact phone number for the lead, free-form string (max 50 characters).", "type": "string" }, "linkedin_url": { "description": "Full URL of the lead's LinkedIn profile (e.g. https://www.linkedin.com/in/…). Used to enrich or import the lead from LinkedIn.", "type": "string" }, "location": { "description": "Free-text geographic location of the lead (city, region, or country).", "type": "string" }, "company_name": { "description": "Name of the company the lead works for or represents.", "type": "string" }, "company_website": { "description": "URL of the lead's company website.", "type": "string" }, "industry": { "description": "Free-text industry or vertical of the lead's company (e.g. \"SaaS\", \"Manufacturing\").", "type": "string" }, "company_size": { "description": "Headcount band of the lead's company. One of: \"1-10\", \"11-50\", \"51-200\", \"201-1000\", \"1000+\".", "type": "string" }, "title": { "description": "Job title of the lead at their company (e.g. \"Head of Sales\", \"CTO\").", "type": "string" }, "lead_stage_id": { "description": "Integer foreign key to the pipeline stage (lead-stages repository / lead_stages table) this lead currently sits in. Required. The stage must belong to the lead's campaign, or be a tenant-default stage (campaign_id NULL) when the lead has no campaign.", "type": "number" }, "campaign_id": { "description": "ULID foreign key to the outreach campaign (campaigns table) this lead is enrolled in. Null for leads not attached to any campaign.", "type": "number" }, "organization_id": { "description": "ULID foreign key to the linked organization, stored as a Client record (clients table). Associates the lead with an existing organization/company account. Null when unlinked.", "type": "number" }, "source": { "description": "Acquisition channel the lead came from. One of: \"manual\", \"linkedin\", \"cold_email\", \"referral\", \"event\", \"inbound\", \"hubspot\", \"other\". Defaults to \"manual\".", "type": "string" }, "owner_id": { "description": "ULID foreign key to the employee (employees table) who owns / is responsible for this lead. Null when unassigned.", "type": "string" }, "last_contacted_at": { "description": "Timestamp (ISO 8601) of the most recent outbound contact with the lead. Drives the stale-lead detection.", "type": "string" }, "lost_reason": { "description": "Why the lead was lost / disqualified; setting this marks the lead as lost. One of: \"no_budget\", \"not_interested\", \"competitor\", \"bad_timing\", \"no_response\", \"other\". Null while the lead is still open.", "type": "string" }, "expected_revenue": { "description": "Expected deal value, in the tenant default currency.", "type": "string" }, "expected_close_date": { "description": "Date (YYYY-MM-DD) the deal is expected to close. Used to bucket the lead in the revenue forecast.", "type": "string" }, "probability": { "description": "Manual win probability 0–100. Falls back to the AI fit_score when unset.", "type": "string" }, "fit_score": { "description": "Read-only AI-generated fit score 0–100 rating how well the lead matches the campaign's ideal customer profile. Produced by the score-lead action. Null until the lead has been scored.", "type": "string" }, "verification_status": { "description": "Read-only email deliverability verdict for the lead's email, read from the global verification cache (e.g. \"valid\", \"invalid\", \"risky\"). Null when the address has never been verified.", "type": "string" }, "overdue_follow_up": { "description": "Read-only boolean, index-only kanban badge flag: true when the lead has at least one pending follow-up whose due date is before today.", "type": "boolean" }, "due_today_follow_up": { "description": "Read-only boolean, index-only kanban badge flag: true when the lead has at least one pending follow-up due today.", "type": "boolean" }, "enriched_at": { "description": "Timestamp of the last enrichment run. External enrichers (Hermes, MCP callers) write this when pushing fresh research into the lead.", "type": "string" }, "converted_to_client_id": { "description": "Read-only ULID foreign key to the Client (clients table) this lead was converted into once won. Set by the convert-to-client action. Null while the lead is not converted.", "type": "number" }, "converted_at": { "description": "Read-only timestamp (ISO 8601) marking when the lead was converted into a client. Null while the lead is not converted.", "type": "string" }, "drip_status": { "description": "Read-only status of the lead in its automated drip email sequence. One of: \"active\", \"paused\", \"stopped_replied\" (auto-stopped because the lead replied), \"completed\". Null when the lead is not enrolled in a drip. Controlled by the pause-sequence / resume-sequence actions.", "type": "string" }, "drip_paused_at": { "description": "Read-only timestamp (ISO 8601) of when the lead's drip sequence was paused. Null when the sequence is not paused.", "type": "string" }, "tags": { "description": "Array of free-form string tags applied to the lead for segmentation and filtering.", "items": { "type": "string" }, "type": "array" }, "metadata": { "description": "Free-form JSON bag for external writers (API, MCP). Arbitrary nested structure — Growee stores it as-is and does not interpret it.", "type": "string" }, "custom_fields": { "description": "Field: custom_fields. ", "type": "string" }, "created_by": { "description": "Read-only ULID foreign key to the User (users table) who created the lead.", "type": "string" }, "updated_by": { "description": "Read-only ULID foreign key to the User (users table) who last updated the lead.", "type": "string" }, "archived_at": { "description": "Read-only timestamp (ISO 8601) of when the lead was archived. Null while the lead is active. Set by the archive-lead / unarchive-lead actions.", "type": "string" }, "archived_by": { "description": "Read-only ULID foreign key to the employee (employees table) who archived the lead. Null while the lead is active.", "type": "string" }, "status_before_archive": { "description": "Read-only snapshot of the lead's state before it was archived, used to restore it on unarchive. Null while the lead is active.", "type": "string" }, "created_at": { "description": "Read-only timestamp (ISO 8601) of when the lead record was created.", "type": "string" }, "updated_at": { "description": "Read-only timestamp (ISO 8601) of when the lead record was last updated.", "type": "string" } }, "additionalProperties": true }, "LeadResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/LeadAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "LeadStageAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "number" }, "name": { "description": "Display name of the pipeline stage / kanban column (e.g. \"New\", \"Contacted\", \"Qualified\"). Required, max 100 characters, and unique within the stage's campaign scope.", "type": "string" }, "campaign_id": { "description": "ULID foreign key to the campaign (campaigns table) this stage belongs to. Null makes it a tenant-default stage shared by leads with no campaign. Set only on creation; it cannot be changed afterwards.", "type": "number" }, "position": { "description": "Zero-based integer sort order of the stage within its pipeline; lower numbers appear first. Required.", "type": "integer" }, "color": { "description": "Optional UI color for the stage column (a color name or hex string, max 50 characters).", "type": "string" }, "description": { "description": "Optional free-text description explaining what the stage represents.", "type": "string" }, "created_at": { "description": "Read-only timestamp (ISO 8601) of when the stage was created.", "type": "string" }, "updated_at": { "description": "Read-only timestamp (ISO 8601) of when the stage was last updated.", "type": "string" } }, "additionalProperties": true }, "LeadStageResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/LeadStageAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "LevelAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "name": { "description": "Human-readable name of the seniority level, e.g. \"Junior\", \"Mid\", \"Senior\" or \"Lead\". Required on create; unique per tenant by convention.", "type": "string" }, "description": { "description": "Optional free-text explanation of what this seniority level means or the expectations at this tier. Nullable string.", "type": "string" }, "created_at": { "description": "Read-only datetime when the level was created.", "type": "string" }, "is_used": { "description": "Read-only boolean flag; true when at least one employee or evaluation currently references this level. False means the level is unused and safe to delete.", "type": "boolean" } }, "additionalProperties": true }, "LevelResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/LevelAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "MeetingAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "meetingable_type": { "description": "Polymorphic subject type the meeting was with: \"employee\" or \"client\". Required when creating.", "type": "string" }, "meetingable_id": { "description": "ULID of the subject the meeting was with — an Employee or a Client depending on meetingable_type. Required when creating, max 26 chars.", "type": "string" }, "met_at": { "description": "Date the meeting took place (YYYY-MM-DD). Defaults to today when not provided on creation.", "type": "string" }, "notes": { "description": "Free-text notes captured about the meeting. May be null.", "type": "string" }, "calendar_event_id": { "description": "Optional identifier of an external calendar event this meeting is linked to (e.g. a Google Calendar event id). Max 255 chars, may be null.", "type": "number" }, "calendar_event_title": { "description": "Optional title of the linked external calendar event. Max 500 chars, may be null.", "type": "string" }, "created_by": { "description": "Read-only ULID of the User account that logged the meeting. Set automatically; not writable.", "type": "string" }, "created_by_employee_id": { "description": "Read-only ULID of the Employee who logged the meeting. Set automatically; not writable.", "type": "string" } }, "additionalProperties": true }, "MeetingResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/MeetingAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "OfferAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "number" }, "organization_id": { "description": "ULID foreign key to the client this offer is addressed to (references the ClientRepository / clients table, also surfaced as an organization). Required on create and cannot be changed afterwards.", "type": "string" }, "lead_id": { "description": "Optional ULID foreign key to the sales lead this offer originated from (references the LeadRepository / leads table). Null when the offer is not tied to a specific lead.", "type": "string" }, "signer_contact_id": { "description": "Optional ULID foreign key to the client contact (person) designated to sign this offer (references the ClientContactRepository / client_contacts table). Used to pre-fill signer details when sending for signature.", "type": "string" }, "signer_name": { "description": "Full name of the person who will sign the offer. Free text, up to 255 characters; typically taken from the signer contact but can be set manually.", "type": "string" }, "signer_email": { "description": "Email address of the signer, where the e-signature request is delivered. Must be a valid email.", "type": "string" }, "title": { "description": "Human-readable title of the offer shown to the client (e.g. \"Website redesign proposal\"). Required, up to 255 characters.", "type": "string" }, "offer_number": { "description": "Optional human-facing reference number for the offer (e.g. \"OFF-2026-001\"), up to 100 characters. Null if not assigned.", "type": "number" }, "currency": { "description": "ISO 4217 three-letter currency code (exactly 3 characters, e.g. \"EUR\", \"USD\") in which all line-item prices and totals are expressed. Defaults to \"EUR\".", "type": "string" }, "valid_until": { "description": "Date (Y-m-d) until which the offer remains valid; after this date it may be treated as expired. Null when the offer has no expiry.", "type": "string" }, "terms": { "description": "Free-text terms and conditions displayed on the offer (e.g. payment terms, scope caveats). Null when none are set.", "type": "string" }, "notes": { "description": "Free-text internal or client-facing notes attached to the offer. Null when none are set.", "type": "string" }, "status": { "description": "Read-only lifecycle status of the offer, one of: draft, sent, viewed, signed, declined, expired. Advanced by the system (e.g. by sending for signature or when the signer acts), never set directly. Only draft offers are editable.", "type": "string" }, "subtotal": { "description": "Read-only sum of all line-item amounts before VAT, in the offer currency (decimal, 2 places). Recalculated automatically whenever line items change.", "type": "string" }, "vat_amount": { "description": "Read-only total VAT amount across all line items, in the offer currency (decimal, 2 places). Recalculated automatically whenever line items change.", "type": "number" }, "total": { "description": "Read-only grand total (subtotal + vat_amount) in the offer currency (decimal, 2 places). Recalculated automatically whenever line items change.", "type": "string" }, "envelope_id": { "description": "Read-only identifier of the e-signature envelope created when the offer is sent for signature. Null until the offer has been sent for signing.", "type": "string" }, "sent_at": { "description": "Read-only datetime when the offer was sent to the client for signature. Null until sent.", "type": "string" }, "viewed_at": { "description": "Read-only datetime when the client first viewed the offer. Null until viewed.", "type": "string" }, "signed_at": { "description": "Read-only datetime when the offer was signed by the client. Null until signed.", "type": "string" }, "declined_at": { "description": "Read-only datetime when the client declined the offer. Null unless declined.", "type": "string" }, "tenant_id": { "description": "Read-only tenant (workspace) that owns this offer. Set automatically from the current tenant context.", "type": "string" }, "created_by": { "description": "Read-only ULID foreign key to the user who created the offer (references the UserRepository / users table).", "type": "string" }, "created_at": { "description": "Read-only datetime when the offer record was created.", "type": "string" }, "updated_at": { "description": "Read-only datetime when the offer record was last updated.", "type": "string" } }, "additionalProperties": true }, "OfferResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/OfferAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "PaginationLinks": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "filters": { "description": "Applied filters echo, when present." } } }, "PaginationMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "integer" }, "path": { "type": "string" }, "per_page": { "type": "integer" }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "integer" } }, "additionalProperties": true }, "PositionAttributes": { "type": "object", "properties": { "id": { "description": "The ULID primary key of the position record.", "type": "string" }, "name": { "description": "The title of the job position, e.g. \"Senior Backend Developer\"; this is the human-facing name shown when assigning the position to an employee.", "type": "string" }, "description": { "description": "Optional free-text description of the position's responsibilities or scope.", "type": "string" }, "department_id": { "description": "Optional ULID foreign key referencing the department this position belongs to (the DepartmentRepository / departments table); null if the position is not tied to a department.", "type": "string" }, "is_used": { "description": "Read-only boolean; true when at least one employee or evaluation currently references this position, meaning it cannot be safely deleted.", "type": "boolean" } }, "additionalProperties": true }, "PositionResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/PositionAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ProjectAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "budget": { "description": "The monetary budget for the project, expressed in the project currency. Interpreted according to budget_type (weekly/monthly/yearly recurring amount, or a single fixed total). Drives budget-basis revenue and the remaining/overspend figures in profitability reports. Only visible to users who can manage salaries.", "type": "string" }, "budget_type": { "description": "How the budget value recurs. One of: weekly, monthly, yearly, fixed — weekly, monthly and yearly treat budget as a recurring amount prorated across the reporting window, while fixed treats budget as a single total for the whole engagement.", "type": "string" }, "billing_model": { "description": "The commercial model that determines how revenue is recognised for this project. One of: retainer, fixed_price, time_and_materials, ppc_passthrough, revenue_share, internal — retainer/fixed_price recognise revenue from the budget, time_and_materials from billable timesheet amounts, ppc_passthrough and revenue_share are pass-through/share arrangements, and internal marks non-billable internal work counted only as cost. Only visible to users who can manage salaries.", "type": "string" }, "revenue_share_percent": { "description": "The share of revenue retained by the company, as a percentage from 0 to 100. Only meaningful for revenue_share billing_model projects. Only visible to users who can manage salaries.", "type": "string" }, "currency": { "description": "The 3-letter ISO 4217 currency code (e.g. EUR, USD, RON) in which the budget and billed rates are denominated. If null, the project falls back to the client preferred currency and then the tenant default currency. Only visible to users who can manage salaries.", "type": "string" }, "starts_at": { "description": "The date (Y-m-d) the engagement starts. Bounds the active window used when prorating recurring budgets and computing costs; if null the project creation date is treated as the effective start. Must be on or before ends_at.", "type": "string" }, "ends_at": { "description": "The date (Y-m-d) the engagement ends, or null for an open-ended project. When set and in the past, the project is treated as ended in profitability reports. Must be on or after starts_at.", "type": "string" }, "name": { "description": "The human-readable name of the project. Required on create and must be unique within the tenant.", "type": "string" }, "website": { "description": "An optional URL for the project or the client work (e.g. the delivered site). Trailing slashes are stripped on save; max 255 characters.", "type": "string" }, "client_name": { "description": "Read-only convenience field: the company_name of the client this project belongs to, resolved from the client relationship.", "type": "string" }, "description": { "description": "Free-text notes describing the project scope or context.", "type": "string" }, "created_at": { "description": "Read-only timestamp of when the project record was created.", "type": "string" }, "client_id": { "description": "ULID foreign key to the Client (ClientRepository) this project is delivered for and billed to. Required on create; must reference an existing client.", "type": "string" }, "is_used": { "description": "Read-only boolean flag; true when the project has at least one logged timesheet, meaning it is in active use and cannot be deleted.", "type": "boolean" }, "archived": { "description": "Read-only boolean; true when the project has been archived (soft-hidden from active lists) rather than deleted.", "type": "boolean" }, "logo_path": { "description": "Field: logo_path. -- Important: This should be an absolute path or URL to the file that can be read.", "type": "string" } }, "additionalProperties": true }, "ProjectEmployeeAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "number" }, "project_id": { "description": "ULID foreign key to the Project (ProjectRepository) this membership belongs to. Required on create; must reference an existing project.", "type": "string" }, "employee_id": { "description": "ULID foreign key to the Employee (EmployeeRepository) assigned to the project. Required on create; must reference an existing employee.", "type": "string" }, "currency": { "description": "This is the currency for this employee's billed rate and internal cost on this project. If not set, the company's default currency will be used.", "type": "string" }, "weekly_allocation_hours": { "description": "This is the number of hours this employee is allocated to work on this project each week. Default is 40 hours.", "type": "integer" }, "internal_hourly_cost_for_project": { "description": "This is the internal hourly cost for this employee's work on this project. This is not visible to the client.", "type": "string" }, "cost_type": { "description": "How this member is costed on the project. Can be hourly, monthly. When set to monthly, a fixed monthly cost (prorated by allocation) is used instead of hourly timesheet cost.", "type": "string" }, "internal_monthly_cost_for_project": { "description": "The fixed monthly internal cost for this member on this project. Only used when cost_type is monthly.", "type": "string" }, "billed_rate": { "description": "This is the hourly rate that will be billed to the client for this employee's work on this project.", "type": "integer" } }, "additionalProperties": true }, "ProjectEmployeeResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ProjectEmployeeAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ProjectResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/ProjectAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "TaskAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "project_id": { "description": "ULID foreign key to the parent Project (ProjectRepository) this task belongs to. Required on create; must reference an existing project.", "type": "string" }, "name": { "description": "The human-readable name of the task (the label shown when logging time). Required on create; up to 1024 characters.", "type": "string" }, "description": { "description": "Optional free-text description giving more detail about the task.", "type": "string" }, "created_by": { "description": "Read-only ULID of the User who created the task.", "type": "string" }, "archived": { "description": "Read-only boolean; true when the task has been archived (hidden from active lists) rather than deleted.", "type": "boolean" } }, "additionalProperties": true }, "TaskResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/TaskAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "TimesheetAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "employee_id": { "description": "ULID of the Employee (EmployeeRepository) this time entry belongs to. Defaults to the current employee when omitted; only users allowed to manage timesheets may log time for another employee.", "type": "string" }, "project_id": { "description": "ULID of the Project (ProjectRepository) the worked time is attributed to. Required when creating an entry.", "type": "string" }, "task_id": { "description": "ULID of the Task (TaskRepository) within the project that the time was spent on. Required when creating an entry.", "type": "string" }, "worked_minutes": { "description": "Duration of the logged time in whole minutes (e.g. 90 means one hour and a half). Divide by 60 to get hours.", "type": "integer" }, "is_break": { "description": "When true the entry represents a break rather than billable work; break entries are excluded from worked-hours totals.", "type": "boolean" }, "description": { "description": "Optional free-text note describing what was worked on during this time entry.", "type": "string" }, "date": { "description": "Calendar day the work was performed, formatted as Y-m-d (date only, no time). Required when creating an entry.", "type": "string" }, "created_at": { "description": "Read-only timestamp of when the timesheet entry was created (ISO 8601).", "type": "string" }, "timer_started_at": { "description": "Read-only ISO 8601 timestamp set while a live timer is running for this entry; null when no timer is active (the timer is controlled via the start-timer and stop-timer actions).", "type": "string" }, "billed_hourly_rate": { "description": "Read-only hourly rate (in the tenant currency) billed to the client for this employee's time, used for profitability and invoicing. Only visible to users with the managePayroll permission.", "type": "string" } }, "additionalProperties": true }, "TimesheetResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/TimesheetAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "TimesheetSubmissionAttributes": { "type": "object", "properties": { "id": { "description": "Field: id. ", "type": "string" }, "employee_id": { "description": "Field: employee_id. ", "type": "string" }, "week_start_date": { "description": "Field: week_start_date. ", "type": "string" }, "status": { "description": "Field: status. ", "type": "string" }, "submitted_at": { "description": "Field: submitted_at. ", "type": "string" }, "approved_at": { "description": "Field: approved_at. ", "type": "string" }, "rejected_at": { "description": "Field: rejected_at. ", "type": "string" }, "status_changed_by": { "description": "Field: status_changed_by. ", "type": "string" }, "status_explanation": { "description": "Field: status_explanation. ", "type": "string" } }, "additionalProperties": true }, "TimesheetSubmissionResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/TimesheetSubmissionAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } }, "ValidationError": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable summary of the first error." }, "errors": { "type": "object", "description": "Map of field name to an array of error messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "WorkLocationAttributes": { "type": "object", "properties": { "name": { "description": "The work location name, e.g. \"Cluj Office\" or \"Remote\". Required plain string, unique per tenant in practice.", "type": "string" }, "description": { "description": "Optional free-text description with details such as address or notes about the location. Nullable string.", "type": "string" }, "is_used": { "description": "Read-only boolean flag indicating whether any employees are currently assigned to this location; true means it cannot be safely deleted.", "type": "boolean" } }, "additionalProperties": true }, "WorkLocationResource": { "type": "object", "properties": { "id": { "type": "string", "description": "ULID identifier." }, "type": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/WorkLocationAttributes" }, "relationships": { "type": "object", "description": "Present when the `related` query parameter requests relationships." }, "meta": { "type": "object", "description": "Per-record authorization flags (authorizedToShow, authorizedToUpdate, ...)." } } } }, "responses": { "Unauthenticated": { "description": "Missing or invalid API key - also returned when the key has an IP allowlist and the request comes from a non-allowed address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key (or its user) lacks the permission required by this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No record with this ID is visible to the authenticated user in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "The payload failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }