{ "openapi": "3.1.0", "info": { "title": "Aiwyn API", "version": "1.0.0", "description": "# Welcome to Aiwyn API\n\nThe Aiwyn API provides programmatic access to our comprehensive suite of financial automation tools.\nBuild powerful integrations and automate your accounting workflows with our RESTful APIs.\n\n## Key Features\n\n- ๐Ÿ” **Secure Authentication** - JWT API key exchange for short-lived bearer JWTs\n- ๐Ÿ“Š **Real-time Data** - Access up-to-date financial information\n- ๐Ÿš€ **High Performance** - Low latency, high throughput API infrastructure\n- ๐Ÿ“š **Comprehensive Coverage** - Full access to clients, engagements, expenses, and more\n- ๐Ÿ› ๏ธ **Developer-Friendly** - Extensive documentation, SDKs, and code examples\n\n## API Versioning\n\nWe use URL versioning for our APIs. The current version is `v1`. All endpoints are prefixed with the version number.\n\n## Testing Enviornments\n- **Sandbox** runs the latest development branch.\n- **Staging** mirrors production behavior and stability.\n", "contact": { "name": "Aiwyn API Support", "email": "api-support@aiwyn.ai", "url": "https://www.aiwyn.ai/" } }, "servers": [ { "url": "https://demo.api.aiwyn.ai", "description": "Sandbox" }, { "url": "https://staging.api.aiwyn.app", "description": "Staging" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "Authentication endpoints for obtaining access tokens and managing API keys.\n", "x-displayName": "๐Ÿ” Authentication" }, { "name": "Client", "description": "Manage client records, profiles, and related operations.\n", "x-displayName": "๐Ÿ‘ค Client" }, { "name": "Client Group", "description": "Manage client group records and associated staff assignments.\n", "x-displayName": "๐Ÿ‘ฅ Client Group" }, { "name": "Contact", "description": "Manage contact information and relationships for clients.\n", "x-displayName": "๐Ÿ“‡ Contact" }, { "name": "Client Business Entity", "description": "Manage client business entities used for client categorization and structure.\n", "x-displayName": "๐Ÿงฉ Client Business Entity" }, { "name": "Contact Client", "description": "Manage contact โ†” client relationship records.\n", "x-displayName": "๐Ÿ”— Contact Client" }, { "name": "Contact Info", "description": "Manage contact information records (address, email, phone, etc.).\n", "x-displayName": "๐Ÿชช Contact Info" }, { "name": "Department", "description": "Manage departments and organizational units.\n", "x-displayName": "๐Ÿข Department" }, { "name": "Industry", "description": "Manage industry classifications.\n", "x-displayName": "๐Ÿญ Industry" }, { "name": "Job", "description": "Manage jobs/projects.\n", "x-displayName": "๐Ÿงพ Job" }, { "name": "Job Template", "description": "Manage job templates.\n", "x-displayName": "๐Ÿงฉ Job Template" }, { "name": "Office", "description": "Manage office locations.\n", "x-displayName": "๐Ÿฌ Office" }, { "name": "Org", "description": "Manage organizations.\n", "x-displayName": "๐Ÿ› Org" }, { "name": "Service Line", "description": "Manage service line classifications.\n", "x-displayName": "๐Ÿงท Service Line" }, { "name": "Staff", "description": "Manage staff accounts, roles, and permissions.\n", "x-displayName": "๐Ÿง‘โ€๐Ÿ’ผ Staff" }, { "name": "Payments", "description": "Handle incoming and outgoing payments.\n", "x-displayName": "๐Ÿ’ณ Payments" }, { "name": "Billing", "description": "Manage billing cycles, statements, and billing configurations.\n", "x-displayName": "๐Ÿงพ Billing" }, { "name": "Invoices", "description": "Create, send, and manage invoices.\n", "x-displayName": "๐Ÿ“„ Invoices" }, { "name": "Projects", "description": "Handle engagements, projects, and workflow tracking.\n", "x-displayName": "๐Ÿ“‹ Projects" }, { "name": "Time Management", "description": "Track and manage billable and non-billable time entries.\n", "x-displayName": "โฑ Time Management" }, { "name": "Engagement", "description": "Create, send, and track engagement.\n", "x-displayName": "โœ‰๏ธ Engagement" }, { "name": "Records", "description": "Create, update, and manage entity records across standard and custom record types.\n\nThe Records API provides:\n- **Record Operations** - Create, update, and delete records for any entity type\n- **Schema Discovery** - Query available entity types and their field definitions\n- **Custom Record Types** - Define and manage custom record type schemas\n", "x-displayName": "๐Ÿ—ƒ๏ธ Records" }, { "name": "Event Subscriptions", "description": "Create and manage webhook subscriptions for entity events.\n\nThe Event Subscriptions API provides:\n- **Webhook Management** - Create, update, and deactivate webhook subscriptions\n- **Event Filtering** - Subscribe to specific entity types and operations (CREATE, UPDATE, DELETE)\n- **Security** - Retrieve webhook signing secrets for payload verification\n", "x-displayName": "๐Ÿ”” Event Subscriptions" }, { "name": "File", "description": "Download and access files associated with records and documents.\n", "x-displayName": "๐Ÿ“ File" } ], "paths": { "/v1/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "Generate API Token", "description": "Exchange a **JWT API key** for a **short-lived bearer JWT** used to access Product APIs. \n\n**Headers:**\n- `Tenant`: your tenant schema (recommended; required by many endpoints)\n", "operationId": "generateApiToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jwtApiKey": { "type": "string", "description": "JWT API key obtained from Aiwyn Support." } }, "required": [ "jwtApiKey" ] } } } }, "responses": { "200": { "description": "API Token generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Bearer JWT for accessing Product APIs." } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gql/v1/draft_invoice_histories": { "post": { "tags": [ "Billing" ], "summary": "List draft invoice histories", "description": "**Retrieve draft invoice histories with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nProvides paginated access to draft invoice history records.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/draft_invoice_histories' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getDraftInvoiceHistoriesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved draft invoice histories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInvoiceHistoryListResponse" }, "examples": { "successful_response": { "summary": "Draft invoice histories with client and draft invoice details", "value": { "draftInvoices": [ { "clientId": 7720, "invoiceId": 125890, "jobId": 2514, "client": { "active": true, "clientRef": "TF-2024-789", "name": "TechFlow Enterprises", "pmsRef": "240815" }, "draftInvoice": { "approvedAt": "2024-03-15T14:32:18+00:00", "arTranId": 125890, "approverStaffId": 301, "approvedByStaffId": 301, "invoiceId": 125890, "isActive": true, "pms_invoice_number": "INV-2024-4850", "status": "APPROVED" } } ], "total": { "aggregate": { "count": 94 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/draft_invoice_histories/search": { "post": { "tags": [ "Billing" ], "summary": "Search draft invoice histories", "description": "**Advanced draft invoice history filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nSupports client, invoice, job filtering and draftInvoice approvedAt date range.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/draft_invoice_histories/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"clientId\": {\n \"_in\": [1001, 1002]\n }\n },\n {\n \"jobId\": {\n \"_in\": [2001, 2002]\n }\n }\n ]\n },\n {\n \"active\": {\n \"_eq\": true\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"activityType\": {\n \"_in\": [\n \"DRAFT_INVOICE_CREATED\",\n \"DRAFT_INVOICE_RECONCILED\"\n ]\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"clientId\": \"asc\"\n },\n {\n \"createdAt\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "filterDraftInvoiceHistoriesDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex filtering", "example": { "_and": [ { "_or": [ { "clientId": { "_in": [ 1001, 1002 ] } }, { "jobId": { "_in": [ 2001, 2002 ] } } ] }, { "active": { "_eq": true } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "activityType": { "_in": [ "DRAFT_INVOICE_CREATED", "DRAFT_INVOICE_RECONCILED" ] } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications", "example": [ { "clientId": "asc" }, { "createdAt": "desc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered draft invoice histories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInvoiceHistoryListResponse" }, "examples": { "successful_response": { "summary": "Filtered draft invoice histories", "value": { "draftInvoices": [ { "clientId": 7720, "invoiceId": 125890, "jobId": 2514, "client": { "active": true, "clientRef": "TF-2024-789", "name": "TechFlow Enterprises", "pmsRef": "240815" }, "draftInvoice": { "approvedAt": "2024-03-15T14:32:18+00:00", "arTranId": 125890, "approverStaffId": 301, "approvedByStaffId": 301, "invoiceId": 125890, "isActive": true, "pms_invoice_number": "INV-2024-4850", "status": "APPROVED" } } ], "total": { "aggregate": { "count": 12 } } } } } } } }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/draft_invoice/{id}": { "get": { "tags": [ "Billing" ], "summary": "Get draft invoice by ID", "description": "**Retrieve a specific draft invoice by its unique identifier**\n\nThis endpoint provides detailed draft invoice information including:\n- Complete draft invoice details and line items\n- Draft status and review information\n- Client and project relationships\n- Tax calculations and compliance data\n- Review history and approval workflow\n- Document generation and delivery preparation\n\n**Draft Invoice Management Features:**\n- Draft invoice lifecycle tracking\n- Review and approval workflow\n- Tax calculation and compliance\n- Client relationship integration\n- Document preparation and delivery setup\n\n**Draft Invoice Details Include:**\n- Draft invoice number and reference\n- Draft status and review status\n- Client and project information\n- Line items and amounts\n- Tax calculations\n- Review history\n\n**Business Applications:**\n- Draft invoice review and approval\n- Tax compliance verification\n- Client billing preparation\n- Revenue recognition planning\n- Document generation preparation\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/draft_invoice/56789' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 56789,\n \"draftNumber\": \"DRAFT-2024-001\",\n \"reference\": \"Q4-AUDIT-DRAFT-2024\",\n \"status\": \"UNDER_REVIEW\",\n \"reviewStatus\": \"PENDING_APPROVAL\",\n \"clientId\": 789,\n \"clientName\": \"Acme Corporation\",\n \"clientEmail\": \"billing@acme.com\",\n \"projectId\": 67890,\n \"projectName\": \"Q4 Financial Audit\",\n \"preparedDate\": \"2024-12-01T00:00:00Z\",\n \"proposedIssueDate\": \"2024-12-15T00:00:00Z\",\n \"proposedDueDate\": \"2025-01-15T23:59:59Z\",\n \"subtotal\": 20000.00,\n \"taxAmount\": 2000.00,\n \"totalAmount\": 22000.00,\n \"currency\": \"USD\",\n \"lineItems\": [\n {\n \"id\": 1,\n \"description\": \"Financial Statement Audit\",\n \"quantity\": 80,\n \"unitPrice\": 250.00,\n \"amount\": 20000.00,\n \"taxRate\": 0.10,\n \"notes\": \"Includes fieldwork and report preparation\"\n }\n ],\n \"reviewHistory\": [\n {\n \"id\": 1,\n \"reviewerId\": 123,\n \"reviewerName\": \"John Smith\",\n \"reviewDate\": \"2024-12-05T10:30:00Z\",\n \"status\": \"APPROVED\",\n \"comments\": \"All calculations verified and approved\"\n },\n {\n \"id\": 2,\n \"reviewerId\": 124,\n \"reviewerName\": \"Jane Doe\",\n \"reviewDate\": \"2024-12-06T14:15:00Z\",\n \"status\": \"PENDING_APPROVAL\",\n \"comments\": \"Pending final review\"\n }\n ],\n \"notes\": \"Draft invoice for Q4 audit services - pending final review\",\n \"createdAt\": \"2024-12-01T09:00:00Z\",\n \"updatedAt\": \"2024-12-06T14:15:00Z\"\n}\n```\n", "operationId": "getDraftInvoiceById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the draft invoice", "schema": { "type": "integer", "minimum": 1 }, "example": 56789 } ], "responses": { "200": { "description": "Draft invoice details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique draft invoice identifier", "example": 56789 }, "draftNumber": { "type": "string", "description": "Draft invoice number", "example": "DRAFT-2024-001" }, "reference": { "type": "string", "description": "Draft invoice reference or description", "example": "Q4-AUDIT-DRAFT-2024" }, "status": { "type": "string", "description": "Draft invoice status", "enum": [ "DRAFT", "UNDER_REVIEW", "APPROVED", "REJECTED", "CONVERTED" ], "example": "UNDER_REVIEW" }, "reviewStatus": { "type": "string", "description": "Review status", "enum": [ "NOT_STARTED", "IN_REVIEW", "PENDING_APPROVAL", "APPROVED", "REJECTED" ], "example": "PENDING_APPROVAL" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "clientName": { "type": "string", "description": "Client name", "example": "Acme Corporation" }, "clientEmail": { "type": "string", "description": "Client billing email", "example": "billing@acme.com" }, "projectId": { "type": "integer", "description": "Associated project identifier", "example": 67890 }, "projectName": { "type": "string", "description": "Project name", "example": "Q4 Financial Audit" }, "preparedDate": { "type": "string", "format": "date-time", "description": "Date when draft was prepared", "example": "2024-12-01T00:00:00Z" }, "proposedIssueDate": { "type": "string", "format": "date-time", "description": "Proposed invoice issue date", "example": "2024-12-15T00:00:00Z" }, "proposedDueDate": { "type": "string", "format": "date-time", "description": "Proposed invoice due date", "example": "2025-01-15T23:59:59Z" }, "subtotal": { "type": "number", "format": "decimal", "description": "Draft subtotal before tax", "example": 20000 }, "taxAmount": { "type": "number", "format": "decimal", "description": "Total tax amount", "example": 2000 }, "totalAmount": { "type": "number", "format": "decimal", "description": "Total draft amount including tax", "example": 22000 }, "currency": { "type": "string", "description": "Draft currency code", "example": "USD" }, "lineItems": { "type": "array", "description": "Draft invoice line items", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Line item identifier", "example": 1 }, "description": { "type": "string", "description": "Line item description", "example": "Financial Statement Audit" }, "quantity": { "type": "number", "format": "decimal", "description": "Quantity of units", "example": 80 }, "unitPrice": { "type": "number", "format": "decimal", "description": "Unit price", "example": 250 }, "amount": { "type": "number", "format": "decimal", "description": "Line item total amount", "example": 20000 }, "taxRate": { "type": "number", "format": "decimal", "description": "Tax rate applied", "example": 0.1 }, "notes": { "type": "string", "description": "Additional notes for line item", "example": "Includes fieldwork and report preparation" } } } }, "reviewHistory": { "type": "array", "description": "Review history for this draft invoice", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Review record identifier", "example": 1 }, "reviewerId": { "type": "integer", "description": "Reviewer identifier", "example": 123 }, "reviewerName": { "type": "string", "description": "Reviewer name", "example": "John Smith" }, "reviewDate": { "type": "string", "format": "date-time", "description": "Review date", "example": "2024-12-05T10:30:00Z" }, "status": { "type": "string", "description": "Review status", "enum": [ "APPROVED", "REJECTED", "PENDING_APPROVAL", "COMMENTS" ], "example": "APPROVED" }, "comments": { "type": "string", "description": "Review comments", "example": "All calculations verified and approved" } } } }, "notes": { "type": "string", "description": "Additional notes or terms", "example": "Draft invoice for Q4 audit services - pending final review" }, "createdAt": { "type": "string", "format": "date-time", "description": "Draft invoice creation timestamp", "example": "2024-12-01T09:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-12-06T14:15:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this draft invoice" }, "404": { "description": "Draft invoice not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Draft invoice not found" }, "message": { "type": "string", "example": "Draft invoice with ID 56789 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/gql/v1/client_groups": { "post": { "tags": [ "Client Group" ], "summary": "List client groups", "description": "**Retrieve all client groups with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis endpoint returns a paginated list of all client groups in the tenant,\nincluding assigned partner/manager staff and office information.\n\n**Key Features:**\n- Basic pagination with configurable page sizes (default: 50 records)\n- Default sorting by client group name (ascending) then creation date (descending)\n- Total count aggregation for pagination metadata\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/client_groups' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getClientGroups", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved client group list", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientGroups": { "type": "array", "items": { "$ref": "#/components/schemas/ClientGroup" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of client groups in the tenant", "example": 142 } } } } } } }, "examples": { "successful_response": { "summary": "Typical response with client group data", "value": { "clientGroups": [ { "id": 10, "name": "Acme Corp Group", "pmsRef": "GRP-001", "active": true, "isManagedByAiwyn": false, "partnerStaffId": 101, "managerStaffId": 102, "officeId": 5, "createdAt": "2024-01-15T10:00:00.000000+00:00", "updatedAt": "2024-06-20T14:30:00.000000+00:00", "version": 3, "partnerStaff": { "id": 101, "firstName": "Michael", "lastName": "Chen", "email": "m.chen@company.com" }, "managerStaff": { "id": 102, "firstName": "Lisa", "lastName": "Rodriguez", "email": "l.rodriguez@company.com" }, "office": { "id": 5, "pmsRef": "OFF-5", "name": "San Francisco" } }, { "id": 11, "name": "Beta Industries Group", "pmsRef": "GRP-002", "active": true, "isManagedByAiwyn": true, "partnerStaffId": 103, "managerStaffId": null, "officeId": null, "createdAt": "2024-02-10T08:00:00.000000+00:00", "updatedAt": "2024-02-10T08:00:00.000000+00:00", "version": 1, "partnerStaff": { "id": 103, "firstName": "Jennifer", "lastName": "Park", "email": "j.park@company.com" }, "managerStaff": null, "office": null } ], "total": { "aggregate": { "count": 142 } } } }, "empty_response": { "summary": "Empty result set", "value": { "clientGroups": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gql/v1/clients": { "post": { "tags": [ "Client" ], "summary": "List clients", "description": "**Retrieve all clients with limit/offset pagination**\n\nThis endpoint lists all clients. It does not apply filters. Use\n`POST /gql/v1/clients/search` when you need a where clause.\n\n**Pagination (v1 โ€” intentional limit/offset)**\n\n`pageSize` is a **limit** (how many records to return). `page` is an\n**offset** (how many records to skip). It is **not** a 0-based or 1-based\npage number. Hasura maps these as `limit: $pageSize` and `offset: $page`.\n\nUse `total.aggregate.count` from the response to know when you have reached\nthe end. When `page` is greater than or equal to that count, `clients` is\nan empty array.\n\nExample with 25,156 clients and `pageSize` 1000:\n\n| Request | Records returned |\n|---|---|\n| `pageSize: 1000`, `page: 0` | records 1โ€“1000 |\n| `pageSize: 1000`, `page: 1000` | records 1001โ€“2000 |\n| `pageSize: 1000`, `page: 25000` | records 25001โ€“25156 (156 rows) |\n| `pageSize: 1000`, `page: 25156` | empty `clients` array |\n\nDo **not** request `page: 26` or `page: 27` expecting page 26 or 27 of\n1,000-record pages. Those values skip 26 or 27 rows and still return a\nfull `pageSize` of clients.\n\nA later API version will use conventional page-number pagination. This v1\ncontract will not change.\n\n**Other behavior:**\n- Default sort is client name ascending, then `createdAt` descending\n- Response includes contact details, staff assignments, and total count\n- Default `pageSize` is 50; maximum is 1000\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/gql/v1/clients' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1000,\n \"page\": 0\n}'\n```\n", "operationId": "getClients", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 1000 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nTo fetch the next 1,000 rows after the first 1,000, send\n`pageSize: 1000` and `page: 1000`. An offset at or beyond\n`total.aggregate.count` returns an empty `clients` array.\n", "example": 0 } } }, "examples": { "first_page": { "summary": "First 1,000 clients (skip 0)", "value": { "pageSize": 1000, "page": 0 } }, "next_chunk": { "summary": "Next 1,000 clients after the first 1,000", "value": { "pageSize": 1000, "page": 1000 } }, "last_partial_chunk": { "summary": "Remaining clients after skipping 25,000", "value": { "pageSize": 1000, "page": 25000 } }, "beyond_last_record": { "summary": "Offset at or beyond the total count (empty result)", "value": { "pageSize": 1000, "page": 25156 } } } } } }, "responses": { "200": { "description": "Successfully retrieved client list", "content": { "application/json": { "schema": { "type": "object", "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of clients in the system", "example": 13697 } } } } } } }, "examples": { "successful_response": { "summary": "Typical response with client data", "value": { "clients": [ { "id": 1001, "pmsRef": "8842", "clientRef": "45123", "name": "Sarah Johnson", "clientKey": "000000045123 f", "active": true, "createdAt": "2024-03-15T10:30:22.488054+00:00", "updatedAt": "2024-07-20T14:22:10.817274+00:00", "clientContactInfo": { "id": 7001, "firstName": "Sarah", "lastName": "Johnson", "email": "sarah.johnson@techcorp.com", "phone": "555-0123", "address": "123 Business Plaza", "city": "San Francisco", "state": "CA", "zip_code": "94105" }, "partnerStaff": { "id": 101, "firstName": "Michael", "lastName": "Chen", "email": "m.chen@company.com" }, "managerStaff": { "id": 102, "firstName": "Lisa", "lastName": "Rodriguez", "email": "l.rodriguez@company.com" } }, { "id": 1002, "pmsRef": "8843", "clientRef": "45124", "name": "DataFlow Solutions Inc", "clientKey": "000000045124 f", "active": true, "createdAt": "2024-03-16T09:15:33.660145+00:00", "updatedAt": "2024-07-20T14:22:10.817274+00:00", "clientContactInfo": { "id": 7002, "firstName": "Robert", "lastName": "Kim", "email": "r.kim@dataflow.io", "phone": "555-0124", "address": "456 Innovation Drive", "city": "Austin", "state": "TX", "zip_code": "73301" }, "partnerStaff": { "id": 103, "firstName": "Jennifer", "lastName": "Park", "email": "j.park@company.com" }, "managerStaff": { "id": 104, "firstName": "David", "lastName": "Thompson", "email": "d.thompson@company.com" } }, { "id": 1003, "pmsRef": "8844", "clientRef": "45125", "name": "Green Energy Partners", "clientKey": "000000045125 f", "active": true, "createdAt": "2024-03-17T11:45:11.410185+00:00", "updatedAt": "2024-03-17T11:45:11.410185+00:00", "clientContactInfo": null, "partnerStaff": { "id": 105, "firstName": "Amanda", "lastName": "Williams", "email": "a.williams@company.com" }, "managerStaff": { "id": 105, "firstName": "Amanda", "lastName": "Williams", "email": "a.williams@company.com" } }, { "id": 1004, "pmsRef": "8845", "clientRef": "45126", "name": "Metro Healthcare Systems", "clientKey": "000000045126 f", "active": true, "createdAt": "2024-03-18T08:20:14.232691+00:00", "updatedAt": "2024-07-20T14:22:10.817274+00:00", "clientContactInfo": { "id": 7004, "firstName": "Dr. Elena", "lastName": "Martinez", "email": "e.martinez@metrohealthcare.com", "phone": "555-0126", "address": "789 Medical Center Blvd", "city": "Denver", "state": "CO", "zip_code": "80202" }, "partnerStaff": { "id": 106, "firstName": "Ryan", "lastName": "O'Connor", "email": "r.oconnor@company.com" }, "managerStaff": { "id": 107, "firstName": "Maria", "lastName": "Gonzalez", "email": "m.gonzalez@company.com" } }, { "id": 1005, "pmsRef": "8846", "clientRef": "45127", "name": "Pacific Manufacturing Co", "clientKey": "000000045127 f", "active": true, "createdAt": "2024-03-19T13:12:52.495590+00:00", "updatedAt": "2024-07-20T14:22:10.817274+00:00", "clientContactInfo": { "id": 7005, "firstName": "James", "lastName": "Wu", "email": "j.wu@pacificmfg.com", "phone": "555-0127", "address": "321 Industrial Way", "city": "Seattle", "state": "WA", "zip_code": "98101" }, "partnerStaff": { "id": 108, "firstName": "Nicole", "lastName": "Brown", "email": "n.brown@company.com" }, "managerStaff": { "id": 109, "firstName": "Kevin", "lastName": "Davis", "email": "k.davis@company.com" } } ], "total": { "aggregate": { "count": 13697 } } } }, "empty_response": { "summary": "Empty result set (no clients, or offset at/beyond total)", "value": { "clients": [], "total": { "aggregate": { "count": 25156 } } } }, "no_clients": { "summary": "Empty tenant (zero clients)", "value": { "clients": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_page_size": { "summary": "Invalid pageSize parameter", "value": { "error": "pageSize must be between 1 and 1000", "code": "INVALID_PARAMETER" } }, "negative_page": { "summary": "Negative page", "value": { "error": "page must be non-negative", "code": "INVALID_PARAMETER" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gql/v1/clients/search": { "post": { "tags": [ "Client" ], "summary": "Search clients", "description": "**Advanced client filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis query provides maximum flexibility for client data retrieval through custom\nGraphQL-style where clause construction and dynamic ordering specifications.\nIt's designed for complex business requirements that need sophisticated filtering logic.\n\n**Key Features:**\n- Custom GraphQL where clause construction for unlimited filtering combinations\n- Dynamic order_by specifications supporting multi-field sorting with custom directions\n- Advanced boolean logic combining multiple filter conditions with _and, _or, _not\n- Relationship-based filtering across connected entities (contacts, staff assignments)\n- Custom pagination: `pageSize` is a limit and `page` is a record offset (not a page number), matching `POST /gql/v1/clients`\n- Full access to GraphQL query capabilities through REST interface abstraction\n- Enterprise-grade filtering supporting complex business logic requirements\n- Support for nested queries and conditional logic patterns\n\n**Advanced Filtering Capabilities:**\n- **Boolean Logic**: _and, _or, _not operators for complex condition combinations\n- **Text Operations**: _like, _ilike, _regex for pattern matching and search\n- **Comparison Operators**: _gt, _gte, _lt, _lte, _eq, _neq for numerical/date comparisons \n- **Array Operations**: _in, _nin for multi-value filtering and inclusion/exclusion\n- **Null Handling**: _is_null for empty value detection and filtering\n- **Relationship Traversal**: Filter on connected entities like contacts and staff\n- **Date Ranges**: Precision timestamp filtering for time-based analysis\n- **Case Sensitivity**: Both case-sensitive and case-insensitive text matching\n\n**Dynamic Ordering Options:**\n- **Multi-field Sorting**: Order by multiple columns with individual sort directions\n- **Relationship Sorting**: Sort by connected entity fields (staff names, contact info)\n- **Custom Directions**: Mix ascending and descending order across different fields\n- **Priority Ordering**: Define primary, secondary, tertiary sort criteria\n- **Date-based Sorting**: createdAt, updatedAt for chronological ordering\n- **Text Sorting**: Alphabetical ordering with locale-aware collation\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/clients/search' \\\n--header 'Authorization: bearer {{token}} \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"name\": {\n \"_ilike\": \"%tech%\"\n }\n },\n {\n \"clientRef\": {\n \"_ilike\": \"%45%\"\n }\n }\n ]\n },\n {\n \"active\": {\n \"_eq\": true\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"partnerStaffId\": {\n \"_in\": [\n 5,\n 6,\n 7,\n 8\n ]\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"name\": \"asc\"\n },\n {\n \"createdAt\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "filterClientsDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 1 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nSame contract as `POST /gql/v1/clients`. When `page` is at or\nbeyond `total.aggregate.count`, `clients` is an empty array.\n", "example": 0 }, "where": { "type": "object", "description": "GraphQL-style where clause for complex filtering", "example": { "_and": [ { "_or": [ { "name": { "_ilike": "%tech%" } }, { "clientRef": { "_ilike": "%45%" } } ] }, { "active": { "_eq": true } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "partnerStaffId": { "_in": [ 5, 6, 7, 8 ] } } ] } }, "orderBy": { "type": "array", "description": "Dynamic ordering specifications with multiple fields", "items": { "type": "object" }, "example": [ { "name": "asc" }, { "createdAt": "desc" } ] } } }, "examples": { "default_search": { "summary": "Default search with filtering", "value": { "pageSize": 1, "page": 0, "where": { "_and": [ { "_or": [ { "name": { "_ilike": "%tech%" } }, { "clientRef": { "_ilike": "%45%" } } ] }, { "active": { "_eq": true } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "partnerStaffId": { "_in": [ 5, 6, 7, 8 ] } } ] }, "orderBy": [ { "name": "asc" }, { "createdAt": "desc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered clients with dynamic ordering", "content": { "application/json": { "schema": { "type": "object", "properties": { "clients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique client identifier", "example": 3001 }, "pmsRef": { "type": "string", "description": "Practice management system reference", "example": "1650" }, "clientRef": { "type": "string", "description": "Client reference number", "example": "48250" }, "name": { "type": "string", "description": "Client name or company name", "example": "TechFlow Enterprises" }, "clientKey": { "type": "string", "description": "Client key identifier", "example": "000000048250 f" }, "active": { "type": "boolean", "description": "Client active status", "example": true }, "partnerStaffId": { "type": "integer", "description": "Partner staff member assigned to client", "example": 6 }, "managerStaffId": { "type": "integer", "description": "Manager staff member assigned to client", "example": 25 }, "createdAt": { "type": "string", "format": "date-time", "description": "Client record creation timestamp", "example": "2024-05-12T22:43:57.189235+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Client record last update timestamp", "example": "2024-05-12T22:43:57.189235+00:00" }, "clientContactInfo": { "type": "object", "nullable": true, "description": "Client contact information", "properties": { "id": { "type": "integer", "example": 2850 }, "firstName": { "type": "string", "nullable": true, "example": "Jennifer" }, "lastName": { "type": "string", "nullable": true, "example": "Martinez" }, "email": { "type": "string", "nullable": true, "example": "jennifer@techflow.com" }, "phone": { "type": "string", "nullable": true, "example": "555-0123" }, "address": { "type": "string", "nullable": true, "example": "123 Business Plaza" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "state": { "type": "string", "nullable": true, "example": "CA" }, "zip_code": { "type": "string", "nullable": true, "example": "94105" } } }, "partnerStaff": { "type": "object", "description": "Partner staff member details", "properties": { "id": { "type": "integer", "example": 6 }, "firstName": { "type": "string", "example": "Robert" }, "lastName": { "type": "string", "example": "Chen" }, "email": { "type": "string", "example": "robert.chen@company.com" } } }, "managerStaff": { "type": "object", "description": "Manager staff member details", "properties": { "id": { "type": "integer", "example": 25 }, "firstName": { "type": "string", "example": "Sarah" }, "lastName": { "type": "string", "example": "Johnson" }, "email": { "type": "string", "example": "sarah.johnson@company.com" } } } } } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of clients matching filter criteria", "example": 59 } } } } } } }, "examples": { "successful_response": { "summary": "Filtered clients with dynamic ordering and relationships", "value": { "clients": [ { "id": 3001, "pmsRef": "1650", "clientRef": "48250", "name": "TechFlow Enterprises", "clientKey": "000000048250 f", "active": true, "partnerStaffId": 6, "managerStaffId": 25, "createdAt": "2024-05-12T22:43:57.189235+00:00", "updatedAt": "2024-05-12T22:43:57.189235+00:00", "clientContactInfo": { "id": 2850, "firstName": "Jennifer", "lastName": "Martinez", "email": "jennifer@techflow.com", "phone": "555-0123", "address": "123 Business Plaza", "city": "San Francisco", "state": "CA", "zip_code": "94105" }, "partnerStaff": { "id": 6, "firstName": "Robert", "lastName": "Chen", "email": "robert.chen@company.com" }, "managerStaff": { "id": 25, "firstName": "Sarah", "lastName": "Johnson", "email": "sarah.johnson@company.com" } }, { "id": 3002, "pmsRef": "1651", "clientRef": "48251", "name": "DataSolutions Corp", "clientKey": "000000048251 f", "active": true, "partnerStaffId": 7, "managerStaffId": 26, "createdAt": "2024-05-11T15:22:45.123456+00:00", "updatedAt": "2024-05-11T15:22:45.123456+00:00", "clientContactInfo": { "id": 2851, "firstName": "Michael", "lastName": "Davis", "email": "michael@datasolutions.com", "phone": "555-0124", "address": "456 Tech Center", "city": "Austin", "state": "TX", "zip_code": "73301" }, "partnerStaff": { "id": 7, "firstName": "Lisa", "lastName": "Wong", "email": "lisa.wong@company.com" }, "managerStaff": { "id": 26, "firstName": "David", "lastName": "Thompson", "email": "david.thompson@company.com" } } ], "total": { "aggregate": { "count": 59 } } } }, "real_api_response": { "summary": "Sample from actual API response", "value": { "clients": [ { "id": 2576, "pmsRef": "1403", "clientRef": "45985", "name": "Adan Kozey", "clientKey": "000000045985 f", "active": true, "partnerStaffId": 6, "managerStaffId": 25, "createdAt": "2023-05-12T22:43:57.189235+00:00", "updatedAt": "2023-05-12T22:43:57.189235+00:00", "clientContactInfo": { "id": 2622, "firstName": null, "lastName": null, "email": null, "phone": null, "address": "995 Arron Lights", "city": "New Corrine", "state": "MT", "zip_code": "71951" }, "partnerStaff": { "id": 6, "firstName": "Erline", "lastName": "Ruecker", "email": "joel.walker@hotmail.com" }, "managerStaff": { "id": 25, "firstName": "Ada", "lastName": "Kovacek", "email": "norbert.ruecker@yahoo.com" } } ], "total": { "aggregate": { "count": 59 } } } }, "empty_response": { "summary": "No clients match filter criteria", "value": { "clients": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid filter parameters or malformed where clause", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "invalid_where_clause": { "summary": "Malformed where clause", "value": { "error": "Invalid where clause structure: missing operator in condition", "code": "INVALID_WHERE_CLAUSE" } }, "invalid_order_by": { "summary": "Invalid ordering specification", "value": { "error": "Invalid orderBy field or direction specified", "code": "INVALID_ORDER_BY" } } } } } }, "401": { "description": "Unauthorized - missing or invalid admin secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "missing_auth": { "summary": "Missing authentication header", "value": { "error": "x-hasura-admin-secret header is required", "code": "MISSING_AUTH_HEADER" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/gql/v1/client/{id}": { "get": { "tags": [ "Client" ], "summary": "Get client by ID", "description": "**Retrieve a specific client by its unique identifier**\n\nThis endpoint provides detailed client information including:\n- Complete client details and demographics\n- Client status and relationship information\n- Contact and address information\n- Engagement and project portfolio\n- Financial and billing information\n- Industry and business classification\n\n**Client Management Features:**\n- Client lifecycle tracking\n- Relationship management\n- Contact and address management\n- Engagement portfolio oversight\n- Financial and billing setup\n\n**Client Details Include:**\n- Client name and demographics\n- Client status and type\n- Contact information\n- Address and location\n- Engagement portfolio\n- Financial information\n\n**Business Applications:**\n- Client relationship management\n- Engagement portfolio analysis\n- Financial performance tracking\n- Contact management\n- Business development planning\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/client/789' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 789,\n \"name\": \"Acme Corporation\",\n \"legalName\": \"Acme Corporation, Inc.\",\n \"status\": \"ACTIVE\",\n \"type\": \"CORPORATE\",\n \"industry\": \"MANUFACTURING\",\n \"size\": \"LARGE\",\n \"website\": \"https://www.acme.com\",\n \"taxId\": \"12-3456789\",\n \"phone\": \"+1-555-0123\",\n \"email\": \"info@acme.com\",\n \"address\": {\n \"street\": \"123 Business Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"zipCode\": \"10001\",\n \"country\": \"USA\"\n },\n \"billingAddress\": {\n \"street\": \"456 Finance Blvd\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"zipCode\": \"10002\",\n \"country\": \"USA\"\n },\n \"primaryContact\": {\n \"id\": 23456,\n \"name\": \"John Smith\",\n \"title\": \"Chief Financial Officer\",\n \"email\": \"john.smith@acme.com\",\n \"phone\": \"+1-555-0123\"\n },\n \"engagements\": [\n {\n \"id\": 34567,\n \"name\": \"Annual Audit Engagement 2024\",\n \"status\": \"ACTIVE\",\n \"type\": \"AUDIT\",\n \"startDate\": \"2024-01-01T00:00:00Z\",\n \"endDate\": \"2024-12-31T23:59:59Z\"\n }\n ],\n \"financialSummary\": {\n \"totalRevenue\": 150000.00,\n \"outstandingBalance\": 25000.00,\n \"currency\": \"USD\",\n \"lastPaymentDate\": \"2024-11-15T10:30:00Z\"\n },\n \"notes\": \"Long-term client with excellent payment history and strong relationship\",\n \"createdAt\": \"2020-01-15T10:00:00Z\",\n \"updatedAt\": \"2024-11-20T14:30:00Z\"\n}\n```\n", "operationId": "getClientById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the client", "schema": { "type": "integer", "minimum": 1 }, "example": 789 } ], "responses": { "200": { "description": "Client details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique client identifier", "example": 789 }, "name": { "type": "string", "description": "Client name", "example": "Acme Corporation" }, "legalName": { "type": "string", "description": "Legal business name", "example": "Acme Corporation, Inc." }, "status": { "type": "string", "description": "Client status", "enum": [ "ACTIVE", "INACTIVE", "PROSPECT", "FORMER" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "Client type", "enum": [ "CORPORATE", "INDIVIDUAL", "PARTNERSHIP", "LLC", "NONPROFIT" ], "example": "CORPORATE" }, "industry": { "type": "string", "description": "Industry classification", "enum": [ "MANUFACTURING", "RETAIL", "HEALTHCARE", "FINANCIAL", "TECHNOLOGY", "CONSULTING", "OTHER" ], "example": "MANUFACTURING" }, "size": { "type": "string", "description": "Company size classification", "enum": [ "SMALL", "MEDIUM", "LARGE", "ENTERPRISE" ], "example": "LARGE" }, "website": { "type": "string", "format": "uri", "description": "Company website URL", "example": "https://www.acme.com" }, "taxId": { "type": "string", "description": "Tax identification number", "example": "12-3456789" }, "phone": { "type": "string", "description": "Primary phone number", "example": "+1-555-0123" }, "email": { "type": "string", "format": "email", "description": "Primary email address", "example": "info@acme.com" }, "address": { "type": "object", "description": "Primary business address", "properties": { "street": { "type": "string", "description": "Street address", "example": "123 Business Ave" }, "city": { "type": "string", "description": "City", "example": "New York" }, "state": { "type": "string", "description": "State or province", "example": "NY" }, "zipCode": { "type": "string", "description": "ZIP or postal code", "example": "10001" }, "country": { "type": "string", "description": "Country", "example": "USA" } } }, "billingAddress": { "type": "object", "description": "Billing address (if different from primary)", "properties": { "street": { "type": "string", "description": "Street address", "example": "456 Finance Blvd" }, "city": { "type": "string", "description": "City", "example": "New York" }, "state": { "type": "string", "description": "State or province", "example": "NY" }, "zipCode": { "type": "string", "description": "ZIP or postal code", "example": "10002" }, "country": { "type": "string", "description": "Country", "example": "USA" } } }, "primaryContact": { "type": "object", "description": "Primary contact information", "properties": { "id": { "type": "integer", "description": "Contact identifier", "example": 23456 }, "name": { "type": "string", "description": "Contact name", "example": "John Smith" }, "title": { "type": "string", "description": "Contact title", "example": "Chief Financial Officer" }, "email": { "type": "string", "format": "email", "description": "Contact email", "example": "john.smith@acme.com" }, "phone": { "type": "string", "description": "Contact phone", "example": "+1-555-0123" } } }, "engagements": { "type": "array", "description": "Active engagements for this client", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Engagement identifier", "example": 34567 }, "name": { "type": "string", "description": "Engagement name", "example": "Annual Audit Engagement 2024" }, "status": { "type": "string", "description": "Engagement status", "enum": [ "PLANNING", "ACTIVE", "ON_HOLD", "COMPLETED", "CANCELLED" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "Engagement type", "enum": [ "AUDIT", "REVIEW", "COMPILATION", "TAX", "CONSULTING", "ADVISORY" ], "example": "AUDIT" }, "startDate": { "type": "string", "format": "date-time", "description": "Engagement start date", "example": "2024-01-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "Engagement end date", "example": "2024-12-31T23:59:59Z" } } } }, "financialSummary": { "type": "object", "description": "Financial summary for this client", "properties": { "totalRevenue": { "type": "number", "format": "decimal", "description": "Total revenue from this client", "example": 150000 }, "outstandingBalance": { "type": "number", "format": "decimal", "description": "Outstanding balance owed", "example": 25000 }, "currency": { "type": "string", "description": "Currency code", "example": "USD" }, "lastPaymentDate": { "type": "string", "format": "date-time", "description": "Date of last payment", "example": "2024-11-15T10:30:00Z" } } }, "notes": { "type": "string", "description": "Additional notes about the client", "example": "Long-term client with excellent payment history and strong relationship" }, "createdAt": { "type": "string", "format": "date-time", "description": "Client creation timestamp", "example": "2020-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-11-20T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this client" }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Client not found" }, "message": { "type": "string", "example": "Client with ID 789 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/clients/v1/onboard": { "post": { "tags": [ "Client" ], "summary": "Client Onboarding", "description": "**Onboard a new client with inline contact creation**\n\nCreates a new client record and simultaneously resolves or creates up to three\nassociated contacts (preferred, billing, and secondary). Each contact field accepts\neither an existing contact ID or a full inline payload to create a brand-new contact.\n\n**Required fields:**\n- `name` โ€” client display name\n- `pmsRef` โ€” practice management system reference\n- `clientRef` โ€” unique client reference identifier\n- `officeId` โ€” ID of the office this client belongs to\n\n**Contact fields** (`prefContact`, `billingContact`, `secondaryContact`):\nEach contact field is optional but, when provided, must include **either** an existing\n`id` **or** a `contactInfo` object โ€” not both.\n- When supplying `contactInfo`, `pmsRef` on the contact payload is required.\n- At least one of `prefix`, `firstName`, or `lastName` must be provided inside\n `contactInfo` to form a valid full name.\n\n**Classification & billing fields** (all optional):\n- `clientTypeId`, `clientBusinessEntityId` (entity type), and `staffBillingManagerId`\n each reference an existing record; an unknown ID is rejected with **400**.\n- `fiscalYearEndMonth` (1โ€“12) and `fiscalYearEndDay` (1โ€“31) capture the client's fiscal\n year end.\n\n**Custom fields** (`customFieldValuesJson`): a JSON object, encoded as a string, mapping\ncustom field keys to values. Keys not defined in the tenant's `CLIENT` custom-field schema\nare dropped rather than failing the request, and are echoed back in\n`data.ignoredCustomFields` (and appended to the response `message`). The onboard still\nreturns **201**.\n\n**Tax regions** (`taxRegionIds`): a list of existing tax region IDs to link to the new\nclient. Duplicate IDs are de-duplicated; an unknown ID is rejected with **400**. The\nassigned IDs are returned in `data.taxRegionIds`.\n\n**Addresses** (`address`, `billingAddress`), both optional and stored the same way the\nFirm Portal \"Create New Client\" dialog stores them:\n- `address` is the client's own address. It is saved as the client's contact info record\n and shows in the portal's *Address* section; its ID is returned in\n `data.clientContactInfoId`.\n- `billingAddress` is saved as a client address of type *Billing* and shows in the\n portal's *Billing Address* section; its ID is returned in `data.billingAddressId`.\n- `country` must be an ISO 3166-1 alpha-2 code (e.g. `US`, `CA`, `GB`); it is accepted\n case-insensitively and stored upper-case.\n- When `country` is `US`, `state` must be a US state name or abbreviation and is stored\n as the abbreviation (e.g. `North Carolina` โ†’ `NC`). For other countries `state` is\n stored as given.\n- `pmsRef` is optional on both; when omitted an Aiwyn reference (`AIWYN_`) is\n generated. A `pmsRef` that already exists is rejected with **400**.\n- An address object must carry at least one address field; an invalid country, state or\n duplicate `pmsRef` rejects the whole request with **400** and no client is created.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/clients/v1/onboard' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"name\": \"Acme Corporation\",\n \"pmsRef\": \"ACME-001\",\n \"clientRef\": \"ACME-001\",\n \"officeId\": 1,\n \"prefContact\": {\n \"pmsRef\": \"CONT-001\",\n \"contactInfo\": {\n \"pmsRef\": \"CONT-001\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"email\": \"jane.smith@acme.com\"\n }\n },\n \"address\": {\n \"address\": \"123 Main St\",\n \"address2\": \"Suite 400\",\n \"city\": \"Charlotte\",\n \"state\": \"NC\",\n \"country\": \"US\",\n \"zipCode\": \"28202\"\n },\n \"billingAddress\": {\n \"pmsRef\": \"ACME-001-BILLING\",\n \"address\": \"PO Box 999\",\n \"city\": \"Raleigh\",\n \"state\": \"NC\",\n \"country\": \"US\",\n \"zipCode\": \"27601\"\n }\n}'\n```\n", "operationId": "onboardNewClient", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "pmsRef", "clientRef", "officeId" ], "properties": { "name": { "type": "string", "description": "Client display name", "example": "Acme Corporation" }, "pmsRef": { "type": "string", "description": "Practice management system reference identifier", "example": "ACME-001" }, "clientRef": { "type": "string", "description": "Unique client reference identifier", "example": "ACME-001" }, "officeId": { "type": "integer", "format": "int64", "description": "ID of the office this client belongs to", "example": 1 }, "description": { "type": "string", "nullable": true, "description": "Optional client description", "example": "A multinational technology company" }, "sortName": { "type": "string", "nullable": true, "description": "Alternate name used for alphabetical sorting", "example": "Acme" }, "notes": { "type": "string", "nullable": true, "description": "Internal notes about the client", "example": "Preferred billing on the 1st of the month" }, "departmentId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the department associated with this client", "example": 10 }, "orgId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the organization associated with this client", "example": 5 }, "industryId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the industry classification for this client", "example": 3 }, "partnerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the partner staff member assigned to this client", "example": 53 }, "managerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the manager staff member assigned to this client", "example": 15 }, "clientTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the client type classification", "example": 7 }, "clientBusinessEntityId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the client business entity (entity type)", "example": 4 }, "staffBillingManagerId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the staff member acting as billing manager for this client", "example": 22 }, "fiscalYearEndMonth": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "maximum": 12, "description": "Month (1-12) the client's fiscal year ends", "example": 12 }, "fiscalYearEndDay": { "type": "integer", "format": "int32", "nullable": true, "minimum": 1, "maximum": 31, "description": "Day of month (1-31) the client's fiscal year ends", "example": 31 }, "customFieldValuesJson": { "type": "string", "nullable": true, "description": "JSON object, encoded as a string, mapping custom field keys to values. Keys not defined in the tenant's CLIENT custom-field schema are ignored and reported back in `data.ignoredCustomFields`.\n", "example": "{\"industry_niche\":\"Manufacturing\",\"naics_code\":\"333120\"}" }, "taxRegionIds": { "type": "array", "nullable": true, "description": "IDs of existing tax regions to assign to the new client. Duplicates are de-duplicated; an unknown ID returns 400.\n", "items": { "type": "integer", "format": "int64" }, "example": [ 3, 7 ] }, "ebilling": { "type": "boolean", "default": false, "description": "Whether this client is enrolled in electronic billing", "example": true }, "invoiceDeliveryMethod": { "type": "string", "nullable": true, "description": "How invoices are delivered to the client. Defaults to EMAIL when `ebilling` is true, otherwise DOWNLOAD.\n", "enum": [ "EMAIL", "DOWNLOAD", "EMAIL_AND_DOWNLOAD", "POST_ONLY" ], "example": "EMAIL" }, "emailStatement": { "type": "boolean", "default": false, "description": "Whether statements are emailed to the client", "example": false }, "chargeAdminFee": { "type": "boolean", "default": false, "description": "Whether an administrative fee is charged to this client", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the client is active", "example": true }, "address": { "type": "object", "nullable": true, "description": "The client's own address, stored as the client's contact info record (the portal's \"Address\" section). At least one address field is required; `pmsRef` is optional and generated as `AIWYN_` when omitted.\n", "properties": { "pmsRef": { "type": "string", "nullable": true, "description": "PMS reference for the address record. Must not already exist.", "example": "ACME-001-ADDRESS" }, "address": { "type": "string", "nullable": true, "example": "123 Main St" }, "address2": { "type": "string", "nullable": true, "example": "Suite 400" }, "city": { "type": "string", "nullable": true, "example": "Charlotte" }, "state": { "type": "string", "nullable": true, "description": "For `country: US` a US state name or abbreviation, stored as the abbreviation. Free text for other countries.\n", "example": "NC" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 country code; stored upper-case.", "example": "US" }, "zipCode": { "type": "string", "nullable": true, "example": "28202" } } }, "billingAddress": { "type": "object", "nullable": true, "description": "Billing address, stored as a client address of type Billing (the portal's \"Billing Address\" section). Same shape and rules as `address`.\n", "properties": { "pmsRef": { "type": "string", "nullable": true, "description": "PMS reference for the billing address record. Must not already exist.", "example": "ACME-001-BILLING" }, "address": { "type": "string", "nullable": true, "example": "PO Box 999" }, "address2": { "type": "string", "nullable": true, "example": null }, "city": { "type": "string", "nullable": true, "example": "Raleigh" }, "state": { "type": "string", "nullable": true, "example": "NC" }, "country": { "type": "string", "nullable": true, "example": "US" }, "zipCode": { "type": "string", "nullable": true, "example": "27601" } } }, "prefContact": { "type": "object", "nullable": true, "description": "Preferred contact. Provide either `id` (existing contact) or `contactInfo` (create new) โ€” not both. `pmsRef` is required when creating a new contact.\n", "properties": { "id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of an existing contact to link", "example": 501 }, "username": { "type": "string", "format": "email", "nullable": true, "description": "Email address used as the contact's login username", "example": "jane.smith@acme.com" }, "pmsRef": { "type": "string", "nullable": true, "description": "PMS reference for the contact. Required when creating a new contact.", "example": "CONT-001" }, "type": { "type": "string", "nullable": true, "description": "Contact type classification", "example": "PRIMARY" }, "staffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the staff member associated with this contact", "example": 53 }, "officeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the office associated with this contact", "example": 1 }, "contactInfo": { "type": "object", "nullable": true, "description": "Full contact details for creating a new contact record", "required": [ "pmsRef" ], "properties": { "pmsRef": { "type": "string", "description": "PMS reference for the contact info record", "example": "CONT-001" }, "shortName": { "type": "string", "nullable": true, "example": "Jane S." }, "firstName": { "type": "string", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "example": "Smith" }, "jobTitle": { "type": "string", "nullable": true, "example": "CFO" }, "prefix": { "type": "string", "nullable": true, "example": "Ms." }, "salutation": { "type": "string", "nullable": true, "example": "Dear Jane" }, "phone": { "type": "string", "nullable": true, "example": "+1-555-0123" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "jane.smith@acme.com" }, "address": { "type": "string", "nullable": true, "example": "123 Main St" }, "address2": { "type": "string", "nullable": true, "example": "Suite 400" }, "city": { "type": "string", "nullable": true, "example": "New York" }, "state": { "type": "string", "nullable": true, "example": "NY" }, "country": { "type": "string", "nullable": true, "example": "US" }, "zipCode": { "type": "string", "nullable": true, "example": "10001" } } } } }, "billingContact": { "type": "object", "nullable": true, "description": "Billing contact. Same shape as `prefContact` โ€” provide either `id` or `contactInfo`.\n", "properties": { "id": { "type": "integer", "format": "int64", "nullable": true, "example": 502 }, "username": { "type": "string", "format": "email", "nullable": true, "example": "billing@acme.com" }, "pmsRef": { "type": "string", "nullable": true, "example": "CONT-002" }, "type": { "type": "string", "nullable": true, "example": "BILLING" }, "staffId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "officeId": { "type": "integer", "format": "int64", "nullable": true, "example": 1 }, "contactInfo": { "type": "object", "nullable": true, "required": [ "pmsRef" ], "properties": { "pmsRef": { "type": "string", "example": "CONT-002" }, "shortName": { "type": "string", "nullable": true, "example": null }, "firstName": { "type": "string", "nullable": true, "example": "Bob" }, "lastName": { "type": "string", "nullable": true, "example": "Finance" }, "jobTitle": { "type": "string", "nullable": true, "example": "Accounts Payable" }, "prefix": { "type": "string", "nullable": true, "example": null }, "salutation": { "type": "string", "nullable": true, "example": null }, "phone": { "type": "string", "nullable": true, "example": "+1-555-0124" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "billing@acme.com" }, "address": { "type": "string", "nullable": true, "example": null }, "address2": { "type": "string", "nullable": true, "example": null }, "city": { "type": "string", "nullable": true, "example": null }, "state": { "type": "string", "nullable": true, "example": null }, "country": { "type": "string", "nullable": true, "example": null }, "zipCode": { "type": "string", "nullable": true, "example": null } } } } }, "secondaryContact": { "type": "object", "nullable": true, "description": "Secondary contact. Same shape as `prefContact` โ€” provide either `id` or `contactInfo`.\n", "properties": { "id": { "type": "integer", "format": "int64", "nullable": true, "example": 503 }, "username": { "type": "string", "format": "email", "nullable": true, "example": null }, "pmsRef": { "type": "string", "nullable": true, "example": null }, "type": { "type": "string", "nullable": true, "example": null }, "staffId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "officeId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "contactInfo": { "type": "object", "nullable": true, "required": [ "pmsRef" ], "properties": { "pmsRef": { "type": "string", "example": "CONT-003" }, "firstName": { "type": "string", "nullable": true, "example": "Carol" }, "lastName": { "type": "string", "nullable": true, "example": "Secondary" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "carol@acme.com" } } } } } } }, "examples": { "new_contact_inline": { "summary": "New client with inline preferred contact and client address", "value": { "name": "Acme Corporation", "pmsRef": "ACME-001", "clientRef": "ACME-001", "officeId": 1, "prefContact": { "pmsRef": "CONT-001", "contactInfo": { "pmsRef": "CONT-001", "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@acme.com" } }, "address": { "address": "123 Main St", "address2": "Suite 400", "city": "Charlotte", "state": "NC", "country": "US", "zipCode": "28202" } } }, "existing_contact": { "summary": "New client linking to existing contacts", "value": { "name": "Beta Industries", "pmsRef": "BETA-002", "clientRef": "BETA-002", "officeId": 1, "prefContact": { "id": 501 }, "billingContact": { "id": 502 } } }, "minimal": { "summary": "Minimal required fields only", "value": { "name": "Gamma LLC", "pmsRef": "GAMMA-003", "clientRef": "GAMMA-003", "officeId": 1 } }, "crm_integration_fields": { "summary": "Client with classification, fiscal year end, custom fields, and tax regions", "value": { "name": "Redw Client", "pmsRef": "REDW-100", "clientRef": "REDW-100", "officeId": 1, "clientTypeId": 7, "clientBusinessEntityId": 4, "staffBillingManagerId": 22, "fiscalYearEndMonth": 12, "fiscalYearEndDay": 31, "customFieldValuesJson": "{\"industry_niche\":\"Manufacturing\",\"naics_code\":\"333120\"}", "taxRegionIds": [ 3, 7 ] } }, "with_addresses": { "summary": "Client with its own address and a separate billing address", "value": { "name": "Delta Partners", "pmsRef": "DELTA-004", "clientRef": "DELTA-004", "officeId": 1, "address": { "address": "123 Main St", "address2": "Suite 400", "city": "Charlotte", "state": "North Carolina", "country": "us", "zipCode": "28202" }, "billingAddress": { "pmsRef": "DELTA-004-BILLING", "address": "PO Box 999", "city": "Raleigh", "state": "NC", "country": "US", "zipCode": "27601" } } } } } } }, "responses": { "201": { "description": "Client onboarded successfully. Unknown custom field keys are dropped and reported in `data.ignoredCustomFields` โ€” the write still succeeds.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "description": "Success message. When custom field keys are dropped, this is suffixed with \"; ignored unknown custom fields: `{keys}`\".\n", "example": "Client onboarded successfully" }, "data": { "type": "object", "properties": { "client": { "type": "object", "description": "The newly created client record", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the created client", "example": 1001 }, "pmsRef": { "type": "string", "example": "ACME-001" }, "clientRef": { "type": "string", "example": "ACME-001" }, "name": { "type": "string", "example": "Acme Corporation" }, "description": { "type": "string", "nullable": true, "example": null }, "sortName": { "type": "string", "nullable": true, "example": null }, "officeId": { "type": "integer", "format": "int64", "example": 1 }, "departmentId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "orgId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "industryId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "partnerStaffId": { "type": "integer", "format": "int64", "nullable": true, "example": 53 }, "managerStaffId": { "type": "integer", "format": "int64", "nullable": true, "example": 15 }, "clientTypeId": { "type": "integer", "format": "int64", "nullable": true, "example": 7 }, "clientBusinessEntityId": { "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "staffBillingManagerId": { "type": "integer", "format": "int64", "nullable": true, "example": 22 }, "fiscalYearEndMonth": { "type": "integer", "format": "int32", "nullable": true, "example": 12 }, "fiscalYearEndDay": { "type": "integer", "format": "int32", "nullable": true, "example": 31 }, "customFieldValuesJson": { "type": "string", "nullable": true, "description": "JSON object, encoded as a string, of persisted custom field values", "example": "{\"industry_niche\":\"Manufacturing\"}" }, "active": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "ACTIVE" }, "version": { "type": "integer", "format": "int64", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-03-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-03-15T10:00:00Z" } } }, "prefContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the resolved preferred contact", "example": 601 }, "billingContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the resolved billing contact", "example": null }, "secondaryContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the resolved secondary contact", "example": null }, "clientContactInfoId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the contact info record created from `address`; null when no `address` was supplied\n", "example": 44489 }, "billingAddressId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the Billing client address created from `billingAddress`; null when no `billingAddress` was supplied\n", "example": 211 }, "taxRegionIds": { "type": "array", "description": "IDs of the tax regions assigned to the client during onboarding", "items": { "type": "integer", "format": "int64" }, "example": [ 3, 7 ] }, "ignoredCustomFields": { "type": "array", "description": "Custom field keys that were provided but ignored because they are not defined in the tenant's CLIENT custom-field schema\n", "items": { "type": "string" }, "example": [] } } } } }, "examples": { "success": { "summary": "Client onboarded with a new preferred contact and client address", "value": { "success": true, "message": "Client onboarded successfully", "data": { "client": { "id": 1001, "pmsRef": "ACME-001", "clientRef": "ACME-001", "name": "Acme Corporation", "officeId": 1, "active": true, "status": "ACTIVE", "version": 1, "createdAt": "2024-03-15T10:00:00Z", "updatedAt": "2024-03-15T10:00:00Z" }, "prefContactId": 601, "billingContactId": null, "secondaryContactId": null, "clientContactInfoId": 44489, "billingAddressId": null, "taxRegionIds": [], "ignoredCustomFields": [] } } }, "success_with_addresses": { "summary": "Onboarded with a client address and a billing address", "value": { "success": true, "message": "Client onboarded successfully", "data": { "client": { "id": 1003, "pmsRef": "DELTA-004", "clientRef": "DELTA-004", "name": "Delta Partners", "officeId": 1, "active": true, "status": "ACTIVE", "version": 1, "createdAt": "2024-03-15T10:00:00Z", "updatedAt": "2024-03-15T10:00:00Z" }, "prefContactId": null, "billingContactId": null, "secondaryContactId": null, "clientContactInfoId": 44489, "billingAddressId": 211, "taxRegionIds": [], "ignoredCustomFields": [] } } }, "success_with_ignored_custom_fields": { "summary": "Onboarded with tax regions; an unknown custom field key was dropped", "value": { "success": true, "message": "Client onboarded successfully; ignored unknown custom fields: naics_cod", "data": { "client": { "id": 1002, "pmsRef": "REDW-100", "clientRef": "REDW-100", "name": "Redw Client", "officeId": 1, "clientTypeId": 7, "clientBusinessEntityId": 4, "staffBillingManagerId": 22, "fiscalYearEndMonth": 12, "fiscalYearEndDay": 31, "customFieldValuesJson": "{\"industry_niche\":\"Manufacturing\"}", "active": true, "status": "ACTIVE", "version": 1, "createdAt": "2024-03-15T10:00:00Z", "updatedAt": "2024-03-15T10:00:00Z" }, "prefContactId": null, "billingContactId": null, "secondaryContactId": null, "clientContactInfoId": null, "billingAddressId": null, "taxRegionIds": [ 3, 7 ], "ignoredCustomFields": [ "naics_cod" ] } } } } } } }, "400": { "description": "Invalid input data โ€” for example, both `id` and `contactInfo` were supplied on a contact field, a required field is missing, or an address has an unknown country/US state or a `pmsRef` that already exists\n" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_CLIENT_C)" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/client_business_entities": { "post": { "tags": [ "Client Business Entity" ], "summary": "List client business entities", "description": "**Retrieve all client business entities with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura. It is useful after creating records via `/api/v1/records`.\n", "operationId": "getClientBusinessEntitiesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved client business entities", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientBusinessEntities": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "clientBusinessEntities": [ { "id": 101, "name": "Tax", "active": true, "clientBusinessEntityType": "TAX", "ref": "TAX", "sysRefs": {}, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/client_types": { "post": { "tags": [ "Client" ], "summary": "List client types", "description": "**Retrieve all client types with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura. Use it to resolve the\n`clientTypeId` values accepted by the Client Onboarding endpoint\n(`POST /api/v1/clients/v1/onboard`).\n", "operationId": "getClientTypesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved client types", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientTypes": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "clientTypes": [ { "id": 2, "name": "Corporation", "active": true, "is_business": true, "pms_ref": "CORP", "created_at": "2025-01-02T03:04:05Z", "updated_at": "2025-01-02T03:04:05Z" } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/contact_clients": { "post": { "tags": [ "Contact Client" ], "summary": "List contact-client relationships", "description": "**Retrieve all contact-client relationships with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getContactClientsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved contact-client relationships", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactClients": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "contactClients": [ { "id": 9001, "pms_ref": "CC-10001", "active": true, "client_id": 1001, "contact_id": 2001, "relationship": "OWNER", "receives_invoice": true, "receives_statement": true, "receives_payment_confirmation": false, "sys_refs": {}, "created_at": "2025-01-02T03:04:05Z", "updated_at": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/contact_infos": { "post": { "tags": [ "Contact Info" ], "summary": "List contact infos", "description": "**Retrieve all contact info records with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getContactInfosPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved contact infos", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactInfos": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "contactInfos": [ { "id": 3001, "pms_ref": "CI-3001", "active": true, "salutation": "Ms.", "firstName": "Asha", "lastName": "Patel", "email": "asha.patel@example.com", "phone": "555-0101", "address": "123 Main St", "address2": "Suite 400", "city": "Austin", "state": "TX", "country": "US", "zip_code": "78701", "created_at": "2025-01-02T03:04:05Z", "updated_at": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/departments": { "post": { "tags": [ "Department" ], "summary": "List departments", "description": "**Retrieve all departments with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getDepartmentsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved departments", "content": { "application/json": { "schema": { "type": "object", "properties": { "departments": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "departments": [ { "id": 7, "pmsRef": "DEPT-7", "name": "Tax", "active": true, "isCreatedByAiwyn": true, "isManagedByAiwyn": true, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/industries": { "post": { "tags": [ "Industry" ], "summary": "List industries", "description": "**Retrieve all industries with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getIndustriesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved industries", "content": { "application/json": { "schema": { "type": "object", "properties": { "industries": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "industries": [ { "id": 55, "name": "Healthcare", "active": true, "industryType": "NAICS", "ref": "HC", "sysRefs": {}, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/jobs": { "post": { "tags": [ "Job" ], "summary": "List jobs", "description": "**Retrieve all jobs with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getJobsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "jobs": [ { "id": 5012, "pmsRef": "JOB-5012", "jobRef": "J-0005012", "name": "Q1 Financial Review 2025", "status": "ACTIVE", "isActive": true, "clientId": 1001, "deptId": 7, "officeId": 2, "jobTemplateId": 300, "managerStaffId": 102, "partnerStaffId": 101, "sysRefs": {}, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-03T10:11:12Z", "version": 3 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/job/{id}": { "get": { "tags": [ "Job" ], "summary": "Get job by ID", "description": "**Retrieve a specific job by its unique identifier**\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getJobById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the job", "schema": { "type": "integer", "minimum": 1 }, "example": 5012 } ], "responses": { "200": { "description": "Job details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique job identifier", "example": 5012 }, "pmsRef": { "type": "string", "description": "External PMS reference", "example": "JOB-5012" }, "jobRef": { "type": "string", "description": "Internal job reference", "example": "J-0005012" }, "name": { "type": "string", "description": "Job name", "example": "Q1 Financial Review 2025" }, "status": { "type": "string", "description": "Job status", "example": "ACTIVE" }, "isActive": { "type": "boolean", "description": "Whether the job is active", "example": true }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 1001 }, "deptId": { "type": "integer", "description": "Associated department identifier", "example": 7 }, "officeId": { "type": "integer", "description": "Associated office identifier", "example": 2 }, "jobTemplateId": { "type": "integer", "description": "Associated job template identifier", "example": 300 }, "managerStaffId": { "type": "integer", "description": "Staff identifier for the job manager", "example": 102 }, "partnerStaffId": { "type": "integer", "description": "Staff identifier for the job partner", "example": 101 }, "startDate": { "type": "string", "format": "date-time", "description": "Job start date", "example": "2025-01-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "Job end date", "example": "2025-03-31T23:59:59Z" }, "dueDate": { "type": "string", "format": "date-time", "description": "Job due date (alias for endDate)", "example": "2025-03-31T23:59:59Z" }, "targetStartDate": { "type": "string", "format": "date-time", "description": "Target start date", "example": "2025-01-01T00:00:00Z" }, "targetEndDate": { "type": "string", "format": "date-time", "description": "Target end date", "example": "2025-03-31T23:59:59Z" }, "feeStructureId": { "type": "integer", "description": "Associated fee structure identifier", "example": 42 }, "feeStructureV4": { "type": "object", "description": "Fee structure details", "properties": { "id": { "type": "integer", "example": 42 }, "type": { "type": "string", "example": "FIXED" }, "amount": { "type": "number", "example": 5000 }, "active": { "type": "boolean", "example": true } } }, "sysRefs": { "type": "object", "description": "System reference metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation timestamp", "example": "2025-01-02T03:04:05Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2025-01-03T10:11:12Z" }, "version": { "type": "integer", "description": "Record version for optimistic concurrency", "example": 3 } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "job": [ { "id": 5012, "pmsRef": "JOB-5012", "jobRef": "J-0005012", "name": "Q1 Financial Review 2025", "status": "ACTIVE", "isActive": true, "clientId": 1001, "deptId": 7, "officeId": 2, "jobTemplateId": 300, "managerStaffId": 102, "partnerStaffId": 101, "startDate": "2025-01-01T00:00:00Z", "endDate": "2025-03-31T23:59:59Z", "dueDate": "2025-03-31T23:59:59Z", "targetStartDate": "2025-01-01T00:00:00Z", "targetEndDate": "2025-03-31T23:59:59Z", "feeStructureId": 42, "feeStructureV4": { "id": 42, "type": "FIXED", "amount": 5000, "active": true }, "sysRefs": {}, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-03T10:11:12Z", "version": 3 } ] } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/job_templates": { "post": { "tags": [ "Job Template" ], "summary": "List job templates", "description": "**Retrieve all job templates with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getJobTemplatesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved job templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobTemplates": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "jobTemplates": [ { "id": 300, "pmsRef": "JT-300", "ref": "1040", "name": "Individual Tax Return", "active": true, "serviceLineId": 10, "isCreatedByAiwyn": true, "isManagedByAiwyn": true, "sysRefs": {}, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/offices": { "post": { "tags": [ "Office" ], "summary": "List offices", "description": "**Retrieve all offices with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getOfficesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved offices", "content": { "application/json": { "schema": { "type": "object", "properties": { "offices": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "offices": [ { "id": 2, "pmsRef": "OFF-2", "name": "Austin - Downtown", "active": true, "city": "Austin", "stateProvince": "TX", "country": "US", "zip": "78701", "isCreatedByAiwyn": true, "isManagedByAiwyn": true, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/orgs": { "post": { "tags": [ "Org" ], "summary": "List orgs", "description": "**Retrieve all orgs with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getOrgsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved orgs", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgs": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "orgs": [ { "id": 1, "pmsRef": "ORG-1", "name": "Acme Accounting", "active": true, "defaultBillingDay": 15, "isDefault": true, "isCreatedByAiwyn": true, "isManagedByAiwyn": true, "createdAt": "2025-01-02T03:04:05Z", "updatedAt": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/service_lines": { "post": { "tags": [ "Service Line" ], "summary": "List service lines", "description": "**Retrieve all service lines with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura.\n", "operationId": "getServiceLinesPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved service lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceLines": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "serviceLines": [ { "id": 10, "pms_ref": "SL-10", "name": "Tax", "active": true, "charge_admin_fee": false, "created_at": "2025-01-02T03:04:05Z", "updated_at": "2025-01-02T03:04:05Z", "version": 1 } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/tax_regions": { "post": { "tags": [ "Client" ], "summary": "List tax regions", "description": "**Retrieve all tax regions with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis is a read-only lookup endpoint backed by Hasura. Use it to resolve the\n`taxRegionIds` values accepted by the Client Onboarding endpoint\n(`POST /api/v1/clients/v1/onboard`).\n", "operationId": "getTaxRegionsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 50, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved tax regions", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxRegions": { "type": "array", "items": { "type": "object" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } }, "examples": { "sample": { "summary": "Sample response", "value": { "taxRegions": [ { "id": 10, "name": "California", "active": true, "description": "California state sales tax", "tax_percentage": 7.25, "type": "STATE", "created_at": "2025-01-02T03:04:05Z", "updated_at": "2025-01-02T03:04:05Z" } ], "total": { "aggregate": { "count": 1 } } } } } } } }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/contacts": { "post": { "tags": [ "Contact" ], "summary": "List contacts", "description": "**Retrieve all contacts with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nReturns a paginated list of contacts. Default sort prioritizes last/first name.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/contacts' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getContactsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved contacts" }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/contacts/search": { "post": { "tags": [ "Contact" ], "summary": "Search contacts", "description": "**Advanced contact filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nFilter contacts using boolean logic and relationship-aware fields from `contact_info`.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/contacts/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"contact_info\": {\n \"firstName\": {\n \"_ilike\": \"%john%\"\n }\n }\n },\n {\n \"contact_info\": {\n \"lastName\": {\n \"_ilike\": \"%doe%\"\n }\n }\n }\n ]\n },\n {\n \"active\": {\n \"_eq\": true\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"contact_info\": {\n \"email\": {\n \"_ilike\": \"%@company.com%\"\n }\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"contact_info\": {\n \"lastName\": \"asc\"\n }\n },\n {\n \"createdAt\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "filterContactsDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex contact filtering", "example": { "_and": [ { "_or": [ { "contact_info": { "firstName": { "_ilike": "%john%" } } }, { "contact_info": { "lastName": { "_ilike": "%doe%" } } } ] }, { "active": { "_eq": true } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "contact_info": { "email": { "_ilike": "%@company.com%" } } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering with nested relationship fields", "example": [ { "contact_info": { "lastName": "asc" } }, { "createdAt": "desc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered contacts" }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/contact/{id}": { "get": { "tags": [ "Contact" ], "summary": "Get contact by ID", "description": "**Retrieve a specific contact by its unique identifier**\n\nThis endpoint provides detailed contact information including:\n- Complete contact details and demographics\n- Contact status and relationship information\n- Client associations and roles\n- Communication preferences and history\n- Address and location information\n- Professional and personal details\n\n**Contact Management Features:**\n- Contact lifecycle tracking\n- Client relationship management\n- Communication preference management\n- Address and location tracking\n- Professional information management\n\n**Contact Details Include:**\n- Contact name and demographics\n- Contact status and type\n- Client associations\n- Communication preferences\n- Address information\n- Professional details\n\n**Business Applications:**\n- Contact relationship management\n- Client communication planning\n- Contact database maintenance\n- Professional network management\n- Communication preference tracking\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/contact/23456' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 23456,\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"email\": \"john.smith@acme.com\",\n \"phone\": \"+1-555-0123\",\n \"mobile\": \"+1-555-0456\",\n \"title\": \"Chief Financial Officer\",\n \"department\": \"Finance\",\n \"status\": \"ACTIVE\",\n \"type\": \"CLIENT_CONTACT\",\n \"clientId\": 789,\n \"clientName\": \"Acme Corporation\",\n \"isPrimaryContact\": true,\n \"address\": {\n \"street\": \"123 Business Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"zipCode\": \"10001\",\n \"country\": \"USA\"\n },\n \"communicationPreferences\": {\n \"preferredMethod\": \"EMAIL\",\n \"emailFrequency\": \"WEEKLY\",\n \"newsletterSubscription\": true,\n \"marketingEmails\": false\n },\n \"notes\": \"Primary contact for all financial matters and audit communications\",\n \"createdAt\": \"2023-01-15T10:00:00Z\",\n \"updatedAt\": \"2024-11-20T14:30:00Z\"\n}\n```\n", "operationId": "getContactById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the contact", "schema": { "type": "integer", "minimum": 1 }, "example": 23456 } ], "responses": { "200": { "description": "Contact details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique contact identifier", "example": 23456 }, "firstName": { "type": "string", "description": "Contact first name", "example": "John" }, "lastName": { "type": "string", "description": "Contact last name", "example": "Smith" }, "email": { "type": "string", "format": "email", "description": "Primary email address", "example": "john.smith@acme.com" }, "phone": { "type": "string", "description": "Primary phone number", "example": "+1-555-0123" }, "mobile": { "type": "string", "description": "Mobile phone number", "example": "+1-555-0456" }, "title": { "type": "string", "description": "Job title or position", "example": "Chief Financial Officer" }, "department": { "type": "string", "description": "Department or division", "example": "Finance" }, "status": { "type": "string", "description": "Contact status", "enum": [ "ACTIVE", "INACTIVE", "PENDING", "BLOCKED" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "Contact type", "enum": [ "CLIENT_CONTACT", "PROSPECT", "VENDOR", "PARTNER", "STAFF" ], "example": "CLIENT_CONTACT" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "clientName": { "type": "string", "description": "Client name", "example": "Acme Corporation" }, "isPrimaryContact": { "type": "boolean", "description": "Whether this is the primary contact for the client", "example": true }, "address": { "type": "object", "description": "Contact address information", "properties": { "street": { "type": "string", "description": "Street address", "example": "123 Business Ave" }, "city": { "type": "string", "description": "City", "example": "New York" }, "state": { "type": "string", "description": "State or province", "example": "NY" }, "zipCode": { "type": "string", "description": "ZIP or postal code", "example": "10001" }, "country": { "type": "string", "description": "Country", "example": "USA" } } }, "communicationPreferences": { "type": "object", "description": "Communication preferences", "properties": { "preferredMethod": { "type": "string", "description": "Preferred communication method", "enum": [ "EMAIL", "PHONE", "SMS", "MAIL" ], "example": "EMAIL" }, "emailFrequency": { "type": "string", "description": "Preferred email frequency", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "NEVER" ], "example": "WEEKLY" }, "newsletterSubscription": { "type": "boolean", "description": "Whether subscribed to newsletters", "example": true }, "marketingEmails": { "type": "boolean", "description": "Whether accepts marketing emails", "example": false } } }, "notes": { "type": "string", "description": "Additional notes about the contact", "example": "Primary contact for all financial matters and audit communications" }, "createdAt": { "type": "string", "format": "date-time", "description": "Contact creation timestamp", "example": "2023-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-11-20T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this contact" }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Contact not found" }, "message": { "type": "string", "example": "Contact with ID 23456 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/gql/v1/contacts/by_client/{clientId}": { "get": { "tags": [ "Contact" ], "summary": "Get contacts by client ID", "description": "**Retrieve active contacts associated with a specific client**\n\nReturns all contacts linked to the given client via the contact-client relationship,\nwhere the contact, contact-client link, and contact info are all active.\n\nResults are ordered by last name then first name.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/contacts/by_client/789' \\\n--header 'Authorization: bearer {{token}}'\n```\n", "operationId": "getContactsByClientId", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique identifier of the client", "schema": { "type": "integer", "minimum": 1 }, "example": 789 } ], "responses": { "200": { "description": "Active contacts for the client retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "integer", "description": "Unique contact identifier", "example": 23456 }, "client_id": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "active": { "type": "boolean", "description": "Whether this contact-client relationship is active", "example": true }, "relationship": { "type": "string", "description": "Relationship type between the contact and client", "example": "PRIMARY" }, "receives_invoice": { "type": "boolean", "description": "Whether this contact receives invoices", "example": true }, "receives_statement": { "type": "boolean", "description": "Whether this contact receives statements", "example": false }, "receives_payment_confirmation": { "type": "boolean", "description": "Whether this contact receives payment confirmations", "example": true }, "contact": { "type": "object", "properties": { "id": { "type": "integer", "example": 23456 }, "pms_ref": { "type": "string", "description": "PMS reference identifier", "example": "PMS-001" }, "active": { "type": "boolean", "example": true }, "type": { "type": "string", "description": "Contact type", "example": "CLIENT_CONTACT" }, "fwd_email_confirmation": { "type": "boolean", "description": "Whether to forward email confirmations to this contact", "example": true }, "contact_info": { "type": "object", "properties": { "id": { "type": "integer", "example": 5678 }, "salutation": { "type": "string", "example": "Mr." }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Smith" }, "email": { "type": "string", "format": "email", "example": "john.smith@acme.com" }, "phone": { "type": "string", "example": "+1-555-0123" }, "address": { "type": "string", "example": "123 Business Ave" }, "address2": { "type": "string", "example": "Suite 400" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "country": { "type": "string", "example": "USA" }, "zip_code": { "type": "string", "example": "10001" }, "active": { "type": "boolean", "example": true } } } } } } } } } }, "examples": { "success": { "summary": "Two active contacts for client 789", "value": { "contacts": [ { "contact_id": 23456, "client_id": 789, "active": true, "relationship": "PRIMARY", "receives_invoice": true, "receives_statement": false, "receives_payment_confirmation": true, "contact": { "id": 23456, "pms_ref": "PMS-001", "active": true, "type": "CLIENT_CONTACT", "fwd_email_confirmation": true, "contact_info": { "id": 5678, "salutation": "Mr.", "firstName": "John", "lastName": "Smith", "email": "john.smith@acme.com", "phone": "+1-555-0123", "address": "123 Business Ave", "address2": "Suite 400", "city": "New York", "state": "NY", "country": "USA", "zip_code": "10001", "active": true } } }, { "contact_id": 23457, "client_id": 789, "active": true, "relationship": "BILLING", "receives_invoice": true, "receives_statement": true, "receives_payment_confirmation": false, "contact": { "id": 23457, "pms_ref": "PMS-002", "active": true, "type": "CLIENT_CONTACT", "fwd_email_confirmation": false, "contact_info": { "id": 5679, "salutation": "Ms.", "firstName": "Jane", "lastName": "Taylor", "email": "jane.taylor@acme.com", "phone": "+1-555-0456", "address": "123 Business Ave", "address2": null, "city": "New York", "state": "NY", "country": "USA", "zip_code": "10001", "active": true } } } ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions" }, "500": { "description": "Internal server error" } } } }, "/api/v1/contacts/upsert": { "post": { "tags": [ "Contact" ], "summary": "Upsert Contacts", "description": "\n**Upsert up to 100 contacts, each linked to one or more existing clients, in one request**\n\n Send a `contacts` array (1โ€“100). Each entry upserts a contact (contact_info + contact) and\n its links to existing clients, all by external reference โ€” no Aiwyn internal ids required.\n\n **Partial success.** Each contact is processed independently in its own transaction, so one\n failing contact does not roll back the others. The response splits contacts into `succeeded`\n and `failed` (each keyed by request-order `index`); the HTTP status is 200 whenever the\n request itself is valid โ€” inspect the lists for individual outcomes.\n\n Per contact:\n - Matched by `pmsRef` (contact) and the (contact, client) pair (links); re-sending updates, never duplicates.\n - `pmsRef` optional: omit to create a native contact (mints `AIWYN_`, not idempotent).\n - `clients` optional: omit or `[]` upserts only the contact; unlink via `active: false` (never by absence).\n - `clientRef` resolves by the client's `pmsRef` / `clientRef` / `sysRefs`; refs must not contain `:`.\n - All-or-nothing for that one contact: any unresolved client or stage failure persists nothing for it.\n\n Facade over `POST /api/v1/records`.\n\n**Business Applications:**\n- Bulk contact synchronization\n- Link contacts to existing clients\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/contacts/upsert' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"contacts\": [\n {\n \"pmsRef\": \"CONTACT-001\",\n \"contactInfo\": { \"firstName\": \"Jane\", \"lastName\": \"Smith\", \"email\": \"jane.smith@example.com\" },\n \"clients\": [ { \"clientRef\": \"CLIENT-12345\", \"relationship\": \"Primary Contact\", \"receivesInvoice\": true } ]\n },\n {\n \"pmsRef\": \"CONTACT-002\",\n \"contactInfo\": { \"firstName\": \"John\", \"lastName\": \"Doe\" }\n }\n ]\n}'\n```\n", "operationId": "upsertContact", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "pmsRef": { "type": "string", "description": "Pmsref", "nullable": true }, "contactInfo": { "type": "object", "description": "Contactinfo" }, "username": { "type": "string", "description": "Username", "nullable": true }, "type": { "type": "string", "description": "Type", "nullable": true }, "fwdEmailConfirmation": { "type": "boolean", "description": "Fwdemailconfirmation", "nullable": true }, "fwdEmailConfirmationAddresses": { "type": "string", "description": "Fwdemailconfirmationaddresses", "nullable": true }, "active": { "type": "boolean", "description": "Active", "nullable": true }, "clients": { "type": "array", "items": { "type": "object" }, "description": "Clients" } } }, "description": "Contacts" } } } } } }, "responses": { "200": { "description": "Batch processed; see the succeeded / failed lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "description": "Total" }, "succeeded": { "type": "array", "items": { "type": "object" }, "description": "Succeeded" }, "failed": { "type": "array", "items": { "type": "object" }, "description": "Failed" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request (empty or more than 100 contacts, or malformed body)" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires RECD_C)" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/engagements": { "post": { "tags": [ "Engagement" ], "summary": "List engagements", "description": "**Project engagement tracking with comprehensive workflow management**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis endpoint delivers complete project engagement management including:\n- Client engagement tracking with date-based filtering\n- Multi-level staff assignment management (partner and manager roles)\n- Project status workflow tracking and reporting\n- Template-driven engagement naming and standardization\n- Date range analysis for project timeline management\n\n**Project Management Capabilities:**\n- Start and end date tracking for project lifecycles\n- Status-based workflow management (ACTIVE, COMPLETED, ON_HOLD, EXECUTED, etc.)\n- Staff assignment tracking at partner and manager levels\n- Client relationship management for engagement context\n\n**Workflow Features:**\n- Template-based engagement creation for consistency\n- Status progression tracking for project milestones\n- Staff allocation and responsibility assignment\n- Client-specific engagement history and analysis\n\n**Business Intelligence:**\n- Engagement duration analysis and reporting\n- Staff utilization and assignment tracking\n- Client engagement patterns and history\n- Project status distribution and workflow analysis\n\n**Filtering and Analysis:**\n- Client-specific engagement retrieval\n- Status-based workflow filtering\n- Date range queries for period analysis\n- Staff assignment reporting and allocation\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/engagements' \\\n--header 'Authorization: bearer {{token}} \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getEngagements", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "clientId": { "type": "integer", "description": "Filter engagements by specific client ID", "example": 420 }, "status": { "type": "string", "description": "Filter by engagement status", "enum": [ "ACTIVE", "COMPLETED", "ON_HOLD", "EXECUTED", "CANCELLED", "PLANNED" ], "example": "EXECUTED" }, "startDate": { "type": "string", "format": "date", "description": "Start date for engagement date range filter", "example": "2023-06-29" }, "endDate": { "type": "string", "format": "date", "description": "End date for engagement date range filter", "example": "2023-06-29" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort order for engagement dates", "example": "desc" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved engagement records", "content": { "application/json": { "schema": { "type": "object", "properties": { "deid_engagement": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique engagement identifier", "example": 8 }, "name": { "type": "string", "description": "Generated engagement name from template", "example": "2024 Annual Review and Tax 52150" }, "start_dt": { "type": "string", "format": "date", "description": "Engagement start date", "example": "2024-03-15" }, "end_dt": { "type": "string", "format": "date", "description": "Engagement end date", "example": "2024-04-30" }, "status": { "type": "string", "description": "Current engagement status", "example": "EXECUTED" }, "client_id": { "type": "integer", "description": "Associated client identifier", "example": 420 }, "partner_staff_id": { "type": "integer", "description": "Partner staff member assigned to engagement", "example": 53 }, "manager_staff_id": { "type": "integer", "description": "Manager staff member assigned to engagement", "example": 15 }, "created_at": { "type": "string", "format": "date-time", "description": "Engagement record creation timestamp", "example": "2024-03-14T10:58:38.605333+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Engagement record last update timestamp", "example": "2024-07-27T00:08:05.822177+00:00" }, "engagement_name_template": { "type": "string", "description": "Template used to generate engagement name", "example": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}" }, "client": { "type": "object", "nullable": true, "description": "Associated client details", "properties": { "id": { "type": "integer", "example": 420 }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "number": { "type": "string", "example": "52150" } } }, "partnerStaff": { "type": "object", "nullable": true, "description": "Partner staff member details", "properties": { "id": { "type": "integer", "example": 53 }, "firstName": { "type": "string", "example": "Robert" }, "lastName": { "type": "string", "example": "Johnson" }, "email": { "type": "string", "example": "r.johnson@company.com" } } }, "managerStaff": { "type": "object", "nullable": true, "description": "Manager staff member details", "properties": { "id": { "type": "integer", "example": 15 }, "firstName": { "type": "string", "example": "Sarah" }, "lastName": { "type": "string", "example": "Martinez" }, "email": { "type": "string", "example": "s.martinez@company.com" } } } } } }, "deid_engagement_aggregate": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of engagement records matching criteria", "example": 1 } } } } } } }, "examples": { "successful_response": { "summary": "Engagement records with staff and client details", "value": { "deid_engagement": [ { "id": 8, "name": "2024 Annual Review and Tax 52150", "start_dt": "2024-03-15", "end_dt": "2024-04-30", "status": "EXECUTED", "client_id": 420, "partner_staff_id": 53, "manager_staff_id": 15, "created_at": "2024-03-14T10:58:38.605333+00:00", "updated_at": "2024-07-27T00:08:05.822177+00:00", "engagement_name_template": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}", "client": { "id": 420, "name": "TechFlow Enterprises", "number": "52150" }, "partnerStaff": { "id": 53, "firstName": "Robert", "lastName": "Johnson", "email": "r.johnson@company.com" }, "managerStaff": { "id": 15, "firstName": "Sarah", "lastName": "Martinez", "email": "s.martinez@company.com" } }, { "id": 9, "name": "2024 Quarterly Review 52150", "start_dt": "2024-07-01", "end_dt": "2024-07-15", "status": "ACTIVE", "client_id": 420, "partner_staff_id": 53, "manager_staff_id": 22, "created_at": "2024-06-28T09:30:15.123456+00:00", "updated_at": "2024-07-01T14:22:30.789012+00:00", "engagement_name_template": "{{fiscal_year.year}} {{service_type.name}} {{client.number}}", "client": { "id": 420, "name": "TechFlow Enterprises", "number": "52150" }, "partnerStaff": { "id": 53, "firstName": "Robert", "lastName": "Johnson", "email": "r.johnson@company.com" }, "managerStaff": { "id": 22, "firstName": "David", "lastName": "Chen", "email": "d.chen@company.com" } } ], "deid_engagement_aggregate": { "aggregate": { "count": 2 } } } }, "single_engagement": { "summary": "Single engagement from real API response", "value": { "deid_engagement": [ { "id": 7, "name": "2025 NFP Review and Tax 51840", "start_dt": "2023-06-29", "end_dt": "2023-06-29", "status": "EXECUTED", "client_id": 420, "partner_staff_id": 53, "manager_staff_id": 15, "created_at": "2025-03-14T10:58:38.605333+00:00", "updated_at": "2025-07-27T00:08:05.822177+00:00", "engagement_name_template": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}" } ], "deid_engagement_aggregate": { "aggregate": { "count": 1 } } } }, "empty_response": { "summary": "No engagements found", "value": { "deid_engagement": [], "deid_engagement_aggregate": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "invalid_date_range": { "summary": "Invalid date range", "value": { "error": "startDate must be before or equal to endDate", "code": "INVALID_DATE_RANGE" } }, "invalid_client_id": { "summary": "Invalid client ID", "value": { "error": "clientId must be a positive integer", "code": "INVALID_CLIENT_ID" } } } } } }, "401": { "description": "Unauthorized - missing or invalid admin secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "missing_auth": { "summary": "Missing authentication header", "value": { "error": "x-hasura-admin-secret header is required", "code": "MISSING_AUTH_HEADER" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/gql/v1/engagements/search": { "post": { "tags": [ "Engagement" ], "summary": "Search engagements", "description": "**Search Engagements with Dynamic Filters**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis endpoint allows you to search engagements using dynamic filters, enabling flexible querying based on various criteria.\n\n**Features:**\n- Supports multiple filter conditions\n- Pagination for large result sets\n- Sorting options for results\n\n**Example Usage:**\n```bash\ncurl --location 'https://{{host}}/v1/engagements/search' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"name\": {\n \"_ilike\": \"%review%\"\n }\n },\n {\n \"engagementNameTemplate\": {\n \"_ilike\": \"%tax%\"\n }\n }\n ]\n },\n {\n \"status\": {\n \"_in\": [\"ACTIVE\", \"EXECUTED\"]\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"partnerStaffId\": {\n \"_in\": [\n 5,\n 6,\n 7,\n 8\n ]\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"name\": \"asc\"\n },\n {\n \"createdAt\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "searchEngagementsDynamic", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 1 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex filtering", "example": { "_and": [ { "_or": [ { "name": { "_ilike": "%review%" } }, { "engagementNameTemplate": { "_ilike": "%tax%" } } ] }, { "status": { "_in": [ "ACTIVE", "EXECUTED" ] } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "partnerStaffId": { "_in": [ 5, 6, 7, 8 ] } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications", "example": [ { "name": "asc" }, { "createdAt": "desc" } ] } } }, "examples": { "default_search": { "summary": "Default search with filtering", "value": { "pageSize": 1, "where": { "_and": [ { "_or": [ { "name": { "_ilike": "%review%" } }, { "engagementNameTemplate": { "_ilike": "%tax%" } } ] }, { "status": { "_in": [ "ACTIVE", "EXECUTED" ] } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "partnerStaffId": { "_in": [ 5, 6, 7, 8 ] } } ] }, "orderBy": [ { "name": "asc" }, { "createdAt": "desc" } ] } } } } } }, "responses": { "200": { "description": "Engagements retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "engagements": { "type": "array", "items": { "$ref": "#/components/schemas/Engagement" } }, "totalCount": { "type": "integer", "description": "Total number of engagements matching the filters", "example": 100 } } } } } }, "400": { "description": "Bad Request - Invalid input parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gql/v1/engagement/{id}": { "get": { "tags": [ "Engagement" ], "summary": "Get engagement by ID", "description": "**Retrieve a specific engagement by its unique identifier**\n\nThis endpoint provides detailed engagement information including:\n- Complete engagement details and scope\n- Engagement status and lifecycle information\n- Client relationship and contact details\n- Project portfolio and deliverables\n- Team assignments and resource allocation\n- Financial terms and billing arrangements\n\n**Engagement Management Features:**\n- Engagement lifecycle tracking\n- Client relationship management\n- Project portfolio oversight\n- Team resource allocation\n- Financial terms and billing setup\n\n**Engagement Details Include:**\n- Engagement name and description\n- Engagement status and type\n- Client and contact information\n- Project portfolio details\n- Team assignments\n- Financial terms and billing\n\n**Business Applications:**\n- Engagement status monitoring\n- Client relationship management\n- Project portfolio analysis\n- Resource allocation planning\n- Financial performance tracking\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/engagement/34567' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 34567,\n \"name\": \"Annual Audit Engagement 2024\",\n \"description\": \"Comprehensive annual audit engagement including financial statements, tax preparation, and compliance review\",\n \"status\": \"ACTIVE\",\n \"type\": \"AUDIT\",\n \"clientId\": 789,\n \"clientName\": \"Acme Corporation\",\n \"clientEmail\": \"finance@acme.com\",\n \"clientPhone\": \"+1-555-0123\",\n \"startDate\": \"2024-01-01T00:00:00Z\",\n \"endDate\": \"2024-12-31T23:59:59Z\",\n \"estimatedValue\": 50000.00,\n \"currency\": \"USD\",\n \"projects\": [\n {\n \"id\": 67890,\n \"name\": \"Q4 Financial Audit\",\n \"status\": \"IN_PROGRESS\",\n \"budget\": 25000.00\n },\n {\n \"id\": 67891,\n \"name\": \"Tax Preparation\",\n \"status\": \"PLANNING\",\n \"budget\": 15000.00\n }\n ],\n \"teamMembers\": [\n {\n \"staffId\": 123,\n \"name\": \"John Smith\",\n \"role\": \"ENGAGEMENT_PARTNER\",\n \"allocation\": 0.3\n },\n {\n \"staffId\": 124,\n \"name\": \"Jane Doe\",\n \"role\": \"SENIOR_MANAGER\",\n \"allocation\": 0.8\n }\n ],\n \"billingTerms\": {\n \"billingFrequency\": \"MONTHLY\",\n \"paymentTerms\": \"NET_30\",\n \"rateType\": \"HOURLY\",\n \"defaultRate\": 250.00\n },\n \"notes\": \"Annual engagement with quarterly reviews and monthly billing\",\n \"createdAt\": \"2023-12-15T10:00:00Z\",\n \"updatedAt\": \"2024-11-20T14:30:00Z\"\n}\n```\n", "operationId": "getEngagementById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the engagement", "schema": { "type": "integer", "minimum": 1 }, "example": 34567 } ], "responses": { "200": { "description": "Engagement details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique engagement identifier", "example": 34567 }, "name": { "type": "string", "description": "Engagement name", "example": "Annual Audit Engagement 2024" }, "description": { "type": "string", "description": "Detailed engagement description", "example": "Comprehensive annual audit engagement including financial statements, tax preparation, and compliance review" }, "status": { "type": "string", "description": "Engagement status", "enum": [ "PLANNING", "ACTIVE", "ON_HOLD", "COMPLETED", "CANCELLED" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "Engagement type", "enum": [ "AUDIT", "REVIEW", "COMPILATION", "TAX", "CONSULTING", "ADVISORY" ], "example": "AUDIT" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "clientName": { "type": "string", "description": "Client name", "example": "Acme Corporation" }, "clientEmail": { "type": "string", "description": "Primary client contact email", "example": "finance@acme.com" }, "clientPhone": { "type": "string", "description": "Primary client contact phone", "example": "+1-555-0123" }, "startDate": { "type": "string", "format": "date-time", "description": "Engagement start date", "example": "2024-01-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "Engagement end date", "example": "2024-12-31T23:59:59Z" }, "estimatedValue": { "type": "number", "format": "decimal", "description": "Estimated engagement value", "example": 50000 }, "currency": { "type": "string", "description": "Engagement currency code", "example": "USD" }, "projects": { "type": "array", "description": "Projects within this engagement", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Project identifier", "example": 67890 }, "name": { "type": "string", "description": "Project name", "example": "Q4 Financial Audit" }, "status": { "type": "string", "description": "Project status", "enum": [ "PLANNING", "IN_PROGRESS", "ON_HOLD", "COMPLETED", "CANCELLED" ], "example": "IN_PROGRESS" }, "budget": { "type": "number", "format": "decimal", "description": "Project budget", "example": 25000 } } } }, "teamMembers": { "type": "array", "description": "Team members assigned to the engagement", "items": { "type": "object", "properties": { "staffId": { "type": "integer", "description": "Staff member identifier", "example": 123 }, "name": { "type": "string", "description": "Staff member name", "example": "John Smith" }, "role": { "type": "string", "description": "Role on the engagement", "enum": [ "ENGAGEMENT_PARTNER", "SENIOR_MANAGER", "MANAGER", "SENIOR_AUDITOR", "AUDITOR", "ASSOCIATE" ], "example": "ENGAGEMENT_PARTNER" }, "allocation": { "type": "number", "format": "decimal", "description": "Time allocation percentage (0.0 to 1.0)", "example": 0.3 } } } }, "billingTerms": { "type": "object", "description": "Billing terms and arrangements", "properties": { "billingFrequency": { "type": "string", "description": "Billing frequency", "enum": [ "WEEKLY", "MONTHLY", "QUARTERLY", "UPON_COMPLETION" ], "example": "MONTHLY" }, "paymentTerms": { "type": "string", "description": "Payment terms", "enum": [ "NET_15", "NET_30", "NET_45", "NET_60" ], "example": "NET_30" }, "rateType": { "type": "string", "description": "Rate type", "enum": [ "HOURLY", "FIXED", "PERCENTAGE" ], "example": "HOURLY" }, "defaultRate": { "type": "number", "format": "decimal", "description": "Default hourly rate", "example": 250 } } }, "notes": { "type": "string", "description": "Additional notes or terms", "example": "Annual engagement with quarterly reviews and monthly billing" }, "createdAt": { "type": "string", "format": "date-time", "description": "Engagement creation timestamp", "example": "2023-12-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-11-20T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this engagement" }, "404": { "description": "Engagement not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Engagement not found" }, "message": { "type": "string", "example": "Engagement with ID 34567 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/engagements/{engagementId}": { "patch": { "tags": [ "Engagement" ], "summary": "Update an existing engagement", "description": "**Update an existing engagement by ID**\n\nPartially updates an engagement. Only the fields included in the request body\nare modified โ€” omitted fields are left unchanged. At least one field must be\nprovided.\n\n**Updatable Fields:**\n- Core engagement data (client, fiscal year, partner/manager staff, contacts,\n start/end dates, billing contact, CC staff, name template)\n- Engagement letter template and document template\n- Additional clients assigned to the engagement (full replace when provided)\n- Linked jobs/projects (full replace when provided)\n\n**Validation:**\n- The engagement must exist (404 if not found)\n- The engagement must be in `DRAFT` or `UNDER_REVISION` status (400 otherwise)\n- All provided IDs (additional client IDs, job IDs, etc.) must reference valid records\n- At least one field must be provided (400 if request body is empty)\n\n**Replace behavior:** When `additionalClientIds` or `jobIds` is provided, it fully replaces\nthe existing associations โ€” it is not additive. When `jobIds` is provided without\n`additionalClientIds`, the existing additional clients are preserved.\n\n**Note:** Nullable fields (e.g. `secondaryContactId`, `endDate`) cannot be\nexplicitly cleared to null via this endpoint โ€” omitting them leaves the\nexisting value unchanged.\n\n**Real Example:**\n```bash\ncurl --location --request PATCH 'https://{{host}}/api/v1/engagements/12345' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"fiscalYear\": 2025,\n \"partnerStaffId\": 456,\n \"additionalClientIds\": [789, 790]\n}'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 12345\n}\n```\n", "operationId": "updateEngagement", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "engagementId", "in": "path", "required": true, "description": "Unique identifier of the engagement to update", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "integer", "format": "int64", "description": "ID of the primary client for this engagement", "nullable": true, "example": 789 }, "fiscalYear": { "type": "integer", "format": "int32", "description": "Fiscal year of the engagement", "nullable": true, "example": 2025 }, "partnerStaffId": { "type": "integer", "format": "int64", "description": "ID of the partner staff member assigned to the engagement", "nullable": true, "example": 456 }, "managerStaffId": { "type": "integer", "format": "int64", "description": "ID of the manager staff member assigned to the engagement", "nullable": true, "example": 457 }, "primaryContactId": { "type": "integer", "format": "int64", "description": "ID of the primary contact for this engagement", "nullable": true, "example": 101 }, "secondaryContactId": { "type": "integer", "format": "int64", "description": "ID of the secondary contact for this engagement", "nullable": true, "example": 102 }, "startDate": { "type": "string", "format": "date", "description": "Engagement start date (YYYY-MM-DD)", "nullable": true, "example": "2025-01-01" }, "endDate": { "type": "string", "format": "date", "description": "Engagement end date (YYYY-MM-DD)", "nullable": true, "example": "2025-12-31" }, "billingContactId": { "type": "integer", "format": "int64", "description": "ID of the billing contact for this engagement", "nullable": true, "example": 103 }, "ccStaffIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "IDs of staff members to CC on engagement communications", "nullable": true, "example": [ 458, 459 ] }, "engagementLetterTemplateId": { "type": "integer", "format": "int64", "description": "ID of the engagement letter template to use", "nullable": true, "example": 55 }, "documentTemplateId": { "type": "integer", "format": "int64", "description": "ID of the document template to use", "nullable": true, "example": 66 }, "engagementNameTemplate": { "type": "string", "description": "Template string used to generate the engagement name", "nullable": true, "example": "{clientName} {fiscalYear} Audit" }, "additionalClientIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "IDs of additional clients to associate with this engagement.\nWhen provided, **replaces** all existing additional client associations.\n", "nullable": true, "example": [ 790, 791 ] }, "jobIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "IDs of jobs (projects) to link to this engagement.\nWhen provided, **replaces** all existing job links.\nIf `additionalClientIds` is omitted when `jobIds` is provided, existing additional\nclients are preserved.\n", "nullable": true, "example": [ 101, 102 ] } } } } } }, "responses": { "200": { "description": "Engagement updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "ID of the updated engagement", "example": 12345 } } } } } }, "400": { "description": "Bad request โ€” no update fields provided, or one or more IDs are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid additional client IDs: 999999, 999998" } } } } } }, "401": { "description": "Unauthorized โ€” invalid or missing authentication token" }, "403": { "description": "Forbidden โ€” insufficient permissions (requires ROLE_ENG_C)" }, "404": { "description": "Engagement not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Engagement not found: 12345" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/engagements/create": { "post": { "tags": [ "Engagement" ], "summary": "Create a single engagement", "description": "**Create a single engagement letter**\n\nCreates an engagement letter for a specific client. The engagement letter\nwill be associated with the specified client, fiscal year, and assigned staff.\n\n**Required fields:**\n- `clientId` โ€” the client for whom the engagement is being created\n- `fiscalYear` โ€” the fiscal year of the engagement\n- `partnerStaffId` โ€” the partner staff member assigned to the engagement\n- `managerStaffId` โ€” the manager staff member assigned to the engagement\n- `primaryContactId` โ€” the primary client contact\n\n**Optional fields:**\n- `engagementLetterTemplateId` / `documentTemplateId` โ€” which template to use\n- `engagementNameTemplate` โ€” override the firm's default naming template\n- `startDate` / `endDate` โ€” engagement date range\n- `billingContactId` โ€” contact responsible for billing\n- `secondaryContactId` โ€” secondary client contact\n- `ccStaffIds` โ€” additional staff members to CC on the engagement\n- `additionalClientIds` โ€” additional clients to associate with the engagement\n- `jobIds` โ€” jobs/projects to link to the engagement\n- `additionalDocuments` โ€” extra documents to attach to the engagement, each requiring a `documentTemplateId` and a `documentType`\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/engagements/create' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"clientId\": 420,\n \"fiscalYear\": 2024,\n \"partnerStaffId\": 53,\n \"managerStaffId\": 15,\n \"primaryContactId\": 101\n}'\n```\n", "operationId": "createEngagementLetter", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientId", "fiscalYear", "partnerStaffId", "managerStaffId", "primaryContactId" ], "properties": { "clientId": { "type": "integer", "format": "int64", "description": "Unique identifier of the client for this engagement", "example": 420 }, "fiscalYear": { "type": "integer", "description": "Fiscal year of the engagement", "example": 2024 }, "partnerStaffId": { "type": "integer", "format": "int64", "description": "Unique identifier of the partner staff member", "example": 53 }, "managerStaffId": { "type": "integer", "format": "int64", "description": "Unique identifier of the manager staff member", "example": 15 }, "primaryContactId": { "type": "integer", "format": "int64", "description": "Unique identifier of the primary client contact", "example": 101 }, "secondaryContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the secondary client contact", "example": 102 }, "billingContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the billing contact", "example": 103 }, "engagementLetterTemplateId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the engagement letter template to use", "example": 5 }, "documentTemplateId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the document template to use", "example": 7 }, "engagementNameTemplate": { "type": "string", "nullable": true, "description": "Template string used to generate the engagement name. Overrides the firm's default naming template.\n", "example": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Engagement start date (YYYY-MM-DD)", "example": "2024-01-01" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Engagement end date (YYYY-MM-DD)", "example": "2024-12-31" }, "ccStaffIds": { "type": "array", "nullable": true, "description": "List of staff member IDs to CC on the engagement", "items": { "type": "integer", "format": "int64" }, "example": [ 20, 21 ] }, "additionalClientIds": { "type": "array", "nullable": true, "description": "IDs of additional clients to associate with the engagement", "items": { "type": "integer", "format": "int64" }, "example": [ 790, 791 ] }, "jobIds": { "type": "array", "nullable": true, "description": "IDs of jobs (projects) to link to this engagement", "items": { "type": "integer", "format": "int64" }, "example": [ 101, 102 ] }, "additionalDocuments": { "type": "array", "nullable": true, "description": "Extra documents to attach to the engagement", "items": { "type": "object", "required": [ "documentTemplateId", "documentType" ], "properties": { "documentTemplateId": { "type": "integer", "format": "int64", "description": "Unique identifier of the document template", "example": 12 }, "documentType": { "type": "string", "description": "Type of the document (e.g. ENGAGEMENT_LETTER, ADDITIONAL_DOCUMENT)", "example": "ADDITIONAL_DOCUMENT" } } } } } }, "examples": { "minimal": { "summary": "Minimal required fields", "value": { "clientId": 420, "fiscalYear": 2024, "partnerStaffId": 53, "managerStaffId": 15, "primaryContactId": 101 } }, "full": { "summary": "All fields provided", "value": { "clientId": 420, "fiscalYear": 2024, "partnerStaffId": 53, "managerStaffId": 15, "primaryContactId": 101, "secondaryContactId": 102, "billingContactId": 103, "engagementLetterTemplateId": 5, "documentTemplateId": 7, "engagementNameTemplate": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}", "startDate": "2024-01-01", "endDate": "2024-12-31", "ccStaffIds": [ 20, 21 ], "additionalClientIds": [ 790, 791 ], "jobIds": [ 101, 102 ], "additionalDocuments": [ { "documentTemplateId": 12, "documentType": "ADDITIONAL_DOCUMENT" } ] } } } } } }, "responses": { "200": { "description": "Engagement letter created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the newly created engagement", "example": 34567 } } }, "examples": { "success": { "summary": "Engagement created", "value": { "id": 34567 } } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_ENG_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/engagements/batch/create": { "post": { "tags": [ "Engagement" ], "summary": "Create a batch of engagements", "description": "**Create a batch of engagement letters asynchronously**\n\nSubmits a batch of engagement letter creation requests. The batch is processed\nasynchronously โ€” use the returned batch ID with the\n`GET /api/v1/engagements/batch/{batchId}/status` endpoint to poll for completion\nand retrieve the IDs of the created engagements.\n\n**Batch-level options:**\n- `name` โ€” optional label for the batch\n- `projectTemplateId` โ€” apply a single project template to every engagement in the batch\n- `includeAdditionalClients` โ€” include additional clients when creating engagements\n- `batchEngagements` โ€” array of individual engagement records (required)\n\n**Constraint:** You may provide either `projectTemplateId` (top-level) **or** `projectIds`\non individual engagements โ€” not both.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/engagements/batch/create' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"name\": \"2024 Annual Batch\",\n \"batchEngagements\": [\n {\n \"clientId\": 420,\n \"fiscalYear\": 2024,\n \"partnerStaffId\": 53,\n \"managerStaffId\": 15,\n \"primaryContactId\": 101\n },\n {\n \"clientId\": 421,\n \"fiscalYear\": 2024,\n \"partnerStaffId\": 53,\n \"managerStaffId\": 15,\n \"primaryContactId\": 201\n }\n ]\n}'\n```\n", "operationId": "createBatchEngagementLetters", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "batchEngagements" ], "properties": { "name": { "type": "string", "nullable": true, "description": "Optional label for the batch", "example": "2024 Annual Batch" }, "projectTemplateId": { "type": "integer", "format": "int64", "nullable": true, "description": "Project template ID to apply to every engagement in the batch. Cannot be combined with per-engagement `projectIds`.\n", "example": 10 }, "includeAdditionalClients": { "type": "boolean", "default": false, "description": "Whether to include additional clients when creating engagements", "example": false }, "batchEngagements": { "type": "array", "description": "List of engagement records to create", "items": { "type": "object", "required": [ "clientId", "fiscalYear", "primaryContactId" ], "properties": { "clientId": { "type": "integer", "format": "int64", "description": "Unique identifier of the client", "example": 420 }, "fiscalYear": { "type": "integer", "description": "Fiscal year of the engagement", "example": 2024 }, "primaryContactId": { "type": "integer", "format": "int64", "description": "Unique identifier of the primary client contact", "example": 101 }, "partnerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the partner staff member", "example": 53 }, "managerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the manager staff member", "example": 15 }, "secondaryContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the secondary client contact", "example": 102 }, "billingContactId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the billing contact", "example": 103 }, "engagementLetterTemplateId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the engagement letter template to use", "example": 5 }, "documentTemplateId": { "type": "integer", "format": "int64", "nullable": true, "description": "Unique identifier of the document template to use", "example": 7 }, "engagementNameTemplate": { "type": "string", "nullable": true, "description": "Template string used to generate the engagement name. Overrides the firm's default naming template.\n", "example": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Engagement start date (YYYY-MM-DD)", "example": "2024-01-01" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Engagement end date (YYYY-MM-DD)", "example": "2024-12-31" }, "ccStaffIds": { "type": "array", "nullable": true, "description": "List of staff member IDs to CC on the engagement", "items": { "type": "integer", "format": "int64" }, "example": [ 20, 21 ] }, "projectIds": { "type": "array", "nullable": true, "description": "List of project IDs to associate with this engagement. Cannot be used when a top-level `projectTemplateId` is provided.\n", "items": { "type": "integer", "format": "int64" }, "example": [ 301, 302 ] } } } } } }, "examples": { "minimal": { "summary": "Two engagements, minimal fields", "value": { "batchEngagements": [ { "clientId": 420, "fiscalYear": 2024, "partnerStaffId": 53, "managerStaffId": 15, "primaryContactId": 101 }, { "clientId": 421, "fiscalYear": 2024, "partnerStaffId": 53, "managerStaffId": 15, "primaryContactId": 201 } ] } }, "with_project_template": { "summary": "Batch with a shared project template", "value": { "name": "2024 Annual Batch", "projectTemplateId": 10, "batchEngagements": [ { "clientId": 420, "fiscalYear": 2024, "partnerStaffId": 53, "managerStaffId": 15, "primaryContactId": 101 } ] } } } } } }, "responses": { "200": { "description": "Batch created successfully โ€” process is asynchronous", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the created engagement batch", "example": 9001 } } }, "examples": { "success": { "summary": "Batch accepted", "value": { "id": 9001 } } } } } }, "400": { "description": "Invalid input data โ€” for example, both `projectTemplateId` and per-engagement `projectIds` were provided\n" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_ENG_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/engagements/batch/{batchId}/status": { "get": { "tags": [ "Engagement" ], "summary": "Get engagement batch status", "description": "**Retrieve the status of an engagement batch**\n\nReturns the current processing status of a previously submitted engagement batch,\nalong with the IDs of any engagements that have been created so far.\n\nUse this endpoint to poll for completion after calling\n`POST /api/v1/engagements/batch/create`.\n\n**Batch statuses:**\n- `DRAFT` โ€” batch has been recorded but processing has not started\n- `CREATING` โ€” engagements are actively being created\n- `CREATED` โ€” all engagements in the batch have been created successfully\n- `CANCELED` โ€” the batch was canceled before completion\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/engagements/batch/9001/status' \\\n--header 'Authorization: Bearer {{token}}'\n```\n", "operationId": "getEngagementBatchStatus", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "description": "Unique identifier of the engagement batch", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "example": 9001 } ], "responses": { "200": { "description": "Batch status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "integer", "format": "int64", "description": "Unique identifier of the engagement batch", "example": 9001 }, "status": { "type": "string", "description": "Current processing status of the batch", "enum": [ "DRAFT", "CREATING", "CREATED", "CANCELED" ], "example": "CREATED" }, "engagementIds": { "type": "array", "description": "IDs of engagements created by this batch", "items": { "type": "integer", "format": "int64" }, "example": [ 34567, 34568 ] } } }, "examples": { "in_progress": { "summary": "Batch still creating", "value": { "batchId": 9001, "status": "CREATING", "engagementIds": [ 34567 ] } }, "completed": { "summary": "Batch fully created", "value": { "batchId": 9001, "status": "CREATED", "engagementIds": [ 34567, 34568 ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_ENG_C)" }, "404": { "description": "Batch not found" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/engagement_documents/by_engagement/{engagementId}": { "get": { "tags": [ "Engagement" ], "summary": "Get engagement documents by engagement ID", "description": "**Retrieve documents associated with a specific engagement**\n\nReturns all engagement documents linked to the given engagement ID, including\nthe document type name for each record.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/engagement_documents/by_engagement/34567' \\\n--header 'Authorization: bearer {{token}}'\n```\n", "operationId": "getEngagementDocumentsByEngagementId", "parameters": [ { "name": "engagementId", "in": "path", "required": true, "description": "Unique identifier of the engagement", "schema": { "type": "integer", "minimum": 1 }, "example": 34567 } ], "responses": { "200": { "description": "Engagement documents retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "engagementDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique engagement document identifier", "example": 101 }, "fileId": { "type": "integer", "description": "Associated file identifier", "example": 5001 }, "engagementId": { "type": "integer", "description": "Associated engagement identifier", "example": 34567 }, "engagementDocumentTypeId": { "type": "integer", "description": "Document type identifier", "example": 2 }, "is_active": { "type": "boolean", "description": "Whether this document record is active", "example": true }, "clientFacing": { "type": "boolean", "description": "Whether the document is visible to the client", "example": true }, "blocksExecution": { "type": "boolean", "description": "Whether this document must be signed before the engagement executes", "example": true }, "signatureRequirementType": { "type": "string", "description": "Signature requirement mode", "enum": [ "ALL_SIGNATURES_REQUIRED", "ONE_SIGNATURE_REQUIRED" ], "example": "ALL_SIGNATURES_REQUIRED" }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation timestamp", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Record last updated timestamp", "example": "2024-03-20T14:30:00Z" }, "affirmativeStatus": { "type": "string", "description": "Consent acceptance status of the document. NEGATIVE = one or more negative responses AFFIRMATIVE = all signers responded positively INDETERMINATE = at least one positive response but not all signers have responded yet", "enum": [ "NEGATIVE", "AFFIRMATIVE", "INDETERMINATE" ], "example": "AFFIRMATIVE" }, "documentType": { "type": "object", "description": "The document type associated with this record", "properties": { "id": { "type": "integer", "description": "Document type identifier", "example": 2 }, "name": { "type": "string", "description": "Document type name", "example": "Consent Document" } } } } } } } }, "examples": { "success": { "summary": "Two engagement documents for engagement 34567", "value": { "engagementDocuments": [ { "id": 101, "fileId": 5001, "engagementId": 34567, "engagementDocumentTypeId": 2, "is_active": true, "clientFacing": true, "blocksExecution": true, "signatureRequirementType": "ALL_SIGNATURES_REQUIRED", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-03-20T14:30:00Z", "documentType": { "id": 2, "name": "Consent Document" } }, { "id": 102, "fileId": 5002, "engagementId": 34567, "engagementDocumentTypeId": 6, "is_active": true, "clientFacing": true, "blocksExecution": false, "signatureRequirementType": "ONE_SIGNATURE_REQUIRED", "createdAt": "2024-02-01T09:00:00Z", "updatedAt": "2024-02-01T09:00:00Z", "documentType": { "id": 6, "name": "Add-On Document" } } ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/staff": { "post": { "tags": [ "Staff" ], "summary": "List staff", "description": "**Staff directory and human resource management with organizational structure**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis comprehensive HR endpoint provides complete staff management including:\n- Employee directory with advanced search capabilities\n- Department and organizational structure integration\n- Role-based staff categorization and filtering\n- Active/inactive employee status management\n- Multi-field name search with partial matching\n\n**HR Management Capabilities:**\n- Complete employee directory with contact information\n- Department-based organizational structure tracking\n- Role, wage type, and employee type classifications\n- Active employee status for current workforce analysis\n- Employee search across first and last names\n\n**Organizational Features:**\n- Department hierarchy and staff allocation\n- Role and permission-set categorization\n- Employee status management (active/inactive)\n- Contact information and communication data\n- Staff reference and external system integration\n\n**Search and Filter Options:**\n- Multi-field name search (first name, last name)\n- Department-based staff filtering\n- Active status filtering for current employees\n- Role and employment-type categorization\n- Alphabetical sorting for directory listings\n\n**Business Applications:**\n- Employee directory and contact management\n- HR reporting and organizational analysis\n- Department staff allocation and planning\n- Employee onboarding and management workflows\n- Integration with external HR and payroll systems\n\n**Directory Features:**\n- Complete contact information management\n- Department, service line, role, permission, and supervisor relationship tracking\n- Staff reference system for external integration\n- Employee status and lifecycle management\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/staff' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n\n**Permissions:**\n", "operationId": "getStaff", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "isActive": { "type": "boolean", "description": "Filter by active employee status", "example": true }, "departmentId": { "type": "integer", "description": "Filter staff by specific department ID", "example": 7 }, "nameSearch": { "type": "string", "description": "Search term for first and last names (use % for wildcard)", "example": "%" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "Sort order for staff names", "example": "asc" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved staff records", "content": { "application/json": { "schema": { "type": "object", "properties": { "staff": { "type": "array", "items": { "$ref": "#/components/schemas/StaffDirectoryRecord" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of staff records matching criteria", "example": 138 } } } } } } }, "examples": { "successful_response": { "summary": "Staff directory with department and type information", "value": { "staff": [ { "id": 202, "pmsRef": "2254", "staffRef": "HAB", "firstName": "Holley", "lastName": "Abbott", "email": "ena.toy@hotmail.com", "active": true, "deptId": 8, "jobTitle": null, "type": null, "officeId": 2, "serviceLine": { "id": 4, "pmsRef": "TAX", "name": "Tax" }, "subServiceLine": { "id": 12, "pmsRef": "TAX-COMP", "name": "Tax Compliance" }, "wageType": { "id": 1, "pmsRef": "SAL", "name": "Salary" }, "employeeType": { "id": 2, "pmsRef": "FT", "name": "Full Time" }, "role": { "id": 11, "pmsRef": "MANAGER", "display": "Manager", "description": "Manager" }, "permissionSet": { "id": 3, "name": "Standard Manager" }, "staffSupervisor": { "id": 53, "pmsRef": "A53", "staffRef": "AH", "firstName": "Allen", "lastName": "Hermiston", "email": "allen.hermiston@company.com" }, "staffManagerId": 53, "updatedAt": "2026-09-21T18:30:00Z" } ], "total": { "aggregate": { "count": 138 } } } }, "empty_response": { "summary": "No staff found", "value": { "staff": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "invalid_department_id": { "summary": "Invalid department ID", "value": { "error": "departmentId must be a positive integer", "code": "INVALID_DEPARTMENT_ID" } }, "invalid_page": { "summary": "Invalid page number", "value": { "error": "page must be non-negative", "code": "INVALID_PAGE" } } } } } }, "401": { "description": "Unauthorized - insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "insufficient_permissions": { "summary": "User lacks required role", "value": { "error": "Access denied. Missing Roles", "code": "INSUFFICIENT_PERMISSIONS" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/gql/v1/staff/search": { "post": { "tags": [ "Staff" ], "summary": "Search staff", "description": "**Advanced staff filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nProvides flexible, enterprise-grade filtering for staff directory queries with boolean logic,\nrelationship traversal, and multi-field ordering.\n\nEach result includes service and sub-service lines, wage and employee types, `role`\n(formerly `staffType`), permission set, supervisor, and the record's `updatedAt` timestamp.\n\nKey capabilities include boolean operators (`_and`, `_or`, `_not`), text matching (`_ilike`),\ncomparison operators (`_gt`, `_gte`, `_lt`, `_lte`, `_eq`, `_neq`), array operators (`_in`, `_nin`),\nand nested/related filtering (e.g., by office or manager).\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/staff/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"firstName\": {\n \"_ilike\": \"%john%\"\n }\n },\n {\n \"lastName\": {\n \"_ilike\": \"%doe%\"\n }\n }\n ]\n },\n {\n \"active\": {\n \"_eq\": true\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"deptId\": {\n \"_in\": [\n 1,\n 2,\n 3\n ]\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"lastName\": \"asc\"\n },\n {\n \"firstName\": \"asc\"\n }\n ]\n}'\n```\n", "operationId": "filterStaffDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 1 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex staff filtering", "example": { "_and": [ { "_or": [ { "firstName": { "_ilike": "%john%" } }, { "lastName": { "_ilike": "%doe%" } } ] }, { "active": { "_eq": true } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "deptId": { "_in": [ 1, 2, 3 ] } } ] } }, "orderBy": { "type": "array", "description": "Dynamic ordering specifications with multiple fields", "items": { "type": "object" }, "example": [ { "lastName": "asc" }, { "firstName": "asc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered staff with dynamic ordering", "content": { "application/json": { "schema": { "type": "object", "properties": { "staff": { "type": "array", "items": { "$ref": "#/components/schemas/StaffDirectoryRecord" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of staff records matching criteria", "example": 1 } } } } } } }, "examples": { "filtered_response": { "summary": "Filtered staff with dynamic ordering", "value": { "staff": [ { "id": 202, "pmsRef": "2254", "firstName": "Holley", "lastName": "Abbott", "email": "ena.toy@hotmail.com", "active": true, "deptId": 8, "jobTitle": null, "type": null, "officeId": 2, "serviceLine": { "id": 4, "pmsRef": "TAX", "name": "Tax" }, "subServiceLine": { "id": 12, "pmsRef": "TAX-COMP", "name": "Tax Compliance" }, "wageType": { "id": 1, "pmsRef": "SAL", "name": "Salary" }, "employeeType": { "id": 2, "pmsRef": "FT", "name": "Full Time" }, "role": { "id": 11, "pmsRef": "MANAGER", "display": "Manager", "description": "Manager" }, "permissionSet": { "id": 3, "name": "Standard Manager" }, "staffSupervisor": { "id": 53, "pmsRef": "A53", "staffRef": "AH", "firstName": "Allen", "lastName": "Hermiston", "email": "allen.hermiston@company.com" }, "staffManagerId": 53, "updatedAt": "2026-09-21T18:30:00Z" } ], "total": { "aggregate": { "count": 1 } } } }, "empty_response": { "summary": "No staff found matching criteria", "value": { "staff": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/staff/{id}": { "get": { "tags": [ "Staff" ], "summary": "Get staff member by ID", "description": "**Retrieve a specific staff member by their unique identifier**\n\nThis endpoint provides staff member information including:\n- Staff member identification and PMS reference\n- Personal details (name and email)\n- Employment status and organizational structure\n- Department and office assignments\n- Service line, employment classification, permissions, and reporting relationships\n\n**Staff Details Include:**\n- Staff member ID and PMS reference\n- Personal information (first name, last name, email)\n- Active status indicator\n- Department and office identifiers\n- Job title and role (when available)\n- Wage type and employee type\n- Permission set, manager, and supervisor assignments\n- Last-updated timestamp\n\n**Business Applications:**\n- Staff member lookup and verification\n- Organizational structure queries\n- Basic staff information retrieval\n- Department and office staff management\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/staff/123' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 202,\n \"pmsRef\": \"2254\",\n \"firstName\": \"Holley\",\n \"lastName\": \"Abbott\",\n \"email\": \"ena.toy@hotmail.com\",\n \"active\": true,\n \"deptId\": 8,\n \"jobTitle\": null,\n \"type\": null,\n \"officeId\": 2,\n \"serviceLine\": { \"id\": 4, \"pmsRef\": \"TAX\", \"name\": \"Tax\" },\n \"subServiceLine\": { \"id\": 12, \"pmsRef\": \"TAX-COMP\", \"name\": \"Tax Compliance\" },\n \"wageType\": { \"id\": 1, \"pmsRef\": \"SAL\", \"name\": \"Salary\" },\n \"employeeType\": { \"id\": 2, \"pmsRef\": \"FT\", \"name\": \"Full Time\" },\n \"role\": {\n \"id\": 11,\n \"pmsRef\": \"MANAGER\",\n \"display\": \"Manager\",\n \"description\": \"Manager\"\n },\n \"permissionSet\": { \"id\": 3, \"name\": \"Standard Manager\" },\n \"staffSupervisor\": {\n \"id\": 53,\n \"pmsRef\": \"A53\",\n \"staffRef\": \"AH\",\n \"firstName\": \"Allen\",\n \"lastName\": \"Hermiston\",\n \"email\": \"allen.hermiston@company.com\"\n },\n \"staffManagerId\": 53,\n \"updatedAt\": \"2026-09-21T18:30:00Z\"\n}\n```\n", "operationId": "getStaffById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the staff member", "schema": { "type": "integer", "minimum": 1 }, "example": 123 } ], "responses": { "200": { "description": "Staff member details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffDirectoryRecord" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this staff member" }, "404": { "description": "Staff member not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Staff member not found" }, "message": { "type": "string", "example": "Staff member with ID 123 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/staff": { "post": { "tags": [ "Staff" ], "summary": "Onboard a new staff member", "description": "**Create a new staff member, optionally assigning them to a rate card**\n\nCreates a staff record and, when `rateCardAssignment` is provided, atomically\ncreates the corresponding billing rate and average cost records in the same\ntransaction.\n\n**Required fields:**\n- `firstName` โ€” staff member's first name\n- `lastName` โ€” staff member's last name\n- `pmsRef` โ€” practice management system reference\n- `ref` โ€” unique staff reference code\n\n**Rate card assignment** (`rateCardAssignment`):\nWhen provided, the rate card must already exist. Each entry in `billingRates`\nrequires a valid `rateTypeId`. All three records (staff, billing rates, average\ncost) are created atomically โ€” if any write fails the entire request is rolled back.\n- `rateCardId` โ€” ID of an existing rate card (validated before any writes)\n- `billingRates` โ€” one record per rate type; each requires a `rateTypeId`\n- `averageCost` โ€” single average hourly cost for this staff member (optional)\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/staff' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"pmsRef\": \"EMP-1042\",\n \"ref\": \"doe-j\",\n \"email\": \"jane.doe@firm.com\",\n \"jobTitle\": \"Senior Associate\",\n \"active\": true,\n \"rateCardAssignment\": {\n \"rateCardId\": 5,\n \"billingRates\": [\n { \"rateTypeId\": 12, \"hourlyBillingRate\": 150.00 },\n { \"rateTypeId\": 13, \"hourlyBillingRate\": 175.00 }\n ],\n \"averageCost\": 75.00\n }\n}'\n```\n", "operationId": "onboardStaff", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName", "lastName", "pmsRef", "ref" ], "properties": { "firstName": { "type": "string", "description": "Staff member's first name", "example": "Jane" }, "lastName": { "type": "string", "description": "Staff member's last name", "example": "Doe" }, "pmsRef": { "type": "string", "description": "Practice management system reference identifier", "example": "EMP-1042" }, "ref": { "type": "string", "description": "Unique staff reference code", "example": "doe-j" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Primary email address", "example": "jane.doe@firm.com" }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title (free-text)", "example": "Senior Associate" }, "jobTitleId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of a job title lookup record", "example": 7 }, "departmentId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the department this staff member belongs to", "example": 3 }, "officeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the office this staff member is based in", "example": 2 }, "orgId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the organization", "example": 1 }, "serviceLineId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the service line", "example": 4 }, "staffTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the staff type (e.g. Partner, Manager, Associate)", "example": 2 }, "partnerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the partner staff member assigned to this person", "example": 50 }, "managerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the manager staff member", "example": 30 }, "supervisorStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the supervisor staff member", "example": null }, "prefix": { "type": "string", "nullable": true, "description": "Name prefix (e.g. Dr., Ms.)", "example": "Ms." }, "startDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Employment start date", "example": "2024-01-15T00:00:00" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Employment end date", "example": null }, "active": { "type": "boolean", "default": true, "description": "Whether the staff member is active", "example": true }, "rateCardAssignment": { "type": "object", "nullable": true, "description": "Optional rate card assignment. When provided, billing rate and average\ncost records are created atomically with the staff record.\n`rateCardId` and all `rateTypeId` values must reference existing records\nor the entire request is rejected with HTTP 400.\n", "required": [ "rateCardId", "billingRates" ], "properties": { "rateCardId": { "type": "integer", "format": "int64", "description": "ID of an existing rate card to assign this staff member to", "example": 5 }, "billingRates": { "type": "array", "description": "One billing rate record per rate type. Can be an empty array if only an average cost is being set.\n", "items": { "type": "object", "required": [ "rateTypeId" ], "properties": { "rateTypeId": { "type": "integer", "format": "int64", "description": "ID of an existing rate type", "example": 12 }, "hourlyBillingRate": { "type": "number", "format": "decimal", "nullable": true, "description": "Hourly billing rate in the firm's currency. Defaults to 0 when omitted.", "example": 150 } } } }, "averageCost": { "type": "number", "format": "decimal", "nullable": true, "description": "Average hourly cost for this staff member. One record per rate card assignment.", "example": 75 } } } } }, "examples": { "minimal": { "summary": "Minimal required fields only", "value": { "firstName": "Jane", "lastName": "Doe", "pmsRef": "EMP-1042", "ref": "doe-j" } }, "with_rate_card": { "summary": "Staff with full rate card assignment", "value": { "firstName": "Jane", "lastName": "Doe", "pmsRef": "EMP-1042", "ref": "doe-j", "email": "jane.doe@firm.com", "jobTitle": "Senior Associate", "active": true, "rateCardAssignment": { "rateCardId": 5, "billingRates": [ { "rateTypeId": 12, "hourlyBillingRate": 150 }, { "rateTypeId": 13, "hourlyBillingRate": 175 } ], "averageCost": 75 } } } } } } }, "responses": { "201": { "description": "Staff member created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the created staff member", "example": 312 }, "pmsRef": { "type": "string", "example": "EMP-1042" }, "ref": { "type": "string", "example": "doe-j" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "fullName": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "jane.doe@firm.com" }, "jobTitle": { "type": "string", "nullable": true, "example": "Senior Associate" }, "departmentId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "officeId": { "type": "integer", "format": "int64", "nullable": true, "example": null }, "active": { "type": "boolean", "example": true }, "version": { "type": "integer", "format": "int64", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-03-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-03-15T10:00:00Z" }, "rateCardAssignment": { "type": "object", "nullable": true, "description": "Present only when a rate card assignment was provided in the request", "properties": { "rateCardId": { "type": "integer", "format": "int64", "description": "ID of the rate card the staff member was assigned to", "example": 5 }, "billingRateIds": { "type": "array", "description": "IDs of the created rate_card_staff_billing_rate records", "items": { "type": "integer", "format": "int64" }, "example": [ 101, 102 ] }, "averageCostId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the created rate_card_staff_average_cost record, or null if averageCost was not provided", "example": 201 } } } } }, "meta": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Staff member created successfully" }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-03-15T10:00:00Z" }, "version": { "type": "string", "example": "v1" } } } } }, "examples": { "staff_only": { "summary": "Staff created without rate card assignment", "value": { "data": { "id": 312, "pmsRef": "EMP-1042", "ref": "doe-j", "firstName": "Jane", "lastName": "Doe", "fullName": "Jane Doe", "email": "jane.doe@firm.com", "active": true, "version": 1, "createdAt": "2024-03-15T10:00:00Z", "updatedAt": "2024-03-15T10:00:00Z", "rateCardAssignment": null }, "meta": { "success": true, "message": "Staff member created successfully", "timestamp": "2024-03-15T10:00:00Z", "version": "v1" } } }, "staff_with_rate_card": { "summary": "Staff created with billing rates and average cost", "value": { "data": { "id": 312, "pmsRef": "EMP-1042", "ref": "doe-j", "firstName": "Jane", "lastName": "Doe", "fullName": "Jane Doe", "email": "jane.doe@firm.com", "active": true, "version": 1, "createdAt": "2024-03-15T10:00:00Z", "updatedAt": "2024-03-15T10:00:00Z", "rateCardAssignment": { "rateCardId": 5, "billingRateIds": [ 101, 102 ], "averageCostId": 201 } }, "meta": { "success": true, "message": "Staff member created successfully", "timestamp": "2024-03-15T10:00:00Z", "version": "v1" } } } } } } }, "400": { "description": "Invalid request. Common causes:\n- Missing required fields (`firstName`, `lastName`, `pmsRef`, `ref`)\n- `rateCardAssignment.rateCardId` does not reference an existing rate card\n- One or more `rateTypeId` values in `billingRates` do not exist\n" }, "401": { "description": "Unauthorized โ€” missing or invalid bearer token" }, "403": { "description": "Forbidden โ€” token does not have the `ROLE_API_ADMIN` role" }, "500": { "description": "Internal server error" } } } }, "/api/v1/staff/{staffId}": { "put": { "tags": [ "Staff" ], "summary": "Update a staff member", "description": "**Update an existing staff member's profile and optionally replace their rate card assignment**\n\nAll fields are optional โ€” only the fields you include will be updated. Omitted fields\nretain their current values.\n\n**Rate card assignment replacement** (`rateCardAssignment`):\nWhen provided, this operation atomically:\n1. Deactivates **all** active `rate_card_staff_billing_rate` and\n `rate_card_staff_average_cost` records currently linked to this staff member\n (across any rate card).\n2. Creates new records for the specified `rateCardId`.\n\nOmitting `rateCardAssignment` entirely leaves existing rate card records untouched.\n\nPre-write validation ensures `rateCardId` and all `rateTypeId` values reference\nexisting records โ€” if any are invalid the entire request is rejected with HTTP 400\nand no changes are written.\n\n**Real Example:**\n```bash\ncurl --location --request PUT 'https://{{host}}/api/v1/staff/312' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"jobTitle\": \"Manager\",\n \"rateCardAssignment\": {\n \"rateCardId\": 6,\n \"billingRates\": [\n { \"rateTypeId\": 12, \"hourlyBillingRate\": 200.00 }\n ],\n \"averageCost\": 95.00\n }\n}'\n```\n", "operationId": "updateStaff", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "staffId", "in": "path", "required": true, "description": "Unique identifier of the staff member to update", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "example": 312 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "nullable": true, "description": "Updated first name", "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "description": "Updated last name", "example": "Doe" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Updated primary email address", "example": "jane.doe@firm.com" }, "jobTitle": { "type": "string", "nullable": true, "description": "Updated job title (free-text)", "example": "Manager" }, "jobTitleId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated job title lookup record ID", "example": 8 }, "departmentId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated department ID", "example": 3 }, "officeId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated office ID", "example": 2 }, "orgId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated organization ID", "example": 1 }, "serviceLineId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated service line ID", "example": 4 }, "staffTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated staff type ID (e.g. Partner, Manager, Associate)", "example": 3 }, "partnerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated partner staff member ID", "example": 50 }, "managerStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated manager staff member ID", "example": 31 }, "supervisorStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "Updated supervisor staff member ID", "example": null }, "prefix": { "type": "string", "nullable": true, "description": "Updated name prefix", "example": "Dr." }, "startDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated employment start date", "example": "2023-06-01T00:00:00" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated employment end date", "example": null }, "active": { "type": "boolean", "nullable": true, "description": "Updated active status", "example": true }, "rateCardAssignment": { "type": "object", "nullable": true, "description": "When provided, replaces the staff member's entire rate card assignment.\nAll current active billing rate and average cost records are deactivated\nand new records are created for the specified rate card. Validated before\nany writes โ€” invalid `rateCardId` or `rateTypeId` values return HTTP 400.\n", "required": [ "rateCardId", "billingRates" ], "properties": { "rateCardId": { "type": "integer", "format": "int64", "description": "ID of the rate card to assign", "example": 6 }, "billingRates": { "type": "array", "description": "New billing rate records to create, one per rate type. Can be an empty array if only the average cost is being updated.\n", "items": { "type": "object", "required": [ "rateTypeId" ], "properties": { "rateTypeId": { "type": "integer", "format": "int64", "description": "ID of an existing rate type", "example": 12 }, "hourlyBillingRate": { "type": "number", "format": "decimal", "nullable": true, "description": "Hourly billing rate. Defaults to 0 when omitted.", "example": 200 } } } }, "averageCost": { "type": "number", "format": "decimal", "nullable": true, "description": "New average hourly cost. Omit to leave the average cost unset.", "example": 95 } } } } }, "examples": { "fields_only": { "summary": "Update staff fields only (no rate card change)", "value": { "jobTitle": "Manager", "departmentId": 4, "active": true } }, "replace_rate_card": { "summary": "Replace rate card assignment", "value": { "rateCardAssignment": { "rateCardId": 6, "billingRates": [ { "rateTypeId": 12, "hourlyBillingRate": 200 } ], "averageCost": 95 } } }, "fields_and_rate_card": { "summary": "Update fields and replace rate card in one request", "value": { "jobTitle": "Senior Manager", "rateCardAssignment": { "rateCardId": 6, "billingRates": [ { "rateTypeId": 12, "hourlyBillingRate": 200 }, { "rateTypeId": 13, "hourlyBillingRate": 225 } ], "averageCost": 95 } } } } } } }, "responses": { "200": { "description": "Staff member updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Staff member identifier", "example": 312 }, "pmsRef": { "type": "string", "example": "EMP-1042" }, "ref": { "type": "string", "example": "doe-j" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "fullName": { "type": "string", "nullable": true, "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "jane.doe@firm.com" }, "jobTitle": { "type": "string", "nullable": true, "example": "Manager" }, "active": { "type": "boolean", "example": true }, "version": { "type": "integer", "format": "int64", "example": 2 }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-03-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-06-01T09:00:00Z" }, "rateCardAssignment": { "type": "object", "nullable": true, "description": "Present only when `rateCardAssignment` was provided in the request. Contains the IDs of the newly created records.\n", "properties": { "rateCardId": { "type": "integer", "format": "int64", "example": 6 }, "billingRateIds": { "type": "array", "description": "IDs of the newly created rate_card_staff_billing_rate records", "items": { "type": "integer", "format": "int64" }, "example": [ 205 ] }, "averageCostId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the newly created rate_card_staff_average_cost record, or null if averageCost was not provided", "example": 301 } } } } }, "meta": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Staff member updated successfully" }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-06-01T09:00:00Z" }, "version": { "type": "string", "example": "v1" } } } } }, "examples": { "fields_updated": { "summary": "Fields updated, no rate card change", "value": { "data": { "id": 312, "pmsRef": "EMP-1042", "ref": "doe-j", "firstName": "Jane", "lastName": "Doe", "fullName": "Jane Doe", "jobTitle": "Manager", "active": true, "version": 2, "updatedAt": "2024-06-01T09:00:00Z", "rateCardAssignment": null }, "meta": { "success": true, "message": "Staff member updated successfully", "timestamp": "2024-06-01T09:00:00Z", "version": "v1" } } }, "rate_card_replaced": { "summary": "Rate card assignment replaced", "value": { "data": { "id": 312, "pmsRef": "EMP-1042", "ref": "doe-j", "firstName": "Jane", "lastName": "Doe", "fullName": "Jane Doe", "jobTitle": "Manager", "active": true, "version": 2, "updatedAt": "2024-06-01T09:00:00Z", "rateCardAssignment": { "rateCardId": 6, "billingRateIds": [ 205 ], "averageCostId": 301 } }, "meta": { "success": true, "message": "Staff member updated successfully", "timestamp": "2024-06-01T09:00:00Z", "version": "v1" } } } } } } }, "400": { "description": "Invalid request. Common causes:\n- `rateCardAssignment.rateCardId` does not reference an existing rate card\n- One or more `rateTypeId` values in `billingRates` do not exist\n" }, "401": { "description": "Unauthorized โ€” missing or invalid bearer token" }, "403": { "description": "Forbidden โ€” token does not have the `ROLE_API_ADMIN` role" }, "404": { "description": "Staff member not found for the given `staffId`" }, "500": { "description": "Internal server error" } } } }, "/api/v1/staff/type/batch/create": { "post": { "tags": [ "Staff" ], "summary": "Create staff types in batch", "description": "\n**Create staff types in batch**\n\n Creates up to **100** staff types in a single request.\n\n Notes:\n - The request body is JSON ``{ \"items\": [ ... ] }`` where ``items`` is an array of staff type objects (same shape as single ``/create``).\n - ``items`` must contain **1โ€“100** elements; otherwise the request is rejected with **400**.\n - Successful creates appear under `succeeded`; failures appear under `failed` with an error message (partial success is allowed).\n - **201** when every item succeeds; **422** when every item fails; **200** when there is a mix of successes and failures.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/staff/type/batch/create' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"items\": [\n { \"display\": \"Associate\", \"description\": \"Associate staff type\" },\n { \"display\": \"Manager\", \"description\": \"Manager staff type\" }\n ]\n}'\n```\n", "operationId": "StaffTypeBatchCreate", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "display": { "type": "string", "description": "Display" }, "description": { "type": "string", "description": "Description", "nullable": true }, "permissionSetId": { "type": "integer", "format": "int64", "description": "Permissionsetid", "nullable": true } } }, "description": "Items" } } } } } }, "responses": { "201": { "description": "All staff types were created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32", "description": "Index" }, "display": { "type": "string", "description": "Display" }, "id": { "type": "integer", "format": "int64", "description": "Id" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires STF_TYP_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/staff/type/batch/lookup": { "post": { "tags": [ "Staff" ], "summary": "Lookup staff types (paged)", "description": "\n**Lookup staff types page by page**\n\n Returns a page of staff types ordered by id ascending.\n\n Notes:\n - `pageSize` must be between **1** and **100**\n - `page` is zero-based (`page` 0 is the first page)\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/staff/type/batch/lookup' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{ \"pageSize\": 25, \"page\": 0 }'\n```\n", "operationId": "StaffTypeBatchLookup", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "format": "int32", "description": "Pagesize" }, "page": { "type": "integer", "format": "int32", "description": "Page" } } } } } }, "responses": { "200": { "description": "Lookup completed successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of STF_TYP_R, STF_TYP_C)" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/invoices": { "post": { "tags": [ "Invoices" ], "summary": "List invoices", "description": "**Retrieve invoices with comprehensive filtering and financial data**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis endpoint delivers complete invoice management functionality with:\n- Advanced pagination for large invoice datasets\n- Multi-dimensional filtering (client, status, date ranges)\n- Integration with AR transactions for complete financial context\n- Tax, interest, and payment status tracking\n- Client relationship data for each invoice\n- Aggregate counting for reporting and analytics\n\n**Key Financial Features:**\n- Invoice status tracking (PENDING, PAID, OVERDUE, POSTED, etc.)\n- Tax and interest calculations included\n- Due date monitoring for collections management\n- AR transaction linkage for payment reconciliation\n- Amount and allocation tracking for financial reporting\n\n**Filtering Capabilities:**\n- Client-specific invoice retrieval\n- Status-based filtering for workflow management \n- Date range queries for period reporting\n- Sorting by creation date or transaction date\n\n**Business Applications:**\n- Accounts receivable management and aging reports\n- Client billing history and statement generation\n- Collections management and overdue tracking\n- Financial reporting and revenue recognition\n- Payment reconciliation and allocation tracking\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/invoices' \\\n--header 'Authorization: bearer {{token}} \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getInvoices", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "clientId": { "type": "integer", "description": "Filter invoices by specific client ID", "example": 7720 }, "status": { "type": "string", "description": "Filter by invoice status", "enum": [ "PENDING", "POSTED", "PAID", "OVERDUE", "CANCELLED", "DRAFT" ], "example": "POSTED" }, "startDate": { "type": "string", "format": "date-time", "description": "Start date for invoice date range filter", "example": "1990-01-01T00:00:00" }, "endDate": { "type": "string", "format": "date-time", "description": "End date for invoice date range filter", "example": "2024-12-31T23:59:59" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort order for invoice dates", "example": "desc" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved invoice records", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "arTranId": { "type": "integer", "description": "Invoice identifier (equal to the AR transaction id)", "example": 125890 }, "invoiceNumber": { "type": "string", "description": "Unique invoice number for client reference", "example": "INV-2024-4850" }, "dueDate": { "type": "string", "format": "date-time", "description": "Invoice payment due date", "example": "2024-04-24T05:00:00" }, "status": { "type": "string", "description": "Current invoice status", "example": "POSTED" }, "tax": { "type": "number", "format": "decimal", "description": "Tax amount charged on invoice", "example": 0 }, "interest": { "type": "number", "format": "decimal", "description": "Interest charges applied to invoice", "example": 0 }, "description": { "type": "string", "nullable": true, "description": "Additional invoice description or notes", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "Invoice record creation timestamp", "example": "2024-05-12T22:50:20.595961+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Invoice record last update timestamp", "example": "2024-05-12T22:50:20.595961+00:00" }, "ar_tran": { "type": "object", "description": "Associated AR transaction details", "properties": { "id": { "type": "integer", "example": 125890 }, "pmsRef": { "type": "string", "description": "Practice management system reference", "example": "240815" }, "transactionDate": { "type": "string", "format": "date-time", "description": "Transaction date", "example": "2024-03-22T05:00:00" }, "amount": { "type": "number", "format": "decimal", "description": "Transaction amount", "example": 4250 }, "allocated": { "type": "number", "format": "decimal", "description": "Allocated amount", "example": 4250 }, "clientId": { "type": "integer", "description": "Client identifier", "example": 7720 } } } } } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of invoices", "example": 94 } } } } } } }, "examples": { "successful_response": { "summary": "Invoice records with AR transaction details", "value": { "invoices": [ { "arTranId": 125890, "invoiceNumber": "INV-2024-4850", "dueDate": "2024-04-24T05:00:00", "status": "POSTED", "tax": 0, "interest": 0, "description": null, "createdAt": "2024-05-12T22:50:20.595961+00:00", "updatedAt": "2024-05-12T22:50:20.595961+00:00", "ar_tran": { "id": 125890, "pmsRef": "240815", "transactionDate": "2024-03-22T05:00:00", "amount": 4250, "allocated": 4250, "clientId": 7720 } }, { "arTranId": 125234, "invoiceNumber": "INV-2024-4721", "dueDate": "2024-03-03T05:00:00", "status": "POSTED", "tax": 0, "interest": 0, "description": null, "createdAt": "2024-05-12T22:50:10.982058+00:00", "updatedAt": "2024-05-12T22:50:10.982058+00:00", "ar_tran": { "id": 125234, "pmsRef": "239842", "transactionDate": "2024-02-04T05:00:00", "amount": 3750, "allocated": 3750, "clientId": 7720 } }, { "arTranId": 124856, "invoiceNumber": "INV-2024-4592", "dueDate": "2024-02-07T05:00:00", "status": "POSTED", "tax": 0, "interest": 0, "description": null, "createdAt": "2024-05-12T22:50:09.194501+00:00", "updatedAt": "2024-05-12T22:50:09.194501+00:00", "ar_tran": { "id": 124856, "pmsRef": "238967", "transactionDate": "2024-01-08T05:00:00", "amount": 2850, "allocated": 2850, "clientId": 7720 } } ], "total": { "aggregate": { "count": 94 } } } }, "real_api_response": { "summary": "Sample from actual API response", "value": { "invoices": [ { "arTranId": 119859, "invoiceNumber": "4618", "dueDate": "2023-03-24T05:00:00", "status": "POSTED", "tax": 0, "interest": 0, "description": null, "createdAt": "2023-05-12T22:50:20.595961+00:00", "updatedAt": "2023-05-12T22:50:20.595961+00:00", "ar_tran": { "id": 119859, "pmsRef": "224081", "transactionDate": "2023-02-22T05:00:00", "amount": 0, "allocated": 0, "clientId": 7720 } }, { "arTranId": 96162, "invoiceNumber": "74080", "dueDate": "2018-10-11T04:00:00", "status": "POSTED", "tax": 0, "interest": 0, "description": null, "createdAt": "2023-05-12T22:50:08.928921+00:00", "updatedAt": "2023-05-12T22:50:08.928921+00:00", "ar_tran": { "id": 96162, "pmsRef": "108840", "transactionDate": "2018-09-11T04:00:00", "amount": 3516, "allocated": 3516, "clientId": 7720 } } ], "total": { "aggregate": { "count": 94 } } } }, "empty_response": { "summary": "No invoices found", "value": { "invoices": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "invalid_date_range": { "summary": "Invalid date range", "value": { "error": "startDate must be before or equal to endDate", "code": "INVALID_DATE_RANGE" } }, "invalid_client_id": { "summary": "Invalid client ID", "value": { "error": "clientId must be a positive integer", "code": "INVALID_CLIENT_ID" } } } } } }, "401": { "description": "Unauthorized - missing or invalid admin secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "missing_auth": { "summary": "Missing authentication header", "value": { "error": "x-hasura-admin-secret header is required", "code": "MISSING_AUTH_HEADER" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/gql/v1/invoices/search": { "post": { "tags": [ "Invoices" ], "summary": "Search invoices", "description": "**Advanced invoice filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nSupports invoiceNumber text matching, status filtering, and date ranges.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/invoices/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"invoiceNumber\": {\n \"_ilike\": \"%2024%\"\n }\n },\n {\n \"description\": {\n \"_ilike\": \"%service%\"\n }\n }\n ]\n },\n {\n \"status\": {\n \"_in\": [\"POSTED\", \"CLOSED\"]\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"dueDate\": {\n \"_gte\": \"2024-01-01T00:00:00Z\"\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"invoiceNumber\": \"asc\"\n },\n {\n \"createdAt\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "filterInvoicesDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex invoice filtering", "example": { "_and": [ { "_or": [ { "invoiceNumber": { "_ilike": "%2024%" } }, { "description": { "_ilike": "%service%" } } ] }, { "status": { "_in": [ "POSTED", "CLOSED" ] } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "dueDate": { "_gte": "2024-01-01T00:00:00Z" } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications", "example": [ { "invoiceNumber": "asc" }, { "createdAt": "desc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "arTranId": { "type": "integer", "description": "Invoice identifier (equal to the AR transaction id)", "example": 125890 }, "invoiceNumber": { "type": "string", "example": "INV-2024-4850" }, "dueDate": { "type": "string", "format": "date-time", "example": "2024-04-24T05:00:00" }, "status": { "type": "string", "example": "POSTED" }, "tax": { "type": "number", "description": "Tax amount recorded on the invoice", "example": 0 }, "interest": { "type": "number", "description": "Interest amount recorded on the invoice", "example": 0 }, "description": { "type": "string", "nullable": true, "example": null }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-05-12T22:50:20.595961+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-05-12T22:50:20.595961+00:00" }, "ar_tran": { "type": "object", "description": "Associated AR transaction details", "properties": { "id": { "type": "integer", "example": 125890 }, "pmsRef": { "type": "string", "description": "Practice-management-system reference", "example": "240815" }, "transactionDate": { "type": "string", "format": "date-time", "example": "2024-03-22T05:00:00" }, "amount": { "type": "number", "description": "Total transaction amount", "example": 4250 }, "allocated": { "type": "number", "description": "Amount allocated (applied/paid) against the transaction", "example": 4250 }, "clientId": { "type": "integer", "example": 7720 } } } } } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of invoices matching the where clause", "example": 12 } } } } } } } } } }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/invoice/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice by ID", "description": "**Retrieve a specific invoice by its unique identifier**\n\nThis endpoint provides detailed invoice information including:\n- Complete invoice details and line items\n- Invoice status and payment tracking\n- Client and project relationships\n- Tax calculations and compliance data\n- Payment history and outstanding balances\n- Document generation and delivery status\n\n**Invoice Management Features:**\n- Invoice lifecycle tracking\n- Payment status monitoring\n- Tax calculation and compliance\n- Client relationship integration\n- Document generation and delivery\n\n**Invoice Details Include:**\n- Invoice number and reference\n- Invoice status and payment status\n- Client and project information\n- Line items and amounts\n- Tax calculations\n- Payment history\n\n**Business Applications:**\n- Invoice status monitoring\n- Payment tracking and reconciliation\n- Client billing history\n- Revenue recognition analysis\n- Tax compliance reporting\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/invoice/45678' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"arTranId\": 45678,\n \"invoiceNumber\": \"INV-2024-001\",\n \"dueDate\": \"2024-12-31T23:59:59Z\",\n \"status\": \"POSTED\",\n \"tax\": 2000.00,\n \"interest\": 0.00,\n \"description\": \"Q4 Financial Audit\",\n \"createdAt\": \"2024-12-01T09:00:00Z\",\n \"updatedAt\": \"2024-12-15T10:30:00Z\",\n \"ar_tran\": {\n \"id\": 45678,\n \"pmsRef\": \"AR-2024-045678\",\n \"transactionDate\": \"2024-12-01T00:00:00Z\",\n \"amount\": 22000.00,\n \"allocated\": 15000.00,\n \"clientId\": 789\n }\n}\n```\n", "operationId": "getInvoiceById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the invoice", "schema": { "type": "integer", "minimum": 1 }, "example": 45678 } ], "responses": { "200": { "description": "Invoice details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "arTranId": { "type": "integer", "description": "Invoice identifier (equal to the AR transaction id)", "example": 45678 }, "invoiceNumber": { "type": "string", "description": "Invoice number", "example": "INV-2024-001" }, "dueDate": { "type": "string", "format": "date-time", "description": "Invoice due date", "example": "2024-12-31T23:59:59Z" }, "status": { "type": "string", "description": "Invoice status", "example": "POSTED" }, "tax": { "type": "number", "description": "Tax amount recorded on the invoice", "example": 2000 }, "interest": { "type": "number", "description": "Interest amount recorded on the invoice", "example": 0 }, "description": { "type": "string", "description": "Invoice description", "example": "Q4 Financial Audit" }, "createdAt": { "type": "string", "format": "date-time", "description": "Invoice creation timestamp", "example": "2024-12-01T09:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-12-15T10:30:00Z" }, "ar_tran": { "type": "object", "description": "Underlying accounts-receivable transaction", "properties": { "id": { "type": "integer", "description": "AR transaction identifier", "example": 45678 }, "pmsRef": { "type": "string", "description": "Practice-management-system reference", "example": "AR-2024-045678" }, "transactionDate": { "type": "string", "format": "date-time", "description": "AR transaction date", "example": "2024-12-01T00:00:00Z" }, "amount": { "type": "number", "description": "Total transaction amount", "example": 22000 }, "allocated": { "type": "number", "description": "Amount allocated (applied/paid) against the transaction", "example": 15000 }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this invoice" }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invoice not found" }, "message": { "type": "string", "example": "Invoice with ID 45678 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/invoices/unpaid": { "get": { "tags": [ "Invoices" ], "summary": "List a client's unpaid invoices", "description": "**Return the unpaid invoices of one client, resolved by client reference**\n\nThe client is resolved by `clientRef`, the same identifier `POST /api/v1/clients/v1/link/payment`\naccepts, and the invoices returned are exactly the ones that endpoint accepts in `invoiceIds` or\n`invoiceNumbers`: active invoices whose amount is larger than what has been allocated to them so\nfar. Fully paid, reversed, inactive and unposted (draft) invoices are not returned. Invoices are ordered by due date,\nthen invoice number.\n\nAmounts are decimal strings in the firm's currency. `outstanding` is `amount - allocated`.\n\nThe `id` of each invoice is the value to pass as `invoiceIds` when creating a payment link.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/invoices/unpaid?clientRef=ACME-001' \\\n--header 'Authorization: bearer {{token}}'\n```\n", "operationId": "getUnpaidInvoicesByClientRef", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "clientRef", "in": "query", "required": true, "description": "Client reference of the client whose unpaid invoices are requested.", "schema": { "type": "string" }, "example": "ACME-001" } ], "responses": { "200": { "description": "Client resolved and its unpaid invoices returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "example": 7720 }, "clientRef": { "type": "string", "example": "ACME-001" }, "name": { "type": "string", "example": "Acme Corporation" } } }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Invoice identifier, accepted by the payment link endpoint as `invoiceIds`", "example": 125890 }, "invoiceNumber": { "type": "string", "description": "Invoice number, accepted by the payment link endpoint as `invoiceNumbers`", "example": "INV-2026-4850" }, "description": { "type": "string", "nullable": true, "example": "2025 individual tax return" }, "status": { "type": "string", "enum": [ "POSTED", "CLOSED", "CANCEL", "REVERSED" ], "example": "POSTED" }, "transactionDate": { "type": "string", "format": "date", "example": "2026-08-01" }, "dueDate": { "type": "string", "format": "date", "nullable": true, "example": "2026-08-31" }, "amount": { "type": "string", "description": "Invoice total, decimal string", "example": "1250.00" }, "allocated": { "type": "string", "description": "Amount already paid or credited against the invoice, decimal string", "example": "250.00" }, "outstanding": { "type": "string", "description": "Amount still owed, decimal string", "example": "1000.00" } } } } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } }, "example": { "data": { "client": { "id": 7720, "clientRef": "ACME-001", "name": "Acme Corporation" }, "invoices": [ { "id": 125890, "invoiceNumber": "INV-2026-4850", "description": "2025 individual tax return", "status": "POSTED", "transactionDate": "2026-08-01", "dueDate": "2026-08-31", "amount": "1250.00", "allocated": "250.00", "outstanding": "1000.00" } ] }, "error": null, "meta": { "success": true, "message": "Unpaid invoices retrieved successfully", "timestamp": "2026-09-02T14:03:11.412Z" } } } } }, "400": { "description": "`clientRef` blank (`CLIENT_REF_REQUIRED`), more than one client carries that reference\n(`CLIENT_REF_AMBIGUOUS`), or the client is inactive (`CLIENT_INACTIVE`). The code is in `error.code`.\n" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires INVC_R or API_ADMIN)" }, "404": { "description": "No client with that reference (`error.code` is `CLIENT_NOT_FOUND`)" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/payments": { "post": { "tags": [ "Payments" ], "summary": "List payments", "description": "**Retrieve payment records with transaction details and security compliance**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis endpoint provides secure payment data access with:\n- PCI-compliant payment information (masked card data)\n- Payment method categorization and tracking\n- Integration with AR transactions for complete context\n- Payment processor integration (PayPal, Stripe, etc.)\n- Date-based filtering for reconciliation periods\n- Client relationship data for payment attribution\n\n**Security & Compliance:**\n- PCI DSS compliant data handling (last 4 digits only)\n- Secure payment processor ID tracking\n- Payment confirmation date logging\n- Audit trail for payment processing\n\n**Payment Method Support:**\n- Credit/debit card payments with masked PAN\n- ACH/bank transfer processing\n- Check and wire transfer tracking\n- Digital wallet integration (PayPal, Apple Pay, etc.)\n\n**Reconciliation Features:**\n- Payment-to-invoice matching via AR transactions\n- Payment confirmation status tracking\n- Processor reference ID management\n- Multi-currency payment support\n\n**Business Applications:**\n- Payment reconciliation and matching\n- Revenue recognition and cash flow analysis\n- Client payment history and patterns\n- Payment method performance analysis\n- Compliance reporting and audit trails\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/payments' \\\n--header 'Authorization: bearer {{token}} \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getPayments", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "clientId": { "type": "integer", "description": "Filter payments by specific client ID", "example": 789 }, "paymentMethod": { "type": "string", "description": "Filter by payment method type", "enum": [ "CREDIT_CARD", "DEBIT_CARD", "ACH", "BANK_TRANSFER", "CHECK", "WIRE", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY" ], "example": "CREDIT_CARD" }, "startDate": { "type": "string", "format": "date-time", "description": "Start date for payment date range filter", "example": "2024-01-01T00:00:00" }, "endDate": { "type": "string", "format": "date-time", "description": "End date for payment date range filter", "example": "2024-12-31T23:59:59" }, "status": { "type": "string", "description": "Filter by payment status", "enum": [ "PENDING", "CONFIRMED", "FAILED", "CANCELLED", "REFUNDED" ], "example": "CONFIRMED" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort order for payment date", "example": "desc" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved payment records", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_ar_tran_id": { "type": "integer", "description": "AR transaction id of the payment", "example": 1048 }, "ar_transaction_date": { "type": "string", "format": "date-time", "description": "Date/time of the AR transaction", "example": "2026-09-01T15:00:34.317714" }, "client_name": { "type": "string", "description": "Name of the client the payment belongs to", "example": "Acme Corporation" }, "client_ref": { "type": "string", "description": "External client reference number", "example": "1337" }, "invoice_numbers": { "type": "string", "nullable": true, "description": "Comma-separated invoice numbers the payment is applied to", "example": null }, "is_aiwyn_payment": { "type": "boolean", "description": "Whether the payment was created through Aiwyn", "example": true }, "is_partial_payment": { "type": "boolean", "description": "Whether the payment only partially covers the billed amount", "example": false }, "is_payment_success": { "type": "boolean", "description": "Whether the payment succeeded", "example": true }, "notes": { "type": "string", "nullable": true, "description": "Free-text notes on the payment", "example": "Paid by check" }, "engagement_names": { "type": "string", "nullable": true, "description": "Names of engagements associated with the payment", "example": null }, "paid_by_full_name": { "type": "string", "nullable": true, "description": "Full name of the payer", "example": "Jane Doe" }, "payment_payment_method": { "type": "string", "nullable": true, "description": "Human-readable payment method", "example": "Bank Transfer" }, "payment_pp_id": { "type": "string", "nullable": true, "description": "Payment processor (Stripe) identifier", "example": "pi_3UAtArIog7gyKVjp2xxxxxx" }, "refund_date": { "type": "string", "nullable": true, "description": "Date of refund, if refunded", "example": null }, "refund_status": { "type": "string", "nullable": true, "description": "Refund status, if refunded", "example": null }, "staff_admin_id": { "type": "boolean", "description": "Staff/admin association flag", "example": true }, "status": { "type": "string", "description": "Human-readable payment status", "example": "Completed" }, "total_bill_amount": { "type": "number", "nullable": true, "description": "Total billed amount", "example": null }, "amount": { "type": "number", "description": "Payment amount", "example": 10 }, "principal": { "type": "number", "description": "Principal portion of the payment", "example": 10 }, "total_processing_fee_amount": { "type": "number", "description": "Total processing fee amount", "example": 0 }, "total_international_fee_amount": { "type": "number", "description": "Total international fee amount", "example": 0 }, "total_late_fee_amount": { "type": "number", "description": "Total late fee amount", "example": 0 }, "is_posted": { "type": "boolean", "description": "Whether the payment has been posted to the bank", "example": false }, "posted_to_bank_dt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date/time the payment was posted to the bank", "example": null }, "estimated_deposit_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Estimated deposit date", "example": null }, "dispute_status": { "type": "string", "nullable": true, "description": "Dispute status, if disputed", "example": null }, "dispute_refund_date": { "type": "string", "nullable": true, "description": "Date of dispute-related refund, if any", "example": null }, "total_bill_amount_in_currency": { "type": "number", "nullable": true, "description": "Total billed amount in the payment's currency", "example": null }, "amount_in_currency": { "type": "number", "nullable": true, "description": "Payment amount in the payment's currency", "example": null }, "principal_in_currency": { "type": "number", "nullable": true, "description": "Principal portion in the payment's currency", "example": null }, "total_processing_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total processing fee in the payment's currency", "example": null }, "total_international_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total international fee in the payment's currency", "example": null }, "total_late_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total late fee in the payment's currency", "example": null }, "currency_code": { "type": "string", "nullable": true, "description": "ISO currency code of the payment", "example": null } } } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of payment records", "example": 97 } } } } } } }, "examples": { "successful_response": { "summary": "Typical response with payment data", "value": { "payments": [ { "payment_ar_tran_id": 1048, "ar_transaction_date": "2026-09-01T15:00:34.317714", "client_name": "Client Test", "client_ref": "1337", "invoice_numbers": null, "is_aiwyn_payment": true, "is_partial_payment": false, "is_payment_success": true, "notes": "inv 33", "engagement_names": null, "paid_by_full_name": "Client Test", "payment_payment_method": "Bank Transfer", "payment_pp_id": "pi_3UAtArIog7gyKVjp2xxxxx", "refund_date": null, "refund_status": null, "staff_admin_id": true, "status": "Completed", "total_bill_amount": null, "amount": 10, "principal": 10, "total_processing_fee_amount": 0, "total_international_fee_amount": 0, "total_late_fee_amount": 0, "is_posted": false, "posted_to_bank_dt": null, "estimated_deposit_date": null, "dispute_status": null, "dispute_refund_date": null, "total_bill_amount_in_currency": null, "amount_in_currency": null, "principal_in_currency": null, "total_processing_fee_amount_in_currency": null, "total_international_fee_amount_in_currency": null, "total_late_fee_amount_in_currency": null, "currency_code": null } ], "total": { "aggregate": { "count": 97 } } } }, "empty_response": { "summary": "No payments (or offset at/beyond total)", "value": { "payments": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "invalid_date_range": { "summary": "Invalid date range", "value": { "error": "startDate must be before or equal to endDate", "code": "INVALID_DATE_RANGE" } }, "invalid_payment_method": { "summary": "Invalid payment method", "value": { "error": "Invalid payment method specified", "code": "INVALID_PAYMENT_METHOD" } } } } } }, "401": { "description": "Unauthorized - missing or invalid admin secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "missing_auth": { "summary": "Missing authentication header", "value": { "error": "x-hasura-admin-secret header is required", "code": "MISSING_AUTH_HEADER" } } } } } }, "403": { "description": "Forbidden - insufficient permissions for payment data access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions for payment data", "value": { "error": "Access to payment data requires elevated permissions", "code": "INSUFFICIENT_PAYMENT_PERMISSIONS" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/gql/v1/payments/search": { "post": { "tags": [ "Payments" ], "summary": "Search payments", "description": "**Advanced payment filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nBacked by view `vw_payment_history_firm_table`. Supports text matching, date ranges, and flags.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/payments/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"paymentMethod\": {\n \"_ilike\": \"%CREDIT%\"\n }\n },\n {\n \"cardType\": {\n \"_ilike\": \"%VISA%\"\n }\n }\n ]\n },\n {\n \"isAutomatic\": {\n \"_eq\": false\n }\n },\n {\n \"createdAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"paymentConfirmationDate\": {\n \"_is_null\": false\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"paymentConfirmationDate\": \"desc\"\n },\n {\n \"createdAt\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "filterPaymentsDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex payment filtering", "example": { "_and": [ { "_or": [ { "paymentMethod": { "_ilike": "%CREDIT%" } }, { "cardType": { "_ilike": "%VISA%" } } ] }, { "isAutomatic": { "_eq": false } }, { "createdAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "paymentConfirmationDate": { "_is_null": false } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications", "example": [ { "paymentConfirmationDate": "desc" }, { "createdAt": "desc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_ar_tran_id": { "type": "integer", "description": "AR transaction id of the payment", "example": 1048 }, "ar_transaction_date": { "type": "string", "format": "date-time", "description": "Date/time of the AR transaction", "example": "2026-09-01T15:00:34.317714" }, "client_name": { "type": "string", "description": "Name of the client the payment belongs to", "example": "Acme Corporation" }, "client_ref": { "type": "string", "description": "External client reference number", "example": "1337" }, "invoice_numbers": { "type": "string", "nullable": true, "description": "Comma-separated invoice numbers the payment is applied to", "example": null }, "is_aiwyn_payment": { "type": "boolean", "description": "Whether the payment was created through Aiwyn", "example": true }, "is_partial_payment": { "type": "boolean", "description": "Whether the payment only partially covers the billed amount", "example": false }, "is_payment_success": { "type": "boolean", "description": "Whether the payment succeeded", "example": true }, "notes": { "type": "string", "nullable": true, "description": "Free-text notes on the payment", "example": "Paid by check" }, "engagement_names": { "type": "string", "nullable": true, "description": "Names of engagements associated with the payment", "example": null }, "paid_by_full_name": { "type": "string", "nullable": true, "description": "Full name of the payer", "example": "Jane Doe" }, "payment_payment_method": { "type": "string", "nullable": true, "description": "Human-readable payment method", "example": "Bank Transfer" }, "payment_pp_id": { "type": "string", "nullable": true, "description": "Payment processor (Stripe) identifier", "example": "pi_3UAtArIog7gyKVjp2cNQXIBJ" }, "refund_date": { "type": "string", "nullable": true, "description": "Date of refund, if refunded", "example": null }, "refund_status": { "type": "string", "nullable": true, "description": "Refund status, if refunded", "example": null }, "staff_admin_id": { "type": "boolean", "description": "Staff/admin association flag", "example": true }, "status": { "type": "string", "description": "Human-readable payment status", "example": "Completed" }, "total_bill_amount": { "type": "number", "nullable": true, "description": "Total billed amount", "example": null }, "amount": { "type": "number", "description": "Payment amount", "example": 10 }, "principal": { "type": "number", "description": "Principal portion of the payment", "example": 10 }, "total_processing_fee_amount": { "type": "number", "description": "Total processing fee amount", "example": 0 }, "total_international_fee_amount": { "type": "number", "description": "Total international fee amount", "example": 0 }, "total_late_fee_amount": { "type": "number", "description": "Total late fee amount", "example": 0 }, "is_posted": { "type": "boolean", "description": "Whether the payment has been posted to the bank", "example": false }, "posted_to_bank_dt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date/time the payment was posted to the bank", "example": null }, "estimated_deposit_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Estimated deposit date", "example": null }, "dispute_status": { "type": "string", "nullable": true, "description": "Dispute status, if disputed", "example": null }, "dispute_refund_date": { "type": "string", "nullable": true, "description": "Date of dispute-related refund, if any", "example": null }, "total_bill_amount_in_currency": { "type": "number", "nullable": true, "description": "Total billed amount in the payment's currency", "example": null }, "amount_in_currency": { "type": "number", "nullable": true, "description": "Payment amount in the payment's currency", "example": null }, "principal_in_currency": { "type": "number", "nullable": true, "description": "Principal portion in the payment's currency", "example": null }, "total_processing_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total processing fee in the payment's currency", "example": null }, "total_international_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total international fee in the payment's currency", "example": null }, "total_late_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total late fee in the payment's currency", "example": null }, "currency_code": { "type": "string", "nullable": true, "description": "ISO currency code of the payment", "example": null } } } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of payments matching the where clause", "example": 12 } } } } } } } } } }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/payment/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get payment by ID", "description": "**Retrieve a specific payment by its unique identifier**\n\nThis endpoint provides detailed payment information including:\n- Complete payment transaction details\n- PCI-compliant payment method information (masked)\n- Payment status and confirmation data\n- Associated invoice and client relationships\n- Payment processor integration details\n- Audit trail and security compliance data\n\n**Security & Compliance:**\n- PCI DSS compliant data handling\n- Secure payment processor ID tracking\n- Payment confirmation date logging\n- Audit trail for payment processing\n\n**Payment Details Include:**\n- Payment amount and currency\n- Payment method (masked for security)\n- Payment status and confirmation\n- Associated invoice references\n- Client relationship data\n- Payment processor details\n\n**Business Applications:**\n- Payment verification and reconciliation\n- Client payment history lookup\n- Payment dispute resolution\n- Audit and compliance reporting\n- Payment method analysis\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/payment/12345' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\nThe `payment` field is an array containing at most one record (empty if the\nid does not exist).\n\n**Response Example:**\n```json\n{\n \"payment\": [\n {\n \"payment_ar_tran_id\": 1048,\n \"ar_transaction_date\": \"2026-09-01T15:00:34.317714\",\n \"client_name\": \"Acme Corporation\",\n \"client_ref\": \"1337\",\n \"invoice_numbers\": null,\n \"is_aiwyn_payment\": true,\n \"is_partial_payment\": false,\n \"is_payment_success\": true,\n \"notes\": \"Paid by check\",\n \"engagement_names\": null,\n \"paid_by_full_name\": \"Jane Doe\",\n \"payment_payment_method\": \"Bank Transfer\",\n \"payment_pp_id\": \"pi_3UAtArIog7gyKVjp2cNQXIBJ\",\n \"refund_date\": null,\n \"refund_status\": null,\n \"staff_admin_id\": true,\n \"status\": \"Completed\",\n \"total_bill_amount\": null,\n \"amount\": 10,\n \"principal\": 10,\n \"total_processing_fee_amount\": 0,\n \"total_international_fee_amount\": 0,\n \"total_late_fee_amount\": 0,\n \"is_posted\": false,\n \"posted_to_bank_dt\": null,\n \"estimated_deposit_date\": null,\n \"dispute_status\": null,\n \"dispute_refund_date\": null,\n \"total_bill_amount_in_currency\": null,\n \"amount_in_currency\": null,\n \"principal_in_currency\": null,\n \"total_processing_fee_amount_in_currency\": null,\n \"total_international_fee_amount_in_currency\": null,\n \"total_late_fee_amount_in_currency\": null,\n \"currency_code\": null\n }\n ]\n}\n```\n", "operationId": "getPaymentById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the payment", "schema": { "type": "integer", "minimum": 1 }, "example": 12345 } ], "responses": { "200": { "description": "Payment details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "type": "array", "description": "Array containing the matching payment (empty if not found)", "items": { "type": "object", "properties": { "payment_ar_tran_id": { "type": "integer", "description": "AR transaction id of the payment (the id used by this endpoint)", "example": 1048 }, "ar_transaction_date": { "type": "string", "format": "date-time", "description": "Date/time of the AR transaction", "example": "2026-09-01T15:00:34.317714" }, "client_name": { "type": "string", "description": "Name of the client the payment belongs to", "example": "Acme Corporation" }, "client_ref": { "type": "string", "description": "External client reference number", "example": "1337" }, "invoice_numbers": { "type": "string", "nullable": true, "description": "Comma-separated invoice numbers the payment is applied to", "example": null }, "is_aiwyn_payment": { "type": "boolean", "description": "Whether the payment was created through Aiwyn", "example": true }, "is_partial_payment": { "type": "boolean", "description": "Whether the payment only partially covers the billed amount", "example": false }, "is_payment_success": { "type": "boolean", "description": "Whether the payment succeeded", "example": true }, "notes": { "type": "string", "nullable": true, "description": "Free-text notes on the payment", "example": "Paid by check" }, "engagement_names": { "type": "string", "nullable": true, "description": "Names of engagements associated with the payment", "example": null }, "paid_by_full_name": { "type": "string", "nullable": true, "description": "Full name of the payer", "example": "Jane Doe" }, "payment_payment_method": { "type": "string", "nullable": true, "description": "Human-readable payment method", "example": "Bank Transfer" }, "payment_pp_id": { "type": "string", "nullable": true, "description": "Payment processor (Stripe) identifier", "example": "pi_3UAtArIog7gyKVjp2cNQXIBJ" }, "refund_date": { "type": "string", "nullable": true, "description": "Date of refund, if refunded", "example": null }, "refund_status": { "type": "string", "nullable": true, "description": "Refund status, if refunded", "example": null }, "staff_admin_id": { "type": "boolean", "description": "Staff/admin association flag", "example": true }, "status": { "type": "string", "description": "Human-readable payment status", "example": "Completed" }, "total_bill_amount": { "type": "number", "nullable": true, "description": "Total billed amount", "example": null }, "amount": { "type": "number", "description": "Payment amount", "example": 10 }, "principal": { "type": "number", "description": "Principal portion of the payment", "example": 10 }, "total_processing_fee_amount": { "type": "number", "description": "Total processing fee amount", "example": 0 }, "total_international_fee_amount": { "type": "number", "description": "Total international fee amount", "example": 0 }, "total_late_fee_amount": { "type": "number", "description": "Total late fee amount", "example": 0 }, "is_posted": { "type": "boolean", "description": "Whether the payment has been posted to the bank", "example": false }, "posted_to_bank_dt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date/time the payment was posted to the bank", "example": null }, "estimated_deposit_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Estimated deposit date", "example": null }, "dispute_status": { "type": "string", "nullable": true, "description": "Dispute status, if disputed", "example": null }, "dispute_refund_date": { "type": "string", "nullable": true, "description": "Date of dispute-related refund, if any", "example": null }, "total_bill_amount_in_currency": { "type": "number", "nullable": true, "description": "Total billed amount in the payment's currency", "example": null }, "amount_in_currency": { "type": "number", "nullable": true, "description": "Payment amount in the payment's currency", "example": null }, "principal_in_currency": { "type": "number", "nullable": true, "description": "Principal portion in the payment's currency", "example": null }, "total_processing_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total processing fee in the payment's currency", "example": null }, "total_international_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total international fee in the payment's currency", "example": null }, "total_late_fee_amount_in_currency": { "type": "number", "nullable": true, "description": "Total late fee in the payment's currency", "example": null }, "currency_code": { "type": "string", "nullable": true, "description": "ISO currency code of the payment", "example": null } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this payment" }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment not found" }, "message": { "type": "string", "example": "Payment with ID 12345 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/clients/v1/link/payment": { "post": { "tags": [ "Payments" ], "summary": "Create a payment link for a client", "description": "**Create a single-use quick payment link that lets a client pay in the Aiwyn payment portal**\n\nThe client is resolved by `clientRef`, the same identifier the client carries in the firm's\npractice management system. Exactly one active client must match.\n\nThe link is locked to the arguments given: the payer sees the selected invoices, the amount and\nthe note prefilled and cannot change them, and the link accepts one payment. Use it to gate a\ndeliverable behind a specific invoice. At least one of `invoiceIds`, `invoiceNumbers`, `amount`,\n`note`, `returnUrl`, `returnLabel` or `returnAutomatically` must be present; a body carrying only `clientRef` is rejected\nwith `400`, because this route never issues a link to the client's full account. Invoices must\nbelong to the client and must be unpaid; use `GET /api/v1/invoices/unpaid` to list them. The link\nid (the `qpLink` query parameter of the returned URL) is echoed back as `metadata.paymentLinkPlId`\non the `Payment` webhook events the payment raises, so a payment can be matched to the link that\nproduced it.\n\nA quick payment link can carry a `returnUrl`. After a successful payment the portal sends the\npayer back to it (the URL is disclosed only on the charge result, never when the link is opened).\nThe URL must be `https` and its host must be on the firm's `payment_return_url_allowed_hosts`\nconfiguration; a firm without that configuration rejects any `returnUrl` with `400`.\n`returnLabel` names that destination on the return button. `returnAutomatically: true` asks the\nportal to return on its own after the confirmation, after a short countdown, instead of waiting\nfor the payer to press the button: it navigates to `returnUrl` when the link has one, and\notherwise closes the payment tab, which it can do only when your system opened that tab by\nscript.\n\nThe body is decoded strictly: a key that is not one of `clientRef`, `invoiceIds`, `invoiceNumbers`,\n`amount`, `note`, `returnUrl`, `returnLabel`, `returnAutomatically` is rejected with `400` instead\nof being ignored.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/clients/v1/link/payment' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"clientRef\": \"ACME-001\",\n \"invoiceIds\": [125890],\n \"note\": \"2025 individual tax return\"\n}'\n```\n", "operationId": "createClientPaymentLink", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientRef" ], "properties": { "clientRef": { "type": "string", "description": "Client reference of the client the link is for. Exactly one active client must match.", "example": "ACME-001" }, "invoiceIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Unpaid invoices of the client to lock the link to, by invoice `id`. At most 100 invoices per link, counted together with `invoiceNumbers`.", "example": [ 125890 ] }, "invoiceNumbers": { "type": "array", "items": { "type": "string" }, "description": "Unpaid invoices of the client to lock the link to, by invoice number. Resolved to the same invoices as `invoiceIds`; an invoice given both ways is counted once.", "example": [ "INV-2026-4850" ] }, "amount": { "type": "string", "description": "Amount the payer is asked for, decimal with at most two decimal places. Accepted as a JSON number as well. Omit to let the invoices' outstanding balance drive the amount.", "example": "1000.00" }, "note": { "type": "string", "description": "Free text shown to the payer. Treated as sensitive; it is never written to logs.", "example": "2025 individual tax return" }, "returnUrl": { "type": "string", "format": "uri", "description": "Where the portal sends the payer after a successful payment. `https` only, host must be allow-listed for the firm. Makes the link a quick payment link even on its own.", "example": "https://app.safesend.example/returns/42" }, "returnLabel": { "type": "string", "maxLength": 40, "description": "Name of the destination shown on the return control, plain text. Requires `returnUrl`.", "example": "SafeSend" }, "returnAutomatically": { "type": "boolean", "default": false, "description": "Return on its own after the payment confirmation, after a short countdown, instead of waiting for the payer to press the return button. With `returnUrl` the portal navigates there; without one it closes the payment tab, which only works when your system opened the tab by script. Makes the link a quick payment link even on its own.", "example": true } } }, "examples": { "invoiceLocked": { "summary": "Quick payment link locked to one invoice, returning to the caller afterwards", "value": { "clientRef": "ACME-001", "invoiceIds": [ 125890 ], "note": "2025 individual tax return", "returnUrl": "https://app.safesend.example/returns/42", "returnLabel": "SafeSend", "returnAutomatically": true } }, "amountOnly": { "summary": "Quick payment link for an amount with no invoice", "value": { "clientRef": "ACME-001", "amount": "500.00", "note": "Retainer" } } } } } }, "responses": { "200": { "description": "Client was found and the payment link returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "description": "URL to hand to the payer. For a quick payment link the `qpLink` query parameter is the link id.", "example": "https://acme.aiwyn.app/client-portal/payments?qpLink=qpl_1756820591123_9f1c2a7b3d4e" } } } } } }, "400": { "description": "One of four rejections, told apart by `message` and `extensions.details.reason`:\n\n- The body could not be parsed or contains an unknown key. `extensions.details.reason` is\n `INVALID_REQUEST_BODY`.\n- The body carries no quick payment link argument. `extensions.details.reason` is\n `QUICK_PAYMENT_LINK_ARGUMENTS_REQUIRED`.\n- `clientRef` matches no client or more than one: `Multiple or no clients found for the\n reference provided.`\n- An embedded argument was rejected: `The invoice, amount or note provided cannot be used to\n build a payment link for this client.` Causes: an invoice does not exist, is not open, or\n belongs to another client; more than 100 invoices; an amount with more than two decimal\n places; a `returnUrl` that is not `https`, whose host is not allow-listed, or sent to a firm\n with no allow-list; a `returnLabel` without a `returnUrl`. The exact cause is written to\n Aiwyn's server log, not to the response, because it can echo caller data. Check the input\n against `GET /api/v1/invoices/unpaid` and the firm's allow-list.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "The invoice, amount or note provided cannot be used to build a payment link for this client." }, "extensions": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "details": { "type": "object", "nullable": true } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires PAYLNK_C or API_ADMIN)" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/projects": { "post": { "tags": [ "Projects" ], "summary": "List projects", "description": "**Retrieve all projects with basic pagination support**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nProjects are represented via `vw_job`. Default ordering by `updatedAt` desc.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/projects' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getProjectsPaginated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved projects" }, "400": { "description": "Bad request - invalid pagination parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/projects/search": { "post": { "tags": [ "Projects" ], "summary": "Search projects", "description": "**Advanced project filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nProjects are stored in the Jobs table (vw_job view). Supports manager, dates, and flags.\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/projects/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"name\": {\n \"_ilike\": \"%migration%\"\n }\n },\n {\n \"serviceDescription\": {\n \"_ilike\": \"%review%\"\n }\n }\n ]\n },\n {\n \"active\": {\n \"_eq\": true\n }\n },\n {\n \"updatedAt\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"partnerId\": {\n \"_in\": [\n 101,\n 102,\n 103\n ]\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"updatedAt\": \"desc\"\n },\n {\n \"name\": \"asc\"\n }\n ]\n}'\n```\n", "operationId": "filterProjectsDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex project filtering", "example": { "_and": [ { "_or": [ { "name": { "_ilike": "%migration%" } }, { "serviceDescription": { "_ilike": "%review%" } } ] }, { "active": { "_eq": true } }, { "updatedAt": { "_gte": "1900-01-01T00:00:00Z" } }, { "partnerId": { "_in": [ 101, 102, 103 ] } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications", "example": [ { "updatedAt": "desc" }, { "name": "asc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered projects" }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/project/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get project by ID", "description": "**Retrieve a specific project by its unique identifier**\n\nThis endpoint provides detailed project information including:\n- Complete project details and specifications\n- Project status and lifecycle information\n- Client and engagement relationships\n- Team assignments and resource allocation\n- Budget and financial tracking data\n- Timeline and milestone information\n\n**Project Management Features:**\n- Project lifecycle tracking\n- Resource allocation and team management\n- Budget and financial oversight\n- Timeline and milestone management\n- Client relationship integration\n\n**Project Details Include:**\n- Project name and description\n- Project status and phase\n- Client and engagement references\n- Team member assignments\n- Budget and financial data\n- Timeline and milestone tracking\n\n**Business Applications:**\n- Project status monitoring\n- Resource allocation analysis\n- Budget tracking and reporting\n- Client project portfolio management\n- Team performance analysis\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/project/67890' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 67890,\n \"name\": \"Q4 Financial Audit\",\n \"description\": \"Comprehensive financial audit for Q4 2024 including tax preparation and compliance review\",\n \"status\": \"IN_PROGRESS\",\n \"phase\": \"EXECUTION\",\n \"clientId\": 789,\n \"clientName\": \"Acme Corporation\",\n \"engagementId\": 456,\n \"engagementName\": \"Annual Audit Engagement\",\n \"startDate\": \"2024-10-01T00:00:00Z\",\n \"endDate\": \"2024-12-31T23:59:59Z\",\n \"budget\": 25000.00,\n \"currency\": \"USD\",\n \"actualCost\": 18500.00,\n \"teamMembers\": [\n {\n \"staffId\": 123,\n \"name\": \"John Smith\",\n \"role\": \"SENIOR_AUDITOR\",\n \"allocation\": 0.8\n },\n {\n \"staffId\": 124,\n \"name\": \"Jane Doe\",\n \"role\": \"AUDITOR\",\n \"allocation\": 0.6\n }\n ],\n \"milestones\": [\n {\n \"id\": 1,\n \"name\": \"Planning Phase Complete\",\n \"dueDate\": \"2024-10-15T00:00:00Z\",\n \"status\": \"COMPLETED\"\n },\n {\n \"id\": 2,\n \"name\": \"Fieldwork Complete\",\n \"dueDate\": \"2024-12-15T00:00:00Z\",\n \"status\": \"IN_PROGRESS\"\n }\n ],\n \"createdAt\": \"2024-09-15T10:00:00Z\",\n \"updatedAt\": \"2024-11-20T14:30:00Z\"\n}\n```\n", "operationId": "getProjectById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the project", "schema": { "type": "integer", "minimum": 1 }, "example": 67890 } ], "responses": { "200": { "description": "Project details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique project identifier", "example": 67890 }, "name": { "type": "string", "description": "Project name", "example": "Q4 Financial Audit" }, "description": { "type": "string", "description": "Detailed project description", "example": "Comprehensive financial audit for Q4 2024 including tax preparation and compliance review" }, "status": { "type": "string", "description": "Current project status", "enum": [ "PLANNING", "IN_PROGRESS", "ON_HOLD", "COMPLETED", "CANCELLED" ], "example": "IN_PROGRESS" }, "phase": { "type": "string", "description": "Current project phase", "enum": [ "PLANNING", "EXECUTION", "REVIEW", "DELIVERY", "CLOSED" ], "example": "EXECUTION" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "clientName": { "type": "string", "description": "Name of the client", "example": "Acme Corporation" }, "engagementId": { "type": "integer", "description": "Associated engagement identifier", "example": 456 }, "engagementName": { "type": "string", "description": "Name of the engagement", "example": "Annual Audit Engagement" }, "startDate": { "type": "string", "format": "date-time", "description": "Project start date", "example": "2024-10-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "Project end date", "example": "2024-12-31T23:59:59Z" }, "budget": { "type": "number", "format": "decimal", "description": "Project budget amount", "example": 25000 }, "currency": { "type": "string", "description": "Budget currency code", "example": "USD" }, "actualCost": { "type": "number", "format": "decimal", "description": "Actual cost incurred to date", "example": 18500 }, "teamMembers": { "type": "array", "description": "Team members assigned to the project", "items": { "type": "object", "properties": { "staffId": { "type": "integer", "description": "Staff member identifier", "example": 123 }, "name": { "type": "string", "description": "Staff member name", "example": "John Smith" }, "role": { "type": "string", "description": "Role on the project", "enum": [ "PROJECT_MANAGER", "SENIOR_AUDITOR", "AUDITOR", "ASSOCIATE", "INTERN" ], "example": "SENIOR_AUDITOR" }, "allocation": { "type": "number", "format": "decimal", "description": "Time allocation percentage (0.0 to 1.0)", "example": 0.8 } } } }, "milestones": { "type": "array", "description": "Project milestones", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Milestone identifier", "example": 1 }, "name": { "type": "string", "description": "Milestone name", "example": "Planning Phase Complete" }, "dueDate": { "type": "string", "format": "date-time", "description": "Milestone due date", "example": "2024-10-15T00:00:00Z" }, "status": { "type": "string", "description": "Milestone status", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "OVERDUE" ], "example": "COMPLETED" } } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Project creation timestamp", "example": "2024-09-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-11-20T14:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this project" }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Project not found" }, "message": { "type": "string", "example": "Project with ID 67890 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/projects/create_from_template": { "post": { "tags": [ "Projects" ], "summary": "Create one or more jobs from job templates", "description": "**Create jobs from job templates**\n\nCreates one or more jobs for a client from job templates. Up to 100 templates\nmay be provided in a single request. Each entry in `jobTemplates` can override\nfield-level defaults defined on the template.\n\n**Required fields:**\n- `clientId` โ€” the client for whom the jobs are being created\n- `jobTemplates` โ€” list of job templates to instantiate (1โ€“100 entries)\n - `jobTemplateId` โ€” the template to create a job from\n\n**Optional per-template overrides** (each overrides the template default if provided):\n- `startDate` โ€” job start date\n- `name` โ€” job name\n- `serviceDescription` โ€” service description\n- `estimationHours` โ€” estimated hours\n- `feeAmount` โ€” fee amount\n- `requiredPrepayment` โ€” required prepayment amount\n- `includeWipType` โ€” WIP billing behavior (`INCLUDE_WIP`, `INCLUDE_WIP_IF_FINAL`, `DO_NOT_INCLUDE`)\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/projects/create_from_template' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"clientId\": 420,\n \"jobTemplates\": [\n {\n \"jobTemplateId\": 7,\n \"startDate\": \"2025-01-01\",\n \"name\": \"Tax Return 2024\"\n }\n ]\n}'\n```\n", "operationId": "createProjectsFromTemplate", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientId", "jobTemplates" ], "properties": { "clientId": { "type": "integer", "format": "int64", "description": "Unique identifier of the client for whom jobs are being created", "example": 420 }, "jobTemplates": { "type": "array", "description": "List of job templates to instantiate (1โ€“100 entries)", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "jobTemplateId" ], "properties": { "jobTemplateId": { "type": "integer", "format": "int64", "description": "Unique identifier of the job template to use", "example": 7 }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Job start date (YYYY-MM-DD); overrides the template default", "example": "2025-01-01" }, "name": { "type": "string", "nullable": true, "description": "Job name; overrides the template default", "example": "Tax Return 2024" }, "serviceDescription": { "type": "string", "nullable": true, "description": "Service description; overrides the template default", "example": "Annual federal and state tax preparation" }, "estimationHours": { "type": "number", "nullable": true, "description": "Estimated hours for the job; overrides the template default", "example": 8.5 }, "feeAmount": { "type": "number", "nullable": true, "description": "Fee amount for the job; overrides the template default", "example": 1500 }, "requiredPrepayment": { "type": "number", "nullable": true, "description": "Required prepayment amount; overrides the template default", "example": 500 }, "includeWipType": { "type": "string", "nullable": true, "description": "WIP billing behavior; overrides the template default", "enum": [ "INCLUDE_WIP", "INCLUDE_WIP_IF_FINAL", "DO_NOT_INCLUDE" ], "example": "INCLUDE_WIP_IF_FINAL" } } } } } }, "examples": { "minimal": { "summary": "Single job from template, no overrides", "value": { "clientId": 420, "jobTemplates": [ { "jobTemplateId": 7 } ] } }, "full": { "summary": "Multiple jobs with field overrides", "value": { "clientId": 420, "jobTemplates": [ { "jobTemplateId": 7, "startDate": "2025-01-01", "name": "Tax Return 2024", "serviceDescription": "Annual federal and state tax preparation", "estimationHours": 8.5, "feeAmount": 1500, "requiredPrepayment": 500, "includeWipType": "INCLUDE_WIP_IF_FINAL" }, { "jobTemplateId": 12, "startDate": "2025-02-01", "name": "Bookkeeping Q1 2025" } ] } } } } } }, "responses": { "201": { "description": "Jobs created successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "List of IDs for the newly created jobs" }, "examples": { "success": { "summary": "Two jobs created", "value": [ 1001, 1002 ] } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_PROJ_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/projects/assign_staff": { "post": { "tags": [ "Projects" ], "summary": "Assign staff to a project", "description": "\n**Assign staff to a project**\n\n Creates associations between staff members and a job:\n - ``staffJobAssignments``: assigns staff directly to the job via ``staff_job`` records\n - ``staffTaskAssignments``: assigns staff to specific task types on the job via ``task_type_staff_job`` records\n\n If an association already exists but is inactive, it will be re-activated.\n\n Returns the IDs of created or re-activated records.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/projects/assign_staff' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"jobId\": 5001,\n \"staffJobAssignments\": [{\"staffId\": 103}, {\"staffId\": 104}],\n \"staffTaskAssignments\": [{\"staffId\": 103, \"taskTypeId\": 10}, {\"staffId\": 104, \"taskTypeId\": 11}]\n}'\n```\n", "operationId": "AssignStaffToProject", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId" ], "properties": { "jobId": { "type": "integer", "format": "int64", "description": "Jobid" }, "staffJobAssignments": { "type": "array", "items": { "type": "object", "properties": { "staffId": { "type": "integer", "format": "int64", "description": "Staffid" } } }, "description": "Staffjobassignments" }, "staffTaskAssignments": { "type": "array", "items": { "type": "object", "properties": { "staffId": { "type": "integer", "format": "int64", "description": "Staffid" }, "taskTypeId": { "type": "integer", "format": "int64", "description": "Tasktypeid" } } }, "description": "Stafftaskassignments" } } } } } }, "responses": { "200": { "description": "Staff assigned successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires PROJ_C)" }, "404": { "description": "Job, staff, or task type not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/projects/remove_staff": { "post": { "tags": [ "Projects" ], "summary": "Remove staff from a project", "description": "\n**Remove staff from a project**\n\n Deactivates associations between staff members and a job:\n - ``staffJobAssignments``: deactivates matching ``staff_job`` records\n - ``staffTaskAssignments``: deactivates matching ``task_type_staff_job`` records\n\n Returns the IDs of deactivated records. Items with no matching active record are silently skipped.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/projects/remove_staff' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"jobId\": 5001,\n \"staffJobAssignments\": [{\"staffId\": 103}, {\"staffId\": 104}],\n \"staffTaskAssignments\": [{\"staffId\": 103, \"taskTypeId\": 10}, {\"staffId\": 104, \"taskTypeId\": 11}]\n}'\n```\n", "operationId": "RemoveStaffFromProject", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId" ], "properties": { "jobId": { "type": "integer", "format": "int64", "description": "Jobid" }, "staffJobAssignments": { "type": "array", "items": { "type": "object", "properties": { "staffId": { "type": "integer", "format": "int64", "description": "Staffid" } } }, "description": "Staffjobassignments" }, "staffTaskAssignments": { "type": "array", "items": { "type": "object", "properties": { "staffId": { "type": "integer", "format": "int64", "description": "Staffid" }, "taskTypeId": { "type": "integer", "format": "int64", "description": "Tasktypeid" } } }, "description": "Stafftaskassignments" } } } } } }, "responses": { "200": { "description": "Staff removed successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires PROJ_C)" }, "404": { "description": "Job, staff, or task type not found" }, "500": { "description": "Internal server error" } } } }, "/v1/task-types": { "get": { "tags": [ "Time Management" ], "summary": "List all task types", "description": "**Retrieve all task types**\n\nReturns every task type available for the tenant, ordered alphabetically by\ndisplay name. Task types classify the work performed on time entries and\nprojects, and carry billing and tax settings used downstream in invoicing.\n\n**Each task type includes:**\n- Display name, code, and description\n- Billing and tax flags (`billable`, `taxable`)\n- Optional custom hourly rate and rate type\n- Service line and category associations\n- Usage counts across projects and invoices\n- Aiwyn-managed vs firm-defined indicators\n- Active status and audit timestamps\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/task-types' \\\n--header 'Authorization: Bearer {{token}}'\n```\n", "operationId": "getTaskTypes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Task types retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskTypes": { "type": "array", "description": "List of task types ordered by display name", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the task type", "example": 1 }, "pmsRef": { "type": "string", "description": "Practice management system reference identifier", "example": "TAX-PREP" }, "code": { "type": "string", "description": "Short code used to identify the task type", "example": "TXPRP" }, "display": { "type": "string", "description": "Human-readable display name", "example": "Tax Preparation" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the task type", "example": "Federal and state income tax preparation" }, "billable": { "type": "boolean", "description": "Whether time logged under this task type is billable", "example": true }, "taxable": { "type": "boolean", "description": "Whether this task type is subject to tax", "example": false }, "active": { "type": "boolean", "description": "Whether the task type is currently active", "example": true }, "customHourlyRate": { "type": "number", "format": "decimal", "nullable": true, "description": "Optional custom hourly rate that overrides the default rate", "example": 275 }, "rateTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the rate type associated with this task type", "example": 3 }, "taskTypeCategoryId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the task type category", "example": 2 }, "serviceLineId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the service line this task type belongs to", "example": 5 }, "projectsUsedInCount": { "type": "integer", "description": "Number of projects this task type is used in", "example": 42 }, "invoicesUsedInCount": { "type": "integer", "description": "Number of invoices this task type appears on", "example": 118 }, "isCreatedByAiwyn": { "type": "boolean", "description": "Whether this task type was created by Aiwyn", "example": false }, "isManagedByAiwyn": { "type": "boolean", "description": "Whether this task type is managed by Aiwyn", "example": false }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task type was created", "example": "2023-01-15T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task type was last updated", "example": "2024-06-01T12:30:00Z" }, "version": { "type": "integer", "format": "int64", "description": "Optimistic locking version number", "example": 3 } } } }, "total": { "type": "object", "description": "Aggregate count information", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of task types", "example": 25 } } } } } } }, "examples": { "success": { "summary": "Task types retrieved", "value": { "taskTypes": [ { "id": 1, "pmsRef": "TAX-PREP", "code": "TXPRP", "display": "Tax Preparation", "description": "Federal and state income tax preparation", "billable": true, "taxable": false, "active": true, "customHourlyRate": 275, "rateTypeId": 3, "taskTypeCategoryId": 2, "serviceLineId": 5, "projectsUsedInCount": 42, "invoicesUsedInCount": 118, "isCreatedByAiwyn": false, "isManagedByAiwyn": false, "createdAt": "2023-01-15T08:00:00Z", "updatedAt": "2024-06-01T12:30:00Z", "version": 3 }, { "id": 2, "pmsRef": "AUDIT", "code": "AUDIT", "display": "Audit", "description": null, "billable": true, "taxable": false, "active": true, "customHourlyRate": null, "rateTypeId": null, "taskTypeCategoryId": 1, "serviceLineId": 2, "projectsUsedInCount": 17, "invoicesUsedInCount": 53, "isCreatedByAiwyn": false, "isManagedByAiwyn": false, "createdAt": "2023-01-15T08:00:00Z", "updatedAt": "2023-01-15T08:00:00Z", "version": 1 } ], "total": { "aggregate": { "count": 25 } } } }, "empty": { "summary": "No task types found", "value": { "taskTypes": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires API_ADMIN role)" }, "500": { "description": "Internal server error" } } } }, "/v1/task-types/search": { "post": { "tags": [ "Time Management" ], "summary": "Search task types", "description": "**Advanced task type filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nSupports flexible filtering across any task type field using GraphQL-style `where`\nclauses, with pagination and dynamic ordering.\n\n**Common filter examples (pass in the `where` field):**\n- By code: `{ \"code\": { \"_eq\": \"PREP\" } }`\n- By active status: `{ \"active\": { \"_eq\": true } }`\n- By billable flag: `{ \"billable\": { \"_eq\": true } }`\n- By category: `{ \"taskTypeCategoryId\": { \"_eq\": 5 } }`\n- By service line: `{ \"serviceLineId\": { \"_eq\": 2 } }`\n- Combined: `{ \"_and\": [ { \"billable\": { \"_eq\": true } }, { \"active\": { \"_eq\": true } } ] }`\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/task-types/search' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0,\n \"where\": {\n \"_and\": [\n { \"billable\": { \"_eq\": true } },\n { \"active\": { \"_eq\": true } }\n ]\n },\n \"orderBy\": [\n { \"display\": \"asc\" }\n ]\n}'\n```\n", "operationId": "searchTaskTypesDynamic", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "where": { "type": "object", "description": "GraphQL-style where clause for filtering. Supports operators such as `_eq`, `_neq`, `_in`, `_nin`, `_ilike`, `_gte`, `_lte`, and logical combinators `_and`, `_or`, `_not`.\n", "example": { "_and": [ { "billable": { "_eq": true } }, { "active": { "_eq": true } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications. Each element is an object mapping a field name to `\"asc\"` or `\"desc\"`. Defaults to `[{ \"display\": \"asc\" }]`.\n", "example": [ { "display": "asc" } ] } } }, "examples": { "billable_active": { "summary": "All active billable task types", "value": { "pageSize": 25, "page": 0, "where": { "_and": [ { "billable": { "_eq": true } }, { "active": { "_eq": true } } ] }, "orderBy": [ { "display": "asc" } ] } }, "by_service_line": { "summary": "Task types for a specific service line", "value": { "pageSize": 50, "page": 0, "where": { "serviceLineId": { "_eq": 2 } } } }, "by_code": { "summary": "Exact code lookup", "value": { "pageSize": 1, "page": 0, "where": { "code": { "_eq": "TXPRP" } } } } } } } }, "responses": { "200": { "description": "Task types retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskTypes": { "type": "array", "description": "List of task types matching the filter criteria", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier of the task type", "example": 1 }, "pmsRef": { "type": "string", "description": "Practice management system reference identifier", "example": "TAX-PREP" }, "code": { "type": "string", "description": "Short code used to identify the task type", "example": "TXPRP" }, "display": { "type": "string", "description": "Human-readable display name", "example": "Tax Preparation" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the task type", "example": "Federal and state income tax preparation" }, "billable": { "type": "boolean", "description": "Whether time logged under this task type is billable", "example": true }, "taxable": { "type": "boolean", "description": "Whether this task type is subject to tax", "example": false }, "active": { "type": "boolean", "description": "Whether the task type is currently active", "example": true }, "customHourlyRate": { "type": "number", "format": "decimal", "nullable": true, "description": "Optional custom hourly rate that overrides the default rate", "example": 275 }, "rateTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the rate type associated with this task type", "example": 3 }, "taskTypeCategoryId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the task type category", "example": 2 }, "serviceLineId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the service line this task type belongs to", "example": 5 }, "projectsUsedInCount": { "type": "integer", "description": "Number of projects this task type is used in", "example": 42 }, "invoicesUsedInCount": { "type": "integer", "description": "Number of invoices this task type appears on", "example": 118 }, "isCreatedByAiwyn": { "type": "boolean", "description": "Whether this task type was created by Aiwyn", "example": false }, "isManagedByAiwyn": { "type": "boolean", "description": "Whether this task type is managed by Aiwyn", "example": false }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task type was created", "example": "2023-01-15T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task type was last updated", "example": "2024-06-01T12:30:00Z" }, "version": { "type": "integer", "format": "int64", "description": "Optimistic locking version number", "example": 3 } } } }, "total": { "type": "object", "description": "Aggregate count matching the filter (ignores pagination)", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of task types matching the where clause", "example": 12 } } } } } } }, "examples": { "success": { "summary": "Active billable task types returned", "value": { "taskTypes": [ { "id": 1, "pmsRef": "TAX-PREP", "code": "TXPRP", "display": "Tax Preparation", "description": "Federal and state income tax preparation", "billable": true, "taxable": false, "active": true, "customHourlyRate": 275, "rateTypeId": 3, "taskTypeCategoryId": 2, "serviceLineId": 5, "projectsUsedInCount": 42, "invoicesUsedInCount": 118, "isCreatedByAiwyn": false, "isManagedByAiwyn": false, "createdAt": "2023-01-15T08:00:00Z", "updatedAt": "2024-06-01T12:30:00Z", "version": 3 } ], "total": { "aggregate": { "count": 12 } } } }, "empty": { "summary": "No task types matched the filter", "value": { "taskTypes": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid filter parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires API_ADMIN role)" }, "500": { "description": "Internal server error" } } } }, "/v1/task/{id}": { "get": { "tags": [ "Time Management" ], "summary": "Get task by ID", "description": "**Retrieve a specific task by its unique identifier**\n\nReturns full task details including the associated task type, assignee staff\nmember, and parent job reference.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/task/456' \\\n--header 'Authorization: Bearer {{token}}'\n```\n", "operationId": "findTaskById", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the task", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "example": 456 } ], "responses": { "200": { "description": "Task retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "description": "Single-element array containing the matching task (empty if not found)", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier of the task", "example": 456 }, "name": { "type": "string", "description": "Task name", "example": "Q4 Financial Statement Review" }, "overrideName": { "type": "string", "nullable": true, "description": "Optional name that overrides the default task name", "example": null }, "status": { "type": "string", "description": "Current status of the task", "example": "IN_PROGRESS" }, "pmsRef": { "type": "string", "nullable": true, "description": "Practice management system reference identifier", "example": "TASK-001" }, "jobId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the job this task belongs to", "example": 67890 }, "taskTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the task type", "example": 1 }, "assigneeStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the staff member assigned to this task", "example": 123 }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Actual start date of the task", "example": "2024-10-01" }, "dueDate": { "type": "string", "format": "date", "nullable": true, "description": "Actual due date of the task", "example": "2024-12-31" }, "targetStartDate": { "type": "string", "format": "date", "nullable": true, "description": "Planned target start date", "example": "2024-09-15" }, "targetDueDate": { "type": "string", "format": "date", "nullable": true, "description": "Planned target due date", "example": "2024-12-15" }, "estimatedHours": { "type": "number", "format": "decimal", "nullable": true, "description": "Estimated hours to complete the task", "example": 40 }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task was completed", "example": null }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the task", "example": "Review and analyse Q4 financial statements including variance analysis" }, "ordinal": { "type": "integer", "nullable": true, "description": "Display order position of the task", "example": 1 }, "parentTaskId": { "type": "integer", "format": "int32", "nullable": true, "description": "ID of the parent task if this is a subtask", "example": null }, "jobTemplateTaskId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the job template task this was created from", "example": 10 }, "isCreatedByAiwyn": { "type": "boolean", "description": "Whether this task was created by Aiwyn", "example": false }, "isManagedByAiwyn": { "type": "boolean", "description": "Whether this task is managed by Aiwyn", "example": false }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task was created", "example": "2024-09-01T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task was last updated", "example": "2024-10-01T09:30:00Z" }, "taskType": { "type": "object", "nullable": true, "description": "The task type associated with this task", "properties": { "id": { "type": "integer", "format": "int64", "example": 1 }, "code": { "type": "string", "example": "TXPRP" }, "display": { "type": "string", "example": "Tax Preparation" }, "billable": { "type": "boolean", "example": true }, "taxable": { "type": "boolean", "example": false }, "active": { "type": "boolean", "example": true } } }, "assigneeStaff": { "type": "object", "nullable": true, "description": "The staff member assigned to this task", "properties": { "id": { "type": "integer", "format": "int64", "example": 123 }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Smith" }, "email": { "type": "string", "format": "email", "example": "john.smith@firm.com" } } }, "job": { "type": "object", "nullable": true, "description": "The job this task belongs to", "properties": { "id": { "type": "integer", "format": "int64", "example": 67890 } } } } } } } }, "examples": { "success": { "summary": "Task found", "value": { "tasks": [ { "id": 456, "name": "Q4 Financial Statement Review", "overrideName": null, "status": "IN_PROGRESS", "pmsRef": "TASK-001", "jobId": 67890, "taskTypeId": 1, "assigneeStaffId": 123, "startDate": "2024-10-01", "dueDate": "2024-12-31", "targetStartDate": "2024-09-15", "targetDueDate": "2024-12-15", "estimatedHours": 40, "completedAt": null, "description": "Review and analyse Q4 financial statements including variance analysis", "ordinal": 1, "parentTaskId": null, "jobTemplateTaskId": 10, "isCreatedByAiwyn": false, "isManagedByAiwyn": false, "createdAt": "2024-09-01T08:00:00Z", "updatedAt": "2024-10-01T09:30:00Z", "taskType": { "id": 1, "code": "TXPRP", "display": "Tax Preparation", "billable": true, "taxable": false, "active": true }, "assigneeStaff": { "id": 123, "firstName": "John", "lastName": "Smith", "email": "john.smith@firm.com" }, "job": { "id": 67890 } } ] } }, "not_found": { "summary": "Task not found", "value": { "tasks": [] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires API_ADMIN role)" }, "500": { "description": "Internal server error" } } } }, "/v1/tasks/search": { "post": { "tags": [ "Time Management" ], "summary": "Search tasks", "description": "**Advanced task filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nSupports flexible filtering across any task field โ€” including nested relations\nsuch as `taskType` and `job` โ€” using GraphQL-style `where` clauses, with\npagination and dynamic ordering.\n\n**Common filter examples (pass in the `where` field):**\n- By task type ID: `{ \"taskTypeId\": { \"_eq\": 123 } }`\n- By task type code: `{ \"taskType\": { \"code\": { \"_eq\": \"PREP\" } } }`\n- By client: `{ \"job\": { \"clientId\": { \"_eq\": 456 } } }`\n- Start date range: `{ \"startDate\": { \"_gte\": \"2024-01-01\", \"_lte\": \"2024-12-31\" } }`\n- Due date range: `{ \"dueDate\": { \"_gte\": \"2024-01-01\", \"_lte\": \"2024-12-31\" } }`\n- By assignee: `{ \"assigneeStaffId\": { \"_eq\": 789 } }`\n- Combined: `{ \"_and\": [ { \"taskType\": { \"code\": { \"_eq\": \"PREP\" } } }, { \"assigneeStaffId\": { \"_eq\": 789 } } ] }`\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/tasks/search' \\\n--header 'Authorization: Bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0,\n \"where\": {\n \"_and\": [\n { \"taskType\": { \"code\": { \"_eq\": \"PREP\" } } },\n { \"assigneeStaffId\": { \"_eq\": 789 } }\n ]\n },\n \"orderBy\": [\n { \"dueDate\": \"asc\" }\n ]\n}'\n```\n", "operationId": "searchTasksDynamic", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "where": { "type": "object", "description": "GraphQL-style where clause for filtering. Supports operators such as `_eq`, `_neq`, `_in`, `_nin`, `_ilike`, `_gte`, `_lte`, and logical combinators `_and`, `_or`, `_not`. Nested relations `taskType` and `job` can be filtered inline.\n", "example": { "_and": [ { "taskType": { "code": { "_eq": "PREP" } } }, { "assigneeStaffId": { "_eq": 789 } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications. Each element maps a field name to `\"asc\"` or `\"desc\"`. Defaults to `[{ \"id\": \"asc\" }]`.\n", "example": [ { "dueDate": "asc" } ] } } }, "examples": { "by_task_type_and_assignee": { "summary": "Tasks of a specific type assigned to a staff member", "value": { "pageSize": 25, "page": 0, "where": { "_and": [ { "taskType": { "code": { "_eq": "PREP" } } }, { "assigneeStaffId": { "_eq": 789 } } ] }, "orderBy": [ { "dueDate": "asc" } ] } }, "by_client": { "summary": "All tasks for a specific client", "value": { "pageSize": 50, "page": 0, "where": { "job": { "clientId": { "_eq": 456 } } } } }, "due_date_range": { "summary": "Tasks due within a date range", "value": { "pageSize": 50, "page": 0, "where": { "dueDate": { "_gte": "2024-01-01", "_lte": "2024-12-31" } }, "orderBy": [ { "dueDate": "asc" } ] } } } } } }, "responses": { "200": { "description": "Tasks retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "description": "List of tasks matching the filter criteria", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier of the task", "example": 456 }, "name": { "type": "string", "description": "Task name", "example": "Q4 Financial Statement Review" }, "overrideName": { "type": "string", "nullable": true, "description": "Optional name that overrides the default task name", "example": null }, "status": { "type": "string", "description": "Current status of the task", "example": "IN_PROGRESS" }, "pmsRef": { "type": "string", "nullable": true, "description": "Practice management system reference identifier", "example": "TASK-001" }, "jobId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the job this task belongs to", "example": 67890 }, "taskTypeId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the task type", "example": 1 }, "assigneeStaffId": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the staff member assigned to this task", "example": 789 }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Actual start date of the task", "example": "2024-10-01" }, "dueDate": { "type": "string", "format": "date", "nullable": true, "description": "Actual due date of the task", "example": "2024-12-31" }, "targetStartDate": { "type": "string", "format": "date", "nullable": true, "description": "Planned target start date", "example": "2024-09-15" }, "targetDueDate": { "type": "string", "format": "date", "nullable": true, "description": "Planned target due date", "example": "2024-12-15" }, "estimatedHours": { "type": "number", "format": "decimal", "nullable": true, "description": "Estimated hours to complete the task", "example": 40 }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task was completed", "example": null }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the task", "example": "Review and analyse Q4 financial statements" }, "ordinal": { "type": "integer", "nullable": true, "description": "Display order position of the task", "example": 1 }, "parentTaskId": { "type": "integer", "format": "int32", "nullable": true, "description": "ID of the parent task if this is a subtask", "example": null }, "isCreatedByAiwyn": { "type": "boolean", "description": "Whether this task was created by Aiwyn", "example": false }, "isManagedByAiwyn": { "type": "boolean", "description": "Whether this task is managed by Aiwyn", "example": false }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task was created", "example": "2024-09-01T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the task was last updated", "example": "2024-10-01T09:30:00Z" }, "taskType": { "type": "object", "nullable": true, "description": "The task type associated with this task", "properties": { "id": { "type": "integer", "format": "int64", "example": 1 }, "code": { "type": "string", "example": "PREP" }, "display": { "type": "string", "example": "Tax Preparation" }, "billable": { "type": "boolean", "example": true }, "taxable": { "type": "boolean", "example": false }, "active": { "type": "boolean", "example": true } } }, "assigneeStaff": { "type": "object", "nullable": true, "description": "The staff member assigned to this task", "properties": { "id": { "type": "integer", "format": "int64", "example": 789 }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "jane.doe@firm.com" } } }, "job": { "type": "object", "nullable": true, "description": "The job this task belongs to", "properties": { "id": { "type": "integer", "format": "int64", "example": 67890 } } } } } }, "total": { "type": "object", "description": "Aggregate count matching the filter (ignores pagination)", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of tasks matching the where clause", "example": 84 } } } } } } }, "examples": { "success": { "summary": "Tasks returned", "value": { "tasks": [ { "id": 456, "name": "Q4 Financial Statement Review", "overrideName": null, "status": "IN_PROGRESS", "pmsRef": "TASK-001", "jobId": 67890, "taskTypeId": 1, "assigneeStaffId": 789, "startDate": "2024-10-01", "dueDate": "2024-12-31", "targetStartDate": "2024-09-15", "targetDueDate": "2024-12-15", "estimatedHours": 40, "completedAt": null, "description": "Review and analyse Q4 financial statements", "ordinal": 1, "parentTaskId": null, "isCreatedByAiwyn": false, "isManagedByAiwyn": false, "createdAt": "2024-09-01T08:00:00Z", "updatedAt": "2024-10-01T09:30:00Z", "taskType": { "id": 1, "code": "PREP", "display": "Tax Preparation", "billable": true, "taxable": false, "active": true }, "assigneeStaff": { "id": 789, "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@firm.com" }, "job": { "id": 67890 } } ], "total": { "aggregate": { "count": 84 } } } }, "empty": { "summary": "No tasks matched the filter", "value": { "tasks": [], "total": { "aggregate": { "count": 0 } } } } } } } }, "400": { "description": "Bad request - invalid filter parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires API_ADMIN role)" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/wip": { "post": { "tags": [ "Time Management" ], "summary": "List WIP entries", "description": "**Work in Progress tracking with comprehensive financial lifecycle management**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nThis advanced endpoint provides complete WIP management including:\n- WIP value tracking from creation through billing completion\n- Outstanding balance calculations for unbilled work\n- Multi-dimensional analysis (client, job, date-based)\n- Financial aggregations for WIP reporting and analysis\n- Integration with client and job data for complete context\n\n**Financial Tracking Features:**\n- WIP value recording and outstanding balance calculation\n- Billed amount tracking for revenue recognition\n- Write-off amount management for uncollectible WIP\n- Job and client correlation for project profitability\n\n**WIP Lifecycle Management:**\n- Creation date logging for aging analysis\n- WIP type categorization (TIME, EXPENSE, FIXED_FEE, etc.)\n- Outstanding value calculation for billing preparation\n- Billed amount reconciliation for revenue tracking\n\n**Business Intelligence & Reporting:**\n- Client-specific WIP analysis and aging\n- Job-based profitability and WIP tracking\n- WIP aging reports for collections management\n- Revenue recognition and billing pipeline analysis\n\n**Financial Aggregations:**\n- Total WIP value across filtered records\n- Outstanding WIP calculations for billing preparation\n- Billed amount summaries for revenue analysis\n- Write-off tracking for financial reporting\n\n**Advanced Filtering:**\n- Client-specific WIP retrieval and analysis\n- Job-based WIP tracking for project management\n- Date range queries for period-specific reporting\n- WIP type filtering for category analysis\n\n**Active Record Filtering:**\n- Only active WIP records are returned by default (inactive records represent deletions)\n- Each record includes `isActive` so clients can distinguish active from inactive when querying by ID\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/wip' \\\n--header 'Authorization: bearer {{token}} \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 25,\n \"page\": 0\n}'\n```\n", "operationId": "getWip", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n", "example": 0 }, "clientId": { "type": "integer", "description": "Filter WIP records by specific client ID", "example": 1561 }, "jobId": { "type": "integer", "description": "Filter WIP records by specific job ID", "example": 2514 }, "wipType": { "type": "string", "description": "Filter by WIP type", "enum": [ "Time", "Expense", "Fixed_Fee", "Disbursement" ], "example": "Time" }, "startDate": { "type": "string", "format": "date-time", "description": "Start date for WIP logged date range filter", "example": "2024-01-01T00:00:00" }, "endDate": { "type": "string", "format": "date-time", "description": "End date for WIP logged date range filter", "example": "2024-12-31T23:59:59" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort order for logged date", "example": "desc" } } }, "examples": { "default_pagination": { "summary": "Default pagination", "value": { "pageSize": 25, "page": 0 } } } } } }, "responses": { "200": { "description": "Successfully retrieved WIP records with financial aggregations", "content": { "application/json": { "schema": { "type": "object", "properties": { "deid_wip": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique WIP record identifier", "example": 850321 }, "pmsRef": { "type": "string", "description": "Practice management system reference", "example": "1789456" }, "wipType": { "type": "string", "description": "Type of WIP entry", "example": "Time" }, "loggedDate": { "type": "string", "format": "date-time", "description": "Date when WIP was logged", "example": "2024-01-17T05:00:00" }, "wipValue": { "type": "number", "format": "decimal", "description": "Original WIP value recorded", "example": 1250 }, "wipValueOutstanding": { "type": "number", "format": "decimal", "description": "Outstanding WIP value yet to be billed", "example": 0 }, "billedAmount": { "type": "number", "format": "decimal", "description": "Amount that has been billed from this WIP", "example": 1225 }, "writeOffAmount": { "type": "number", "format": "decimal", "description": "Amount written off as uncollectible", "example": 25 }, "notes": { "type": "string", "nullable": true, "description": "Additional notes or description for the WIP entry", "example": "Consultation and analysis for Q1 financial review" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 1561 }, "jobId": { "type": "integer", "description": "Associated job identifier", "example": 2514 }, "isActive": { "type": "boolean", "description": "Whether the WIP record is active (inactive records represent deletions)", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "WIP record creation timestamp", "example": "2024-05-12T23:02:33.24516+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "WIP record last update timestamp", "example": "2024-05-12T23:02:33.24516+00:00" }, "client": { "type": "object", "description": "Associated client information", "properties": { "id": { "type": "integer", "example": 1561 }, "name": { "type": "string", "example": "TechFlow Enterprises" } } }, "job": { "type": "object", "description": "Associated job information", "properties": { "id": { "type": "integer", "example": 2514 }, "name": { "type": "string", "example": "Q1 Financial Review 2024" } } } } } }, "deid_wip_aggregate": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of WIP records matching criteria", "example": 84 }, "sum": { "type": "object", "properties": { "wipValue": { "type": "number", "format": "decimal", "description": "Total WIP value across all matching records", "example": 24186.15 }, "billedAmount": { "type": "number", "format": "decimal", "description": "Total billed amount across all matching records", "example": 19612.07 }, "wipValueOutstanding": { "type": "number", "format": "decimal", "description": "Total outstanding WIP value", "example": 0 } } } } } } } } }, "examples": { "successful_response": { "summary": "WIP records with financial tracking and aggregations", "value": { "deid_wip": [ { "id": 850321, "pmsRef": "1789456", "wipType": "Time", "loggedDate": "2024-01-17T05:00:00", "wipValue": 1250, "wipValueOutstanding": 0, "billedAmount": 1225, "writeOffAmount": 25, "notes": "Consultation and analysis for Q1 financial review", "clientId": 1561, "jobId": 2514, "isActive": true, "createdAt": "2024-05-12T23:02:33.24516+00:00", "updatedAt": "2024-05-12T23:02:33.24516+00:00", "client": { "id": 1561, "name": "TechFlow Enterprises" }, "job": { "id": 2514, "name": "Q1 Financial Review 2024" } }, { "id": 850142, "pmsRef": "1789123", "wipType": "Expense", "loggedDate": "2024-01-15T05:00:00", "wipValue": 350, "wipValueOutstanding": 0, "billedAmount": 343.5, "writeOffAmount": 6.5, "notes": null, "clientId": 1561, "jobId": 2514, "createdAt": "2024-05-12T23:00:05.824148+00:00", "updatedAt": "2024-05-12T23:00:05.824148+00:00", "client": { "id": 1561, "name": "TechFlow Enterprises" }, "job": { "id": 2514, "name": "Q1 Financial Review 2024" } }, { "id": 849987, "pmsRef": "1788890", "wipType": "Time", "loggedDate": "2024-01-12T05:00:00", "wipValue": 875, "wipValueOutstanding": 125, "billedAmount": 750, "writeOffAmount": 0, "notes": "Document review and preparation", "clientId": 1561, "jobId": 2514, "createdAt": "2024-05-12T23:00:07.784813+00:00", "updatedAt": "2024-05-12T23:00:07.784813+00:00", "client": { "id": 1561, "name": "TechFlow Enterprises" }, "job": { "id": 2514, "name": "Q1 Financial Review 2024" } } ], "deid_wip_aggregate": { "aggregate": { "count": 84, "sum": { "wipValue": 24186.15, "billedAmount": 19612.07, "wipValueOutstanding": 125 } } } } }, "real_api_response": { "summary": "Sample from actual API response", "value": { "deid_wip": [ { "id": 743292, "pmsRef": "1694524", "wipType": "Time", "loggedDate": "2018-01-17T05:00:00", "wipValue": 127.5, "wipValueOutstanding": 0, "billedAmount": 0, "writeOffAmount": 127.5, "notes": "Velit aut provident sint dolorum eaque necessitatibus dicta reprehenderit eveniet dolore eius neque est.", "clientId": 1561, "jobId": 2514, "createdAt": "2023-05-12T23:02:33.24516+00:00", "updatedAt": "2023-05-12T23:02:33.24516+00:00", "client": { "id": 1561, "name": "Cammie Cremin" }, "job": { "id": 2514, "name": "Justin Case" } }, { "id": 510044, "pmsRef": "1159387", "wipType": "Time", "loggedDate": "2016-03-23T04:00:00", "wipValue": 87.5, "wipValueOutstanding": 0, "billedAmount": 86.05, "writeOffAmount": 1.45, "notes": null, "clientId": 1561, "jobId": 2514, "createdAt": "2023-05-12T23:00:05.824148+00:00", "updatedAt": "2023-05-12T23:00:05.824148+00:00", "client": { "id": 1561, "name": "Cammie Cremin" }, "job": { "id": 2514, "name": "Justin Case" } } ], "deid_wip_aggregate": { "aggregate": { "count": 84, "sum": { "wipValue": 24186.15, "billedAmount": 19612.07, "wipValueOutstanding": 0 } } } } }, "empty_response": { "summary": "No WIP records found", "value": { "deid_wip": [], "deid_wip_aggregate": { "aggregate": { "count": 0, "sum": { "wipValue": 0, "billedAmount": 0, "wipValueOutstanding": 0 } } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "invalid_date_range": { "summary": "Invalid date range", "value": { "error": "startDate must be before or equal to endDate", "code": "INVALID_DATE_RANGE" } }, "invalid_client_id": { "summary": "Invalid client ID", "value": { "error": "clientId must be a positive integer", "code": "INVALID_CLIENT_ID" } } } } } }, "401": { "description": "Unauthorized - missing or invalid admin secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "examples": { "missing_auth": { "summary": "Missing authentication header", "value": { "error": "x-hasura-admin-secret header is required", "code": "MISSING_AUTH_HEADER" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/gql/v1/wips/search": { "post": { "tags": [ "Time Management" ], "summary": "Search WIP entries", "description": "**Advanced WIP filtering with custom GraphQL where clauses and dynamic ordering**\n\n**Pagination (v1 โ€” limit/offset):** `pageSize` is a limit (records to return).\n`page` is an offset (records to skip), not a page index. Hasura maps these as\n`limit: $pageSize` and `offset: $page`. When `page` is at or beyond\n`total.aggregate.count`, the result array is empty.\n\nSupports wipType selection, date ranges, and client/job constraints.\nBy default, only active WIP records are returned. Pass `isActive` in the `where`\nclause to include inactive records (e.g. for reconciliation syncs).\n\nReal Example:\n```bash\ncurl --location 'https://{{host}}/v1/wips/search' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"where\": {\n \"_and\": [\n {\n \"_or\": [\n {\n \"type\": {\n \"_in\": [\"TIME\", \"EXPENSE\"]\n }\n },\n {\n \"notes\": {\n \"_ilike\": \"%consultation%\"\n }\n }\n ]\n },\n {\n \"approved\": {\n \"_eq\": true\n }\n },\n {\n \"loggedDate\": {\n \"_gte\": \"1900-01-01T00:00:00Z\"\n }\n },\n {\n \"clientId\": {\n \"_in\": [\n 1001,\n 1002,\n 1003\n ]\n }\n }\n ]\n },\n \"orderBy\": [\n {\n \"loggedDate\": \"desc\"\n },\n {\n \"value\": \"desc\"\n }\n ]\n}'\n```\n", "operationId": "filterWipsDynamic", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`." }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index.\nHasura maps this to `offset`. To fetch the next N rows after the\nfirst N, send `pageSize: N` and `page: N`. An offset at or beyond\n`total.aggregate.count` returns an empty result array.\n" }, "where": { "type": "object", "description": "GraphQL-style where clause for complex WIP filtering", "example": { "_and": [ { "_or": [ { "type": { "_in": [ "TIME", "EXPENSE" ] } }, { "notes": { "_ilike": "%consultation%" } } ] }, { "approved": { "_eq": true } }, { "loggedDate": { "_gte": "1900-01-01T00:00:00Z" } }, { "clientId": { "_in": [ 1001, 1002, 1003 ] } } ] } }, "orderBy": { "type": "array", "items": { "type": "object" }, "description": "Dynamic ordering specifications", "example": [ { "loggedDate": "desc" }, { "value": "desc" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved filtered WIP entries" }, "400": { "description": "Bad request - invalid where/orderBy" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/gql/v1/wip/{id}": { "get": { "tags": [ "Time Management" ], "summary": "Get WIP time entry by ID", "description": "**Retrieve a specific work-in-progress (WIP) time entry by its unique identifier**\n\nThis endpoint provides detailed WIP time entry information including:\n- Complete time entry details and descriptions\n- Time entry status and approval information\n- Client, project, and task relationships\n- Billable and non-billable time tracking\n- Rate calculations and billing preparation\n- Time entry history and modifications\n\n**WIP Time Management Features:**\n- Time entry lifecycle tracking\n- Billable vs non-billable time classification\n- Rate calculation and billing preparation\n- Project and task relationship management\n- Approval workflow integration\n\n**WIP Time Details Include:**\n- Time entry description and details\n- Time entry status and type\n- Client, project, and task information\n- Time duration and rates\n- Billable calculations\n- Approval status\n\n**Business Applications:**\n- Time entry review and approval\n- Billable time calculation\n- Project time tracking\n- Client billing preparation\n- Productivity analysis\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/v1/wip/89012' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n**Response Example:**\n```json\n{\n \"id\": 89012,\n \"description\": \"Financial statement review and analysis\",\n \"status\": \"PENDING_APPROVAL\",\n \"type\": \"BILLABLE\",\n \"staffId\": 123,\n \"staffName\": \"John Smith\",\n \"clientId\": 789,\n \"clientName\": \"Acme Corporation\",\n \"projectId\": 67890,\n \"projectName\": \"Q4 Financial Audit\",\n \"taskId\": 456,\n \"taskName\": \"Financial Statement Review\",\n \"date\": \"2024-11-20T00:00:00Z\",\n \"startTime\": \"2024-11-20T09:00:00Z\",\n \"endTime\": \"2024-11-20T17:00:00Z\",\n \"duration\": 8.0,\n \"billableHours\": 8.0,\n \"nonBillableHours\": 0.0,\n \"hourlyRate\": 250.00,\n \"billableAmount\": 2000.00,\n \"currency\": \"USD\",\n \"notes\": \"Completed comprehensive review of Q4 financial statements including variance analysis\",\n \"approvalHistory\": [\n {\n \"id\": 1,\n \"approverId\": 124,\n \"approverName\": \"Jane Doe\",\n \"approvalDate\": \"2024-11-21T10:30:00Z\",\n \"status\": \"PENDING\",\n \"comments\": \"Under review\"\n }\n ],\n \"createdAt\": \"2024-11-20T17:30:00Z\",\n \"updatedAt\": \"2024-11-21T10:30:00Z\"\n}\n```\n", "operationId": "getWipById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the WIP time entry", "schema": { "type": "integer", "minimum": 1 }, "example": 89012 } ], "responses": { "200": { "description": "WIP time entry details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique WIP time entry identifier", "example": 89012 }, "description": { "type": "string", "description": "Time entry description", "example": "Financial statement review and analysis" }, "status": { "type": "string", "description": "Time entry status", "enum": [ "DRAFT", "SUBMITTED", "PENDING_APPROVAL", "APPROVED", "REJECTED", "BILLED" ], "example": "PENDING_APPROVAL" }, "type": { "type": "string", "description": "Time entry type", "enum": [ "BILLABLE", "NON_BILLABLE", "PTO", "TRAINING", "ADMINISTRATIVE" ], "example": "BILLABLE" }, "staffId": { "type": "integer", "description": "Staff member identifier", "example": 123 }, "staffName": { "type": "string", "description": "Staff member name", "example": "John Smith" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "clientName": { "type": "string", "description": "Client name", "example": "Acme Corporation" }, "projectId": { "type": "integer", "description": "Associated project identifier", "example": 67890 }, "projectName": { "type": "string", "description": "Project name", "example": "Q4 Financial Audit" }, "taskId": { "type": "integer", "description": "Associated task identifier", "example": 456 }, "taskName": { "type": "string", "description": "Task name", "example": "Financial Statement Review" }, "date": { "type": "string", "format": "date", "description": "Date of time entry", "example": "2024-11-20T00:00:00Z" }, "startTime": { "type": "string", "format": "date-time", "description": "Start time of work", "example": "2024-11-20T09:00:00Z" }, "endTime": { "type": "string", "format": "date-time", "description": "End time of work", "example": "2024-11-20T17:00:00Z" }, "duration": { "type": "number", "format": "decimal", "description": "Total duration in hours", "example": 8 }, "billableHours": { "type": "number", "format": "decimal", "description": "Billable hours", "example": 8 }, "nonBillableHours": { "type": "number", "format": "decimal", "description": "Non-billable hours", "example": 0 }, "hourlyRate": { "type": "number", "format": "decimal", "description": "Hourly rate for this time entry", "example": 250 }, "billableAmount": { "type": "number", "format": "decimal", "description": "Total billable amount", "example": 2000 }, "currency": { "type": "string", "description": "Currency code", "example": "USD" }, "notes": { "type": "string", "description": "Additional notes about the time entry", "example": "Completed comprehensive review of Q4 financial statements including variance analysis" }, "approvalHistory": { "type": "array", "description": "Approval history for this time entry", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Approval record identifier", "example": 1 }, "approverId": { "type": "integer", "description": "Approver identifier", "example": 124 }, "approverName": { "type": "string", "description": "Approver name", "example": "Jane Doe" }, "approvalDate": { "type": "string", "format": "date-time", "description": "Approval date", "example": "2024-11-21T10:30:00Z" }, "status": { "type": "string", "description": "Approval status", "enum": [ "PENDING", "APPROVED", "REJECTED", "COMMENTS" ], "example": "PENDING" }, "comments": { "type": "string", "description": "Approval comments", "example": "Under review" } } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Time entry creation timestamp", "example": "2024-11-20T17:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-11-21T10:30:00Z" }, "isActive": { "type": "boolean", "description": "Whether the WIP record is active (inactive records represent deletions)", "example": true } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to access this WIP time entry" }, "404": { "description": "WIP time entry not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "WIP time entry not found" }, "message": { "type": "string", "example": "WIP time entry with ID 89012 does not exist" } } } } } }, "500": { "description": "Internal server error" } } } }, "/api/v1/codes/types": { "get": { "tags": [ "Time Management" ], "summary": "List available time management code record types", "description": "\n**List available time management code record types**\n\n Returns the code types that can be managed via the Product API under `/api/v1/codes`.\n", "operationId": "listTimeManagementCodeTypes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Code types retrieved successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of TM_CODE_R, TM_CODE_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/codes/schema/{type}": { "get": { "tags": [ "Time Management" ], "summary": "Get field schema for a time management code type", "description": "\n**Get field schema for a time management code type**\n\n Returns field definitions for the requested code type.\n", "operationId": "getTimeManagementCodeSchema", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema retrieved successfully" }, "400": { "description": "Invalid code type" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of TM_CODE_R, TM_CODE_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/codes": { "post": { "tags": [ "Time Management" ], "summary": "Create or update time management code records (upsert)", "description": "\n**Create or update time management code records (upsert)**\n\n Records are created if they don't exist, or updated if matched by `systemRef`.\n Maximum 100 records per request.\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/codes' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"records\": example value\n}'\n```\n", "operationId": "upsertTimeManagementCodes", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "systemRef": { "type": "object", "description": "Systemref", "nullable": true }, "attributes": { "type": "object", "description": "Attributes" } } }, "description": "Records" } } } } } }, "responses": { "200": { "description": "All codes processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "description": "Summary" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Records" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires TM_CODE_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/codes/batch/{type}": { "post": { "tags": [ "Time Management" ], "summary": "Lookup time management code records in pages (by type)", "description": "\n**Lookup time management code records in pages**\n\n Request body:\n `{ \"pageSize\": 25, \"page\": 0 }`\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/codes/batch/{type}' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"page\": 1\n}'\n```\n", "operationId": "pagedLookupTimeManagementCodes", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "format": "int32", "description": "Pagesize" }, "page": { "type": "integer", "format": "int32", "description": "Page" } } } } } }, "responses": { "200": { "description": "Lookup completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "pageSize": { "type": "integer", "format": "int32", "description": "Pagesize" }, "page": { "type": "integer", "format": "int32", "description": "Page" }, "returned": { "type": "integer", "format": "int32", "description": "Returned" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Records" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of TM_CODE_R, TM_CODE_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/entries/types": { "get": { "tags": [ "Time Management" ], "summary": "List available time management entry record types", "description": "\n**List available time management entry record types**\n\n Returns the entry types that can be managed via the Product API under `/api/v1/entries`.\n", "operationId": "listTimeManagementEntryTypes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Entry types retrieved successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of TM_ENTRY_R, TM_ENTRY_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/entries/schema/{type}": { "get": { "tags": [ "Time Management" ], "summary": "Get field schema for a time management entry type", "description": "\n**Get field schema for a time management entry type**\n\n Returns field definitions for the requested entry type.\n\n For `TimeEntry`, the schema includes optional `taskId` (FK to Task) and `code`\n (work code string). Use `GET /api/v1/entries/schema/TimeEntry` to see the full\n attribute list for your tenant, including custom fields.\n", "operationId": "getTimeManagementEntrySchema", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema retrieved successfully" }, "400": { "description": "Invalid entry type" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of TM_ENTRY_R, TM_ENTRY_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/entries": { "post": { "tags": [ "Time Management" ], "summary": "Create or update time management entry records (upsert)", "description": "\n**Create or update time management entry records (upsert)**\n\n Records are created if they don't exist, or updated if matched by top-level `systemRef`.\n Maximum 100 records per request.\n\n ### TimeEntry โ€” linking a project task\n\n Use the optional `taskId` attribute to associate a time entry with a project task.\n Accepts a systemRef (`{ \"system\": \"PM\", \"reference\": \"\" }`), a numeric\n Aiwyn id, or a string numeric id (treated as Aiwyn id).\n\n When `taskId` is set and no work code is supplied, the work code is derived from the\n linked task's task type (same behavior as the firm portal UI).\n\n ### TimeEntry โ€” work code (`code` attribute)\n\n `code` is the **work code** (stored as `entry_code_id`), not the task. It must match\n the exact `time_management_entry_code.code` value, or fall back to `task_type.code`.\n When both `taskId` and `code` are provided, the explicit `code` wins.\n\n ### Resolving task references\n\n Look up tasks before upserting entries:\n - `GET /v1/task/{id}` โ€” get a task by Aiwyn id\n - `POST /v1/tasks/search` โ€” search tasks (filter by job, assignee, task type, dates)\n\n See `GET /api/v1/entries/schema/TimeEntry` for the full attribute list.\n\n ### Example โ€” TimeEntry with project task\n\n ```json\n {\n \"records\": [\n {\n \"type\": \"TimeEntry\",\n \"systemRef\": {\"system\": \"PM\", \"reference\": \"beeye-entry-001\"},\n \"attributes\": {\n \"pmsRef\": \"beeye-entry-001\",\n \"loggedDate\": \"2026-06-17T09:00:00\",\n \"value\": 2.5,\n \"billable\": true,\n \"notes\": \"Worked on tax planning deliverable\",\n \"clientId\": {\"system\": \"PM\", \"reference\": \"37584\"},\n \"jobId\": {\"system\": \"PM\", \"reference\": \"AIWYN_29059\"},\n \"loggedStaffId\": {\"system\": \"PM\", \"reference\": \"12345\"},\n \"taskId\": {\"system\": \"PM\", \"reference\": \"AIWYN_98765\"}\n }\n }\n ]\n }\n ```\n\n ### Example โ€” TimeEntry with task and explicit work code\n\n ```json\n {\n \"records\": [\n {\n \"type\": \"TimeEntry\",\n \"systemRef\": {\"system\": \"PM\", \"reference\": \"beeye-entry-002\"},\n \"attributes\": {\n \"pmsRef\": \"beeye-entry-002\",\n \"loggedDate\": \"2026-06-17T14:00:00\",\n \"value\": 1.0,\n \"clientId\": {\"system\": \"PM\", \"reference\": \"37584\"},\n \"jobId\": {\"system\": \"PM\", \"reference\": \"AIWYN_29059\"},\n \"loggedStaffId\": {\"system\": \"PM\", \"reference\": \"12345\"},\n \"taskId\": {\"system\": \"PM\", \"reference\": \"AIWYN_98765\"},\n \"code\": \"TXBLE30X01\"\n }\n }\n ]\n }\n ```\n\n**Business Applications:**\n- Sync time entries from external time-tracking systems\n- Attach project tasks to time entries\n- Upsert entries by external system reference\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/entries' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"records\": [\n {\n \"type\": \"TimeEntry\",\n \"systemRef\": {\"system\": \"PM\", \"reference\": \"beeye-entry-001\"},\n \"attributes\": {\n \"pmsRef\": \"beeye-entry-001\",\n \"loggedDate\": \"2026-06-17T09:00:00\",\n \"value\": 2.5,\n \"billable\": true,\n \"notes\": \"Worked on tax planning deliverable\",\n \"clientId\": {\"system\": \"PM\", \"reference\": \"37584\"},\n \"jobId\": {\"system\": \"PM\", \"reference\": \"AIWYN_29059\"},\n \"loggedStaffId\": {\"system\": \"PM\", \"reference\": \"12345\"},\n \"taskId\": {\"system\": \"PM\", \"reference\": \"AIWYN_98765\"}\n }\n }\n ]\n}'\n```\n", "operationId": "upsertTimeManagementEntries", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "systemRef": { "type": "object", "description": "Systemref", "nullable": true }, "attributes": { "type": "object", "description": "Attributes" } } }, "description": "Records" } } } } } }, "responses": { "200": { "description": "All entries processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "description": "Summary" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Records" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires TM_ENTRY_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/entries/batch/{type}": { "post": { "tags": [ "Time Management" ], "summary": "Lookup time management entry records in pages (by type)", "description": "\n**Lookup time management entry records in pages**\n\n Request body:\n `{ \"pageSize\": 25, \"page\": 0 }`\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/entries/batch/{type}' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"pageSize\": 1,\n \"page\": 1\n}'\n```\n", "operationId": "pagedLookupTimeManagementEntries", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "integer", "format": "int32", "description": "Pagesize" }, "page": { "type": "integer", "format": "int32", "description": "Page" } } } } } }, "responses": { "200": { "description": "Lookup completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "pageSize": { "type": "integer", "format": "int32", "description": "Pagesize" }, "page": { "type": "integer", "format": "int32", "description": "Page" }, "returned": { "type": "integer", "format": "int32", "description": "Returned" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Records" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of TM_ENTRY_R, TM_ENTRY_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/records": { "post": { "tags": [ "Records" ], "summary": "Create or update records (upsert)", "description": "\n**Create or update records (upsert)**\n\n Records are created if they don't exist, or updated if matched by systemRef.\n\n **Partial Success Behavior:**\n - Each record is processed independently\n - Successful records are persisted even if others fail\n - Check `summary.failed` and individual `records[].status` for failures\n - Failed records include error details in `records[].error`\n\n **Limits:** Maximum 100 records per request.\n\n**Business Applications:**\n- Bulk record import\n- Entity synchronization\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/records' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"records\": [\n {\n \"type\": \"Client\",\n \"systemRef\": {\"system\": \"CCH\", \"reference\": \"C-12345\"},\n \"attributes\": {\n \"name\": \"Acme Corporation\",\n \"email\": \"contact@acme.com\"\n }\n }\n ]\n}'\n```\n", "operationId": "createOrUpdateRecords", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "systemRef": { "type": "object", "description": "Systemref", "nullable": true }, "attributes": { "type": "object", "description": "Attributes" } } }, "description": "Records" } } } } } }, "responses": { "200": { "description": "Records processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "description": "Summary" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Records" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires RECD_C)" }, "500": { "description": "Internal server error" } } }, "put": { "tags": [ "Records" ], "summary": "Update records (fails if not found)", "description": "\n**Update existing records only**\n\n Only updates existing records. Returns error if record not found by systemRef.\n The systemRef field is required for all records in PUT requests.\n\n **Partial Success Behavior:**\n - Each record is processed independently\n - Successful records are persisted even if others fail\n - Records not found will have status `FAILED` with error code `RECORD_NOT_FOUND`\n - Check `summary.failed` and individual `records[].status` for failures\n\n **Limits:** Maximum 100 records per request.\n\n**Business Applications:**\n- Strict update workflows\n- Guaranteed existence updates\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/records' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"records\": [\n {\n \"type\": \"Client\",\n \"systemRef\": {\"system\": \"CCH\", \"reference\": \"C-12345\"},\n \"attributes\": {\n \"email\": \"updated@acme.com\",\n \"phone\": \"555-1234\"\n }\n }\n ]\n}'\n```\n", "operationId": "updateRecords", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "systemRef": { "type": "object", "description": "Systemref", "nullable": true }, "attributes": { "type": "object", "description": "Attributes" } } }, "description": "Records" } } } } } }, "responses": { "200": { "description": "Records updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "description": "Summary" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Records" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires RECD_C)" }, "404": { "description": "Records not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Records" ], "summary": "Delete (inactivate) records", "description": "\n**Delete (inactivate) records**\n\n Soft-deletes records by marking them as inactive. Returns error if record not found.\n The systemRef field is required for all records in DELETE requests.\n\n **Partial Success Behavior:**\n - Each record is processed independently\n - Successful deletions are persisted even if others fail\n - Records not found will have status `FAILED` with error code `RECORD_NOT_FOUND`\n - Check `summary.failed` and individual `records[].status` for failures\n\n **Limits:** Maximum 100 records per request.\n\n**Business Applications:**\n- Bulk inactivation\n- Record cleanup\n", "operationId": "deleteRecords", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type" }, "systemRef": { "type": "object", "description": "Systemref" } } }, "description": "Records" } } } } } }, "responses": { "200": { "description": "Records deleted successfully" }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires RECD_C)" }, "404": { "description": "Records not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/records/types": { "get": { "tags": [ "Records" ], "summary": "List available record types", "description": "\n**List available record types**\n\n Returns record types that can be managed via this API, with schema URLs.\n\n**Business Applications:**\n- Discover record types\n", "operationId": "listEntityTypes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Entity types retrieved successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of RECD_R, RECD_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/records/schema/{type}": { "get": { "tags": [ "Records" ], "summary": "Get field schema for a record type", "description": "\n**Get field schema for a record type**\n\n Returns field definitions including types, validation, and foreign key relationships.\n\n**Business Applications:**\n- Dynamic form generation\n- Field validation\n- Integration mapping\n", "operationId": "getEntitySchema", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema retrieved successfully" }, "400": { "description": "Invalid record type" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of RECD_R, RECD_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/records/custom": { "get": { "tags": [ "Records" ], "summary": "List all custom record types", "description": "\n**List all custom record types**\n\n Returns all custom record type definitions for the tenant.\n Use includeInactive=true to include deactivated record types.\n\n**Business Applications:**\n- Discover custom record types\n- Integration configuration\n", "operationId": "listCustomRecordTypes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Record types retrieved successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of CUSTYP_R, CUSTYP_C)" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Records" ], "summary": "Create a new custom record type", "description": "\n**Create a new custom record type**\n\n Creates a new custom record type with the specified field schema.\n The record type name must be unique and follow naming conventions.\n\n**Business Applications:**\n- Define custom data structures\n- Extend system capabilities\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/records/custom' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"name\": \"Example Name\",\n \"displayName\": \"Example Name\",\n \"description\": \"example value\"\n}'\n```\n", "operationId": "createCustomRecordType", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "fields" ], "properties": { "name": { "type": "string", "description": "Name" }, "displayName": { "type": "string", "description": "Displayname", "nullable": true }, "description": { "type": "string", "description": "Description", "nullable": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name" }, "displayName": { "type": "string", "description": "Displayname", "nullable": true }, "type": { "type": "string", "description": "Type" }, "required": { "type": "boolean", "description": "Required" }, "nullable": { "type": "boolean", "description": "Nullable" }, "description": { "type": "string", "description": "Description", "nullable": true }, "referencedEntityType": { "type": "string", "description": "Referencedentitytype", "nullable": true }, "rank": { "type": "integer", "format": "int32", "description": "Rank", "nullable": true } } }, "description": "Fields" } } } } } }, "responses": { "201": { "description": "Record type created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Id" }, "name": { "type": "string", "description": "Name" }, "displayName": { "type": "string", "description": "Displayname" }, "description": { "type": "string", "description": "Description", "nullable": true }, "isCustom": { "type": "boolean", "description": "Iscustom" }, "active": { "type": "boolean", "description": "Active" }, "fields": { "type": "array", "items": { "type": "object" }, "description": "Fields" }, "recordsUrl": { "type": "string", "description": "Recordsurl", "nullable": true }, "schemaUrl": { "type": "string", "description": "Schemaurl" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires CUSTYP_C)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/records/custom/{name}": { "get": { "tags": [ "Records" ], "summary": "Get a custom record type by name", "description": "\n**Get a custom record type by name**\n\n Returns the full definition of a custom record type including its field schema.\n\n**Business Applications:**\n- View record type schema\n- Integration setup\n", "operationId": "getCustomRecordType", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Record type retrieved successfully" }, "400": { "description": "Invalid record type name" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires any of CUSTYP_R, CUSTYP_C)" }, "404": { "description": "Record type not found" }, "500": { "description": "Internal server error" } } }, "put": { "tags": [ "Records" ], "summary": "Update a custom record type", "description": "\n**Update a custom record type**\n\n Updates an existing custom record type. Only provided fields will be updated.\n Note: Changing fields may affect existing data.\n\n**Business Applications:**\n- Modify record type definitions\n- Add new fields\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/records/custom/{name}' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"displayName\": \"Example Name\",\n \"description\": \"example value\",\n \"fields\": example value\n}'\n```\n", "operationId": "updateCustomRecordType", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Displayname", "nullable": true }, "description": { "type": "string", "description": "Description", "nullable": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name" }, "displayName": { "type": "string", "description": "Displayname", "nullable": true }, "type": { "type": "string", "description": "Type" }, "required": { "type": "boolean", "description": "Required" }, "nullable": { "type": "boolean", "description": "Nullable" }, "description": { "type": "string", "description": "Description", "nullable": true }, "referencedEntityType": { "type": "string", "description": "Referencedentitytype", "nullable": true }, "rank": { "type": "integer", "format": "int32", "description": "Rank", "nullable": true } } }, "description": "Fields", "nullable": true }, "active": { "type": "boolean", "description": "Active", "nullable": true } } } } } }, "responses": { "200": { "description": "Record type updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Id" }, "name": { "type": "string", "description": "Name" }, "displayName": { "type": "string", "description": "Displayname" }, "description": { "type": "string", "description": "Description", "nullable": true }, "isCustom": { "type": "boolean", "description": "Iscustom" }, "active": { "type": "boolean", "description": "Active" }, "fields": { "type": "array", "items": { "type": "object" }, "description": "Fields" }, "recordsUrl": { "type": "string", "description": "Recordsurl", "nullable": true }, "schemaUrl": { "type": "string", "description": "Schemaurl" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires CUSTYP_C)" }, "404": { "description": "Record type not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Records" ], "summary": "Deactivate a custom record type", "description": "\n**Deactivate a custom record type**\n\n Soft-deletes a custom record type by marking it as inactive.\n Existing data is preserved but the type will no longer appear in lists.\n\n**Business Applications:**\n- Remove custom record types\n- Clean up unused definitions\n", "operationId": "deactivateCustomRecordType", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Record type deactivated successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires CUSTYP_C)" }, "404": { "description": "Record type not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/event-subscriptions/catalog": { "get": { "tags": [ "Event Subscriptions" ], "summary": "Get available event types catalog", "description": "\n**Get catalog of available event types**\n\n Returns all entity/operation combinations that can be subscribed to.\n Use the 'enabled' query parameter to filter by enabled status.\n\n**Business Applications:**\n- Discover available events\n- Integration planning\n", "operationId": "getEventSettingsCatalog", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Event Subscriptions retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_API_ADMIN)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/event-subscriptions": { "post": { "tags": [ "Event Subscriptions" ], "summary": "Create a webhook subscription", "description": "\n**Create a webhook subscription for entity events**\n\n Subscribe to receive webhook notifications when entities are created, updated, or deleted.\n The webhook URL must use HTTPS and will receive POST requests with event data.\n\n**Business Applications:**\n- Real-time integrations\n- Event-driven workflows\n- System synchronization\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/event-subscriptions' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"entityType\": example value,\n \"operation\": example value,\n \"deliveryUrl\": \"example value\"\n}'\n```\n", "operationId": "createEventSubscription", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entityType", "operation", "deliveryUrl" ], "properties": { "entityType": { "type": "object", "description": "Entitytype" }, "operation": { "type": "object", "description": "Operation" }, "deliveryUrl": { "type": "string", "description": "Deliveryurl" }, "filterExpression": { "type": "string", "description": "Narrows what this subscription receives. Supported values: `ownPaymentLinksOnly` (only\npayments made through quick payment links minted by the API user that owns this\nsubscription; links minted through the SafeSend application-key route have no minting\nuser and never match), `paymentLinkOnly` (payments made through any quick payment link of the\nfirm) and `allPayments` (every payment of the firm). The last two are accepted only while\nthe API user holds the `PYMT_EVNT_ALL` Product API role, and stop delivering if the firm\nrevokes it. Any other value is rejected with 400. Required for `Payment` subscriptions;\noptional for other entity types, where omitting it means every event of the entity and\noperation.\n", "example": "ownPaymentLinksOnly", "nullable": true }, "description": { "type": "string", "description": "Description", "nullable": true } } } } } }, "responses": { "201": { "description": "Event Subscriptions created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "subscription": { "type": "object", "description": "Subscription" }, "webhookSecret": { "type": "string", "description": "Webhooksecret" }, "webhookSecretInstructions": { "type": "string", "description": "Webhooksecretinstructions" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_API_ADMIN)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/event-subscriptions/{id}": { "patch": { "tags": [ "Event Subscriptions" ], "summary": "Update a webhook subscription", "description": "\n**Update an existing webhook subscription**\n\n Modify subscription properties such as delivery URL, filter expression, or description.\n Only provided fields will be updated.\n\n**Business Applications:**\n- Update webhook URLs\n- Modify event filters\n", "operationId": "updateEventSubscription", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "object", "description": "Entitytype", "nullable": true }, "operation": { "type": "object", "description": "Operation", "nullable": true }, "deliveryUrl": { "type": "string", "description": "Deliveryurl", "nullable": true }, "filterExpression": { "type": "string", "description": "Narrows what this subscription receives. Supported values: `ownPaymentLinksOnly` (only\npayments made through quick payment links minted by the API user that owns this\nsubscription; links minted through the SafeSend application-key route have no minting\nuser and never match), `paymentLinkOnly` (payments made through any quick payment link of the\nfirm) and `allPayments` (every payment of the firm). The last two are accepted only while\nthe API user holds the `PYMT_EVNT_ALL` Product API role, and stop delivering if the firm\nrevokes it. Any other value is rejected with 400. Required for `Payment` subscriptions;\noptional for other entity types, where omitting it means every event of the entity and\noperation.\n", "example": "ownPaymentLinksOnly", "nullable": true }, "description": { "type": "string", "description": "Description", "nullable": true }, "active": { "type": "boolean", "description": "Active", "nullable": true } } } } } }, "responses": { "200": { "description": "Event Subscriptions updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Id" }, "staffId": { "type": "integer", "format": "int64", "description": "Staffid", "nullable": true }, "entityType": { "type": "object", "description": "Entitytype" }, "operation": { "type": "object", "description": "Operation" }, "deliveryUrl": { "type": "string", "description": "Deliveryurl" }, "description": { "type": "string", "description": "Description", "nullable": true }, "filterExpression": { "type": "string", "description": "Filterexpression", "nullable": true }, "active": { "type": "boolean", "description": "Active" }, "status": { "type": "string", "description": "Status" }, "createdAt": { "type": "string", "format": "date-time", "description": "Createdat", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updatedat", "nullable": true }, "isInternal": { "type": "boolean", "description": "Isinternal" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_API_ADMIN)" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Event Subscriptions" ], "summary": "Deactivate a webhook subscription", "description": "\n**Deactivate a webhook subscription**\n\n Soft-deletes a subscription by marking it as inactive.\n The subscription can be reactivated later if needed.\n\n**Business Applications:**\n- Stop receiving webhooks\n- Cleanup unused subscriptions\n", "operationId": "deactivateEventSubscription", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Event Subscriptions deleted successfully - No content returned" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_API_ADMIN)" }, "404": { "description": "Event Subscriptions not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/event-subscriptions/{id}/reactivate": { "post": { "tags": [ "Event Subscriptions" ], "summary": "Reactivate a webhook subscription", "description": "\n**Reactivate a webhook subscription**\n\n Reactivates a previously deactivated subscription.\n\n**Business Applications:**\n- Restore webhook integrations\n- Resume event notifications\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/event-subscriptions/{id}/reactivate' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n```\n", "operationId": "reactivateEventSubscription", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Subscription reactivated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Id" }, "staffId": { "type": "integer", "format": "int64", "description": "Staffid", "nullable": true }, "entityType": { "type": "object", "description": "Entitytype" }, "operation": { "type": "object", "description": "Operation" }, "deliveryUrl": { "type": "string", "description": "Deliveryurl" }, "description": { "type": "string", "description": "Description", "nullable": true }, "filterExpression": { "type": "string", "description": "Filterexpression", "nullable": true }, "active": { "type": "boolean", "description": "Active" }, "status": { "type": "string", "description": "Status" }, "createdAt": { "type": "string", "format": "date-time", "description": "Createdat", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updatedat", "nullable": true }, "isInternal": { "type": "boolean", "description": "Isinternal" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Subscription filter no longer allowed" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires EVNT_SUB)" }, "404": { "description": "Subscription not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/event-subscriptions/{id}/deliveries": { "get": { "tags": [ "Event Subscriptions" ], "summary": "Retrieve webhook delivery attempts for a subscription", "description": "\n**Retrieve webhook delivery attempts for a subscription**\n\n Returns a paginated list of delivery attempts for webhook events for the given subscription.\n Supports filtering by HTTP status code and time range.\n\n**Business Applications:**\n- Webhook troubleshooting\n- Delivery monitoring\n- Operational auditing\n", "operationId": "getWebhookDeliveryHistory", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Delivery history retrieved successfully" }, "400": { "description": "Invalid query parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires EVNT_SUB)" }, "404": { "description": "Subscription not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/event-subscriptions/webhook/secret": { "get": { "tags": [ "Event Subscriptions" ], "summary": "Get webhook signing secret", "description": "\n**Get the webhook signing secret**\n\n Retrieves the secret used to sign webhook payloads.\n Use this secret to verify webhook authenticity on your server.\n\n**Business Applications:**\n- Webhook signature verification\n- Security setup\n", "operationId": "getSubscriptionSecret", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Event Subscriptions retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires ROLE_API_ADMIN)" }, "404": { "description": "Event Subscriptions not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/webhook/test/generate": { "post": { "tags": [ "Event Subscriptions" ], "summary": "Generate a test webhook payload and signature", "description": "\n**Generate a signed test webhook payload**\n\n Generates a signature for an arbitrary JSON payload using the provided secret.\n This is intended for debugging webhook integrations ONLY.\n\n**Business Applications:**\n- Webhook troubleshooting\n- Signature validation testing\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/webhook/test/generate' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n```\n", "operationId": "generateWebhookTestPayload", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Generated payload and signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "isValid": { "type": "boolean", "description": "Isvalid" }, "payload": { "type": "object", "description": "Payload" }, "signature": { "type": "string", "description": "Signature" }, "secret": { "type": "string", "description": "Secret" } } }, "error": { "type": "object", "nullable": true }, "meta": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions" }, "500": { "description": "Internal server error" } } } }, "/api/v1/webhook/test/validate": { "post": { "tags": [ "Event Subscriptions" ], "summary": "Validate a webhook signature", "description": "\n**Validate a webhook signature**\n\n Verifies that the provided signature matches the payload and secret.\n This is intended for debugging webhook integrations ONLY.\n\n**Business Applications:**\n- Webhook troubleshooting\n- Signature validation testing\n\n**Real Example:**\n```bash\ncurl --location 'https://{{host}}/api/v1/webhook/test/validate' \\\n--header 'Authorization: bearer {{token}}' \\\n--header 'Content-Type: application/json' \\\n```\n", "operationId": "validateWebhookTestSignature", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions" }, "500": { "description": "Internal server error" } } } }, "/api/v1/files": { "get": { "tags": [ "File" ], "summary": "List files with filters and cursor pagination", "description": "\n**Retrieve a paginated list of files scoped to the tenant**\n\n Returns files across whitelisted sources: CLIENT_REQUEST, DELIVERABLE, REFERENCE_FILE, DMS_DIRECT_UPLOAD.\n\n **Optional Filters:**\n - `createdAfter` (ISO-8601) โ€” only files created strictly after this timestamp\n - `createdBefore` (ISO-8601) โ€” only files created strictly before this timestamp\n - `clientId` โ€” filter by numeric client ID\n - `projectId` โ€” filter by project/job ID\n - `ids` โ€” filter by one or more specific file IDs (multi-value: `?ids=1&ids=2`)\n\n **Pagination:**\n - Results ordered by `created_at ASC, id ASC`\n - Pass `next_cursor` from a previous response as `cursor` to fetch the next page\n - `pageSize` defaults to 20, max 100\n\n **Response per item:**\n - File metadata (id, name, created_at, size_bytes, path as slash-joined folder names)\n - `download_url` โ€” time-limited direct-link URL; only populated when `includeDownloadUrl=true` and the file has a DMS path or external ID. Omit this flag for metadata-only queries (pagination, search) to avoid unnecessary URL minting on every page.\n - `context` โ€” client, project, and uploader fields\n\n **Note:** Invalid date formats return 400.\n\n**Business Applications:**\n- Retrieve all files associated with a client or project\n- Paginate through large file sets using cursor pagination\n- Filter files by upload date range\n- Fetch specific files by ID\n", "operationId": "listFiles", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Files retrieved successfully" }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires API_ADMIN)" }, "500": { "description": "Internal server error" } } } }, "/api/v1/files/{id}": { "get": { "tags": [ "File" ], "summary": "Get file metadata by ID", "description": "\n**Retrieve file metadata by Aiwyn ID**\n\n Returns file metadata including filename, source type, status, and optional download URL.\n\n **Query Parameters:**\n - `includeDownloadUrl` (optional, default: false) - When true, generates a time-limited signed download URL\n\n **Response includes:**\n - File metadata (id, filename, fileSource, fileStatus, active, timestamps)\n - FileInfo metadata (size, creator information) if available\n - Signed download URL (only when includeDownloadUrl=true and file has GCS path)\n\n **Note:** Download URLs are time-limited (15 minutes) and should be used promptly.\n\n**Business Applications:**\n- Retrieve file metadata for display\n- Generate download URLs for file access\n- Verify file existence and status\n", "operationId": "getFileById", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "File retrieved successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions (requires API_ADMIN)" }, "404": { "description": "File not found" }, "500": { "description": "Internal server error" } } } } }, "components": { "schemas": { "Error": { "type": "object", "description": "Standard error response format", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable error message", "example": "Invalid parameter value" }, "code": { "type": "string", "description": "Machine-readable error code", "example": "INVALID_PARAMETER" }, "details": { "type": "string", "description": "Additional error context", "example": "The 'pageSize' parameter must be between 1 and 1000" } } }, "DraftInvoiceHistory": { "type": "object", "description": "Draft invoice history record with client and draft invoice details", "properties": { "clientId": { "type": "integer", "description": "Client identifier", "example": 7720 }, "invoiceId": { "type": "integer", "description": "Invoice identifier", "example": 125890 }, "jobId": { "type": "integer", "description": "Associated job/project identifier", "example": 2514 }, "client": { "type": "object", "description": "Client summary information", "properties": { "active": { "type": "boolean", "example": true }, "clientRef": { "type": "string", "example": "TF-2024-789" }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "pmsRef": { "type": "string", "example": "240815" } } }, "draftInvoice": { "type": "object", "description": "Draft invoice metadata", "properties": { "approvedAt": { "type": "string", "format": "date-time", "example": "2024-03-15T14:32:18+00:00" }, "arTranId": { "type": "integer", "example": 125890 }, "approverStaffId": { "type": "integer", "example": 301 }, "approvedByStaffId": { "type": "integer", "example": 301 }, "invoiceId": { "type": "integer", "example": 125890 }, "isActive": { "type": "boolean", "example": true }, "pms_invoice_number": { "type": "string", "example": "INV-2024-4850" }, "status": { "type": "string", "example": "APPROVED" } } } } }, "DraftInvoiceHistoryListResponse": { "type": "object", "description": "Standard response format for draft invoice history endpoints", "properties": { "draftInvoices": { "type": "array", "items": { "$ref": "#/components/schemas/DraftInvoiceHistory" } }, "total": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of draft invoice history records matching criteria", "example": 94 } } } } } } }, "StaffMember": { "type": "object", "description": "Staff member basic information", "properties": { "id": { "type": "integer", "example": 53 }, "pmsRef": { "type": "string", "nullable": true, "example": "A53" }, "staffRef": { "type": "string", "nullable": true, "example": "AH" }, "firstName": { "type": "string", "example": "Allen" }, "lastName": { "type": "string", "example": "Hermiston" }, "email": { "type": "string", "format": "email", "example": "allen.hermiston@company.com" } } }, "ClientGroup": { "type": "object", "description": "Client group record with assigned staff and office information", "properties": { "id": { "type": "integer", "description": "Unique client group identifier", "example": 10 }, "name": { "type": "string", "description": "Client group name", "example": "Acme Corp Group" }, "pmsRef": { "type": "string", "description": "Practice Management System reference", "example": "GRP-001" }, "parentClientId": { "type": "integer", "nullable": true, "description": "ID of the parent client, if any", "example": null }, "primaryContactId": { "type": "integer", "nullable": true, "description": "ID of the primary contact", "example": 201 }, "billingContactId": { "type": "integer", "nullable": true, "description": "ID of the billing contact", "example": 202 }, "partnerStaffId": { "type": "integer", "nullable": true, "description": "ID of the assigned partner staff member", "example": 101 }, "managerStaffId": { "type": "integer", "nullable": true, "description": "ID of the assigned manager staff member", "example": 102 }, "officeId": { "type": "integer", "nullable": true, "description": "ID of the associated office", "example": 5 }, "active": { "type": "boolean", "description": "Whether the client group is active", "example": true }, "isManagedByAiwyn": { "type": "boolean", "description": "Whether the client group is managed by Aiwyn", "example": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation timestamp", "example": "2024-01-15T10:00:00.000000+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last modification timestamp", "example": "2024-06-20T14:30:00.000000+00:00" }, "version": { "type": "integer", "description": "Record version number", "example": 3 }, "partnerStaff": { "$ref": "#/components/schemas/StaffMember" }, "managerStaff": { "$ref": "#/components/schemas/StaffMember" }, "office": { "type": "object", "nullable": true, "description": "Associated office", "properties": { "id": { "type": "integer", "example": 5 }, "pmsRef": { "type": "string", "example": "OFF-5" }, "name": { "type": "string", "example": "San Francisco" } } } } }, "ClientContactInfo": { "type": "object", "description": "Client contact information details", "properties": { "id": { "type": "integer", "example": 9957 }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "loree.kling@yahoo.com" }, "phone": { "type": "string", "example": "1-555-123-4567" }, "address": { "type": "string", "example": "123 Main Street" }, "city": { "type": "string", "example": "Anytown" }, "state": { "type": "string", "example": "CA" }, "zip_code": { "type": "string", "example": "12345" } } }, "Client": { "type": "object", "description": "Complete client record with all associated data", "properties": { "id": { "type": "integer", "description": "Unique client identifier", "example": 2180 }, "pmsRef": { "type": "string", "description": "Practice Management System reference", "example": "1155" }, "clientRef": { "type": "string", "description": "External client reference number", "example": "41664" }, "name": { "type": "string", "description": "Client full name or company name", "example": "Aaron Fahey" }, "clientKey": { "type": "string", "description": "Formatted client key with padding", "example": "000000041664 f" }, "active": { "type": "boolean", "description": "Client active status", "example": true }, "partnerStaffId": { "type": "integer", "description": "ID of assigned partner staff member", "example": 53 }, "managerStaffId": { "type": "integer", "description": "ID of assigned manager staff member", "example": 19 }, "createdAt": { "type": "string", "format": "date-time", "description": "Client record creation timestamp", "example": "2023-05-12T22:43:55.488054+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last modification timestamp", "example": "2023-06-09T21:34:28.817274+00:00" }, "clientContactInfo": { "$ref": "#/components/schemas/ClientContactInfo" }, "partnerStaff": { "$ref": "#/components/schemas/StaffMember" }, "managerStaff": { "$ref": "#/components/schemas/StaffMember" } } }, "ClientWithNumber": { "type": "object", "description": "Client details with number field", "properties": { "id": { "type": "integer", "example": 420 }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "number": { "type": "string", "example": "52150" } } }, "Engagement": { "type": "object", "description": "Project engagement record with staff assignments", "properties": { "id": { "type": "integer", "description": "Unique engagement identifier", "example": 8 }, "name": { "type": "string", "description": "Generated engagement name from template", "example": "2024 Annual Review and Tax 52150" }, "start_dt": { "type": "string", "format": "date", "description": "Engagement start date", "example": "2024-03-15" }, "end_dt": { "type": "string", "format": "date", "description": "Engagement end date", "example": "2024-04-30" }, "status": { "type": "string", "description": "Current engagement status", "example": "EXECUTED" }, "client_id": { "type": "integer", "description": "Associated client identifier", "example": 420 }, "partner_staff_id": { "type": "integer", "description": "Partner staff member assigned to engagement", "example": 53 }, "manager_staff_id": { "type": "integer", "description": "Manager staff member assigned to engagement", "example": 15 }, "created_at": { "type": "string", "format": "date-time", "description": "Engagement record creation timestamp", "example": "2024-03-14T10:58:38.605333+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Engagement record last update timestamp", "example": "2024-07-27T00:08:05.822177+00:00" }, "engagement_name_template": { "type": "string", "description": "Template used to generate engagement name", "example": "{{fiscal_year.year}} {{letter_template.name}} {{client.number}}" }, "client": { "$ref": "#/components/schemas/ClientWithNumber" }, "partnerStaff": { "$ref": "#/components/schemas/StaffMember" }, "managerStaff": { "$ref": "#/components/schemas/StaffMember" } } }, "Department": { "type": "object", "description": "Department information", "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "Technology" } } }, "StaffOffice": { "type": "object", "properties": { "id": { "type": "integer" }, "pmsRef": { "type": "string", "nullable": true }, "name": { "type": "string" }, "city": { "type": "string", "nullable": true }, "stateProvince": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } } }, "StaffClassification": { "type": "object", "description": "Referenced staff classification", "properties": { "id": { "type": "integer", "example": 2 }, "pmsRef": { "type": "string", "nullable": true, "example": "FT" }, "name": { "type": "string", "example": "Full Time" } } }, "StaffType": { "type": "object", "description": "Staff type classification details", "properties": { "id": { "type": "integer", "example": 11 }, "pmsRef": { "type": "string", "nullable": true }, "display": { "type": "string", "nullable": true }, "description": { "type": "string", "example": "Senior Associate" }, "rateCardStaffTypeBillingRates": { "type": "array", "description": "Billing rates configured for this role", "items": { "type": "object", "additionalProperties": true } } } }, "StaffPermissionSet": { "type": "object", "description": "Permission set summary", "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Standard Manager" } } }, "StaffDirectoryRecord": { "type": "object", "description": "Staff directory record with organizational, employment, permission, and reporting relationships", "properties": { "id": { "type": "integer", "example": 21 }, "pmsRef": { "type": "string", "nullable": true, "example": "AIWYN_21" }, "staffRef": { "type": "string", "nullable": true, "example": "AIWYN" }, "firstName": { "type": "string", "example": "Aiwyn" }, "lastName": { "type": "string", "example": "User" }, "email": { "type": "string", "format": "email", "example": "test@aiwyn.ai" }, "active": { "type": "boolean", "example": true }, "deptId": { "type": "integer", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "jobTitleId": { "type": "integer", "nullable": true }, "type": { "type": "string", "nullable": true }, "officeId": { "type": "integer", "nullable": true }, "department": { "allOf": [ { "$ref": "#/components/schemas/Department" } ], "nullable": true }, "office": { "allOf": [ { "$ref": "#/components/schemas/StaffOffice" } ], "nullable": true }, "serviceLine": { "description": "Primary service line assigned to the staff member", "allOf": [ { "$ref": "#/components/schemas/StaffClassification" } ], "nullable": true }, "subServiceLine": { "description": "Sub-service line assigned to the staff member", "allOf": [ { "$ref": "#/components/schemas/StaffClassification" } ], "nullable": true }, "wageType": { "description": "Wage classification, such as salary or hourly", "allOf": [ { "$ref": "#/components/schemas/StaffClassification" } ], "nullable": true }, "employeeType": { "description": "Employment classification, such as full time or contractor", "allOf": [ { "$ref": "#/components/schemas/StaffClassification" } ], "nullable": true }, "role": { "description": "Staff role; this response field replaces the former `staffType` field", "allOf": [ { "$ref": "#/components/schemas/StaffType" } ], "nullable": true }, "permissionSet": { "description": "Permission set assigned directly to the staff member", "allOf": [ { "$ref": "#/components/schemas/StaffPermissionSet" } ], "nullable": true }, "staffSupervisor": { "description": "Staff member assigned as this person's supervisor", "allOf": [ { "$ref": "#/components/schemas/StaffMember" } ], "nullable": true }, "staffManagerId": { "type": "integer", "nullable": true }, "rateCardBillingRates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the most recent staff record update", "example": "2026-09-21T18:30:00Z" } } }, "ClientBasic": { "type": "object", "description": "Basic client information for relationships", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "TechFlow Enterprises" } } }, "CreditLabel": { "type": "object", "description": "Credit label details for categorization", "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Service Credit" }, "description": { "type": "string", "example": "Credit for service issues or complaints" } } }, "DebitLabel": { "type": "object", "description": "Debit label details for categorization", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Late Fee" }, "description": { "type": "string", "example": "Late payment penalty charge" }, "is_active": { "type": "boolean", "example": true } } }, "ARTransactionBasic": { "type": "object", "description": "Basic AR transaction details for invoice relationships", "properties": { "id": { "type": "integer", "example": 125890 }, "pmsRef": { "type": "string", "description": "Practice management system reference", "example": "240815" }, "transactionDate": { "type": "string", "format": "date-time", "description": "Transaction date", "example": "2024-03-22T05:00:00" }, "amount": { "type": "number", "format": "decimal", "description": "Transaction amount", "example": 4250 }, "allocated": { "type": "number", "format": "decimal", "description": "Allocated amount", "example": 4250 }, "clientId": { "type": "integer", "description": "Client identifier", "example": 7720 }, "client": { "$ref": "#/components/schemas/ClientBasic" } } }, "ClientWithRef": { "type": "object", "description": "Client information with reference number", "properties": { "id": { "type": "integer", "example": 789 }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "clientRef": { "type": "string", "example": "TF-2024-789" } } }, "Job": { "type": "object", "description": "Job information for WIP tracking", "properties": { "id": { "type": "integer", "example": 2514 }, "name": { "type": "string", "example": "Q1 Financial Review 2024" } } }, "PaginationRequest": { "type": "object", "description": "Hasura REST list/search pagination. `pageSize` is a limit and `page` is an\noffset (records to skip), not a page index.\n", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Limit โ€” number of records to return (not a page count). Hasura maps this to `limit`.", "example": 25 }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Offset โ€” number of records to skip. This is not a page index. Hasura maps\nthis to `offset`. To fetch the next N rows after the first N, send\n`pageSize: N` and `page: N`. An offset at or beyond `total.aggregate.count`\nreturns an empty result array.\n", "example": 0 } } }, "AggregateCount": { "type": "object", "description": "Standard count aggregation", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of records matching criteria", "example": 13697 } } } } }, "ARTransaction": { "type": "object", "description": "Accounts receivable transaction record", "properties": { "id": { "type": "integer", "description": "Unique transaction identifier", "example": 125001 }, "pmsRef": { "type": "string", "description": "Practice management system reference number", "example": "240815" }, "type": { "type": "string", "description": "Transaction type classification", "example": "Receipt" }, "transactionDate": { "type": "string", "format": "date-time", "description": "Date when transaction occurred", "example": "2024-02-15T05:00:00" }, "amount": { "type": "number", "format": "decimal", "description": "Transaction amount (negative for receipts/credits)", "example": -1250 }, "allocated": { "type": "number", "format": "decimal", "description": "Amount allocated/applied to invoices", "example": -1250 }, "notes": { "type": "string", "description": "Additional transaction notes or comments", "example": null }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation timestamp", "example": "2024-05-12T22:50:18.418236+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Record last update timestamp", "example": "2024-05-12T22:50:18.418236+00:00" }, "client": { "$ref": "#/components/schemas/ClientBasic" } } }, "AggregateCountSum": { "type": "object", "description": "Count and sum aggregation for financial data", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of records matching criteria", "example": 48 }, "sum": { "type": "object", "properties": { "amount": { "type": "number", "format": "decimal", "description": "Sum of amounts", "example": -52750 }, "allocated": { "type": "number", "format": "decimal", "description": "Sum of allocated amounts", "example": -52750 } } } } } } }, "Credit": { "type": "object", "description": "Credit entry with categorization", "properties": { "ar_tran_id": { "type": "integer", "description": "Associated AR transaction identifier", "example": 125890 }, "is_partial": { "type": "boolean", "description": "Whether this is a partial credit (true) or full credit (false)", "example": false }, "credit_label_id": { "type": "integer", "description": "Reference to credit categorization label", "example": 3 }, "created_at": { "type": "string", "format": "date-time", "description": "Credit record creation timestamp", "example": "2024-05-12T22:50:21.31979+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Credit record last update timestamp", "example": "2024-05-12T22:50:21.31979+00:00" }, "creditLabel": { "$ref": "#/components/schemas/CreditLabel" } } }, "Debit": { "type": "object", "description": "Debit entry with categorization and staff tracking", "properties": { "ar_tran_id": { "type": "integer", "description": "Associated AR transaction identifier", "example": 125890 }, "debit_label_id": { "type": "integer", "description": "Reference to debit categorization label", "example": 2 }, "created_at": { "type": "string", "format": "date-time", "description": "Debit record creation timestamp", "example": "2024-05-12T22:50:21.31979+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Debit record last update timestamp", "example": "2024-05-12T22:50:21.31979+00:00" }, "created_by_staff_id": { "type": "integer", "description": "ID of staff member who created the debit", "example": 15 }, "last_updated_by_staff_id": { "type": "integer", "description": "ID of staff member who last updated the debit", "example": 15 }, "custom_field_values": { "type": "object", "description": "Additional custom field data in JSON format", "example": { "reason": "Late payment fee", "approved_by": "manager" } }, "debitLabel": { "$ref": "#/components/schemas/DebitLabel" }, "createdByStaff": { "$ref": "#/components/schemas/StaffMember" }, "lastUpdatedByStaff": { "$ref": "#/components/schemas/StaffMember" } } }, "Invoice": { "type": "object", "description": "Invoice record with AR transaction details", "properties": { "arTranId": { "type": "integer", "description": "Associated AR transaction identifier", "example": 125890 }, "invoiceNumber": { "type": "string", "description": "Unique invoice number for client reference", "example": "INV-2024-4850" }, "dueDate": { "type": "string", "format": "date-time", "description": "Invoice payment due date", "example": "2024-04-24T05:00:00" }, "status": { "type": "string", "description": "Current invoice status", "example": "POSTED" }, "tax": { "type": "number", "format": "decimal", "description": "Tax amount charged on invoice", "example": 0 }, "interest": { "type": "number", "format": "decimal", "description": "Interest charges applied to invoice", "example": 0 }, "description": { "type": "string", "description": "Additional invoice description or notes", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "Invoice record creation timestamp", "example": "2024-05-12T22:50:20.595961+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Invoice record last update timestamp", "example": "2024-05-12T22:50:20.595961+00:00" }, "ar_tran": { "$ref": "#/components/schemas/ARTransactionBasic" } } }, "Payment": { "type": "object", "description": "Payment record with security compliance", "properties": { "id": { "type": "integer", "description": "Unique payment identifier", "example": 45201 }, "arTranId": { "type": "integer", "description": "Associated AR transaction identifier", "example": 125890 }, "paymentMethod": { "type": "string", "description": "Payment method type", "example": "CREDIT_CARD" }, "amount": { "type": "number", "format": "decimal", "description": "Payment amount", "example": 2750 }, "paymentDate": { "type": "string", "format": "date-time", "description": "Date when payment was processed", "example": "2024-03-15T14:30:22+00:00" }, "confirmationDate": { "type": "string", "format": "date-time", "description": "Date when payment was confirmed", "example": "2024-03-15T14:32:18+00:00" }, "status": { "type": "string", "description": "Current payment status", "example": "CONFIRMED" }, "processorId": { "type": "string", "description": "Payment processor identifier", "example": "stripe" }, "processorReferenceId": { "type": "string", "description": "Payment processor transaction reference", "example": "pi_3N1K2mL4uZ5v6w7x8y9z0a1b" }, "last4Digits": { "type": "string", "description": "Last 4 digits of card (PCI compliant)", "example": "4242" }, "cardType": { "type": "string", "description": "Credit card type", "example": "VISA" }, "currency": { "type": "string", "description": "Payment currency code", "example": "USD" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 789 }, "createdAt": { "type": "string", "format": "date-time", "description": "Payment record creation timestamp", "example": "2024-03-15T14:30:22.123456+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Payment record last update timestamp", "example": "2024-03-15T14:32:18.789012+00:00" }, "client": { "$ref": "#/components/schemas/ClientWithRef" }, "ar_tran": { "$ref": "#/components/schemas/ARTransactionBasic" } } }, "WIP": { "type": "object", "description": "Work in Progress record with financial tracking", "properties": { "id": { "type": "integer", "description": "Unique WIP record identifier", "example": 850321 }, "pmsRef": { "type": "string", "description": "Practice management system reference", "example": "1789456" }, "wipType": { "type": "string", "description": "Type of WIP entry", "example": "Time" }, "loggedDate": { "type": "string", "format": "date-time", "description": "Date when WIP was logged", "example": "2024-01-17T05:00:00" }, "wipValue": { "type": "number", "format": "decimal", "description": "Original WIP value recorded", "example": 1250 }, "wipValueOutstanding": { "type": "number", "format": "decimal", "description": "Outstanding WIP value yet to be billed", "example": 0 }, "billedAmount": { "type": "number", "format": "decimal", "description": "Amount that has been billed from this WIP", "example": 1225 }, "writeOffAmount": { "type": "number", "format": "decimal", "description": "Amount written off as uncollectible", "example": 25 }, "notes": { "type": "string", "description": "Additional notes or description for the WIP entry", "example": "Consultation and analysis for Q1 financial review" }, "clientId": { "type": "integer", "description": "Associated client identifier", "example": 1561 }, "jobId": { "type": "integer", "description": "Associated job identifier", "example": 2514 }, "createdAt": { "type": "string", "format": "date-time", "description": "WIP record creation timestamp", "example": "2024-05-12T23:02:33.24516+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "WIP record last update timestamp", "example": "2024-05-12T23:02:33.24516+00:00" }, "client": { "$ref": "#/components/schemas/ClientBasic" }, "job": { "$ref": "#/components/schemas/Job" } } }, "WIPAggregate": { "type": "object", "description": "WIP-specific aggregation with financial summaries", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of WIP records", "example": 84 }, "sum": { "type": "object", "properties": { "wipValue": { "type": "number", "format": "decimal", "description": "Total WIP value", "example": 24186.15 }, "billedAmount": { "type": "number", "format": "decimal", "description": "Total billed amount", "example": 19612.07 }, "wipValueOutstanding": { "type": "number", "format": "decimal", "description": "Total outstanding WIP value", "example": 125 } } } } } } }, "Contact": { "type": "object", "description": "Contact record with contact info and client relationships", "properties": { "id": { "type": "integer", "example": 1001 }, "pms_ref": { "type": "string", "example": "C-4451" }, "active": { "type": "boolean", "example": true }, "contact_info_id": { "type": "integer", "example": 7001 }, "office_id": { "type": "integer", "example": 3 }, "staff_id": { "type": "integer", "example": 53 }, "type": { "type": "string", "example": "Billing" }, "fwd_email_confirmation": { "type": "boolean", "example": false }, "contact_info": { "$ref": "#/components/schemas/ClientContactInfo" }, "contact_clients": { "type": "array", "description": "Relationships linking this contact to clients", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "example": 2180 }, "contact_id": { "type": "integer", "example": 1001 }, "pms_ref": { "type": "string", "example": "LL-9981" }, "active": { "type": "boolean", "example": true }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 2180 }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "clientRef": { "type": "string", "example": "TF-2024-789" }, "active": { "type": "boolean", "example": true } } } } } } } }, "Project": { "type": "object", "description": "Project record from vw_job with status, client and staff references", "properties": { "id": { "type": "integer", "example": 5012 }, "name": { "type": "string", "example": "Q1 Financial Review 2024" }, "startDate": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "targetEndDate": { "type": "string", "format": "date-time", "example": "2024-03-31T23:59:59Z" }, "dueDate": { "type": "string", "format": "date-time", "example": "2024-03-15T00:00:00Z" }, "targetStartDate": { "type": "string", "format": "date-time", "example": "2023-12-01T00:00:00Z" }, "pmsRef": { "type": "string", "example": "JOB-2024-115" }, "isCreatedByAiwyn": { "type": "boolean", "example": true }, "managerStaffId": { "type": "integer", "example": 102 }, "partnerStaffId": { "type": "integer", "example": 101 }, "status": { "type": "string", "example": "ACTIVE" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-05-20T12:34:56.123456+00:00" }, "sysRefs": { "type": "object" }, "jobStatus": { "type": "object", "properties": { "id": { "type": "integer", "example": 4 }, "name": { "type": "string", "example": "In Progress" }, "state": { "type": "string", "example": "ACTIVE" } } }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 2180 }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "clientRef": { "type": "string", "example": "TF-2024-789" }, "clientGroup": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Enterprise" } } } } }, "managerStaff": { "$ref": "#/components/schemas/StaffMember" }, "partnerStaff": { "$ref": "#/components/schemas/StaffMember" } } }, "StaffUserTask": { "type": "object", "description": "Staff user task from vw_my_task with task type and job info", "properties": { "id": { "type": "integer", "example": 88015 }, "taskType": { "type": "object", "properties": { "code": { "type": "string", "example": "BILLABLE" }, "id": { "type": "integer", "example": 12 }, "display": { "type": "string", "example": "Billable Work" }, "billable": { "type": "boolean", "example": true }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-05-10T09:10:11.000000+00:00" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-05-10T09:10:11.000000+00:00" }, "isManagedByAiwyn": { "type": "boolean", "example": true }, "rate_type": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Hourly" }, "createdAt": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00+00:00" } } }, "task_type_category": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Consulting" }, "description": { "type": "string", "example": "Client-facing consulting tasks" }, "associatedTaskTypes": { "type": "array", "items": { "type": "integer" }, "example": [ 11, 12, 13 ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00+00:00" } } }, "job_templates": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "example": 5 } } } } } } }, "job": { "type": "object", "description": "Project information for the task", "properties": { "id": { "type": "integer", "example": 5012 }, "name": { "type": "string", "example": "Q1 Financial Review 2024" }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 2180 }, "name": { "type": "string", "example": "TechFlow Enterprises" }, "clientRef": { "type": "string", "example": "TF-2024-789" } } } } } } }, "StaffComplete": { "type": "object", "description": "Complete staff record with department and type information", "properties": { "id": { "type": "integer", "description": "Unique staff identifier", "example": 301 }, "pmsRef": { "type": "string", "description": "Practice management system reference", "example": "2650" }, "staffRef": { "type": "string", "description": "Staff reference code or initials", "example": "JDM" }, "firstName": { "type": "string", "description": "Employee first name", "example": "Sarah" }, "lastName": { "type": "string", "description": "Employee last name", "example": "Johnson" }, "email": { "type": "string", "description": "Employee email address", "example": "sarah.johnson@company.com" }, "active": { "type": "boolean", "description": "Employee active status", "example": true }, "deptId": { "type": "integer", "description": "Department identifier", "example": 7 }, "staffTypeId": { "type": "integer", "description": "Staff type classification identifier", "example": 11 }, "createdAt": { "type": "string", "format": "date-time", "description": "Staff record creation timestamp", "example": "2024-05-12T22:42:02.719873+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Staff record last update timestamp", "example": "2024-05-12T22:42:05.487898+00:00" }, "department": { "$ref": "#/components/schemas/Department" }, "staff_type": { "$ref": "#/components/schemas/StaffType" } } }, "FilterRequest": { "allOf": [ { "$ref": "#/components/schemas/PaginationRequest" }, { "type": "object", "properties": { "where": { "type": "object", "description": "GraphQL-style boolean expression for filtering", "additionalProperties": true, "example": { "_and": [ { "active": { "_eq": true } }, { "name": { "_ilike": "%searchterm%" } } ] } }, "orderBy": { "type": "array", "description": "Array of sorting criteria", "items": { "type": "object", "additionalProperties": true }, "example": [ { "name": "asc" }, { "createdAt": "desc" } ] } } } ] }, "ClientListResponse": { "type": "object", "description": "Standard response format for client list endpoints", "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "total": { "$ref": "#/components/schemas/AggregateCount" } } }, "ARTransactionListResponse": { "type": "object", "description": "Standard response format for AR transaction endpoints", "properties": { "deid_ar_tran": { "type": "array", "items": { "$ref": "#/components/schemas/ARTransaction" } }, "deid_ar_tran_aggregate": { "$ref": "#/components/schemas/AggregateCountSum" } } }, "CreditListResponse": { "type": "object", "description": "Standard response format for credit endpoints", "properties": { "deid_credit": { "type": "array", "items": { "$ref": "#/components/schemas/Credit" } }, "deid_credit_aggregate": { "$ref": "#/components/schemas/AggregateCount" } } }, "DebitListResponse": { "type": "object", "description": "Standard response format for debit endpoints", "properties": { "deid_debit": { "type": "array", "items": { "$ref": "#/components/schemas/Debit" } }, "deid_debit_aggregate": { "$ref": "#/components/schemas/AggregateCount" } } }, "EngagementListResponse": { "type": "object", "description": "Standard response format for engagement endpoints", "properties": { "deid_engagement": { "type": "array", "items": { "$ref": "#/components/schemas/Engagement" } }, "deid_engagement_aggregate": { "$ref": "#/components/schemas/AggregateCount" } } }, "InvoiceListResponse": { "type": "object", "description": "Standard response format for invoice endpoints", "properties": { "deid_invoice": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "deid_invoice_aggregate": { "$ref": "#/components/schemas/AggregateCount" } } }, "PaymentListResponse": { "type": "object", "description": "Standard response format for payment endpoints", "properties": { "deid_payment": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "deid_payment_aggregate": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "count": { "type": "integer", "example": 15 }, "sum": { "type": "object", "properties": { "amount": { "type": "number", "format": "decimal", "description": "Total payment amount", "example": 28750 } } } } } } } } }, "StaffListResponse": { "type": "object", "description": "Standard response format for staff endpoints", "properties": { "staff": { "type": "array", "items": { "$ref": "#/components/schemas/StaffDirectoryRecord" } }, "total": { "$ref": "#/components/schemas/AggregateCount" } } }, "WIPListResponse": { "type": "object", "description": "Standard response format for WIP endpoints", "properties": { "deid_wip": { "type": "array", "items": { "$ref": "#/components/schemas/WIP" } }, "deid_wip_aggregate": { "$ref": "#/components/schemas/WIPAggregate" } } }, "TransactionType": { "type": "string", "enum": [ "Receipt", "Invoice", "Payment", "Credit", "Adjustment" ], "description": "Available AR transaction types" }, "PaymentMethod": { "type": "string", "enum": [ "CREDIT_CARD", "DEBIT_CARD", "ACH", "BANK_TRANSFER", "CHECK", "WIRE", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY" ], "description": "Available payment methods" }, "PaymentStatus": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "FAILED", "CANCELLED", "REFUNDED" ], "description": "Available payment statuses" }, "InvoiceStatus": { "type": "string", "enum": [ "PENDING", "POSTED", "PAID", "OVERDUE", "CANCELLED", "DRAFT" ], "description": "Available invoice statuses" }, "EngagementStatus": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "ON_HOLD", "EXECUTED", "CANCELLED", "PLANNED" ], "description": "Available engagement statuses" }, "WIPType": { "type": "string", "enum": [ "Time", "Expense", "Fixed_Fee", "Disbursement" ], "description": "Available WIP types" }, "SortOrder": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order options" }, "ContactListResponse": { "type": "object", "description": "Standard response format for contact endpoints", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "total": { "$ref": "#/components/schemas/AggregateCount" } } }, "ProjectListResponse": { "type": "object", "description": "Standard response format for project endpoints", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "total": { "$ref": "#/components/schemas/AggregateCount" } } }, "StaffUserTaskListResponse": { "type": "object", "description": "Standard response format for staff user task endpoints", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/StaffUserTask" } }, "total": { "$ref": "#/components/schemas/AggregateCount" } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer JWT authentication for Product API access (JWTs are issued via Aiwynโ€™s `/v1/auth/token` JWT API key exchange).\n\n**Usage:**\n```\nAuthorization: Bearer \n```\n\n**Token Requirements:**\n- JWT tokens are issued by Aiwyn (backed by Firebase), obtained by exchanging a `jwtApiKey` at `/v1/auth/token`\n- Tokens contain Hasura role-based permissions and tenant context\n- Standard expiration time: 1 hour (3600 seconds)\n- Contains both application roles and Hasura-specific claims\n\n**Token Structure:**\n```json\n{\n \"https://hasura.io/jwt/claims\": {\n \"x-hasura-allowed-roles\": [\n \"aiwynsb_SUPER_ADMIN\",\n \"aiwynsb_API_USR\", \n \"aiwynsb_API_ADMIN\",\n \"aiwynsb_RECD_R\",\n \"aiwynsb_RECD_C\",\n \"aiwynsb_CUSTYP_R\",\n \"aiwynsb_CUSTYP_C\"\n ],\n \"x-hasura-default-role\": \"aiwynsb_API_ADMIN\"\n },\n \"staffId\": 420,\n \"tenant\": \"aiwynsb\",\n \"roles\": [\"SUPER_ADMIN\", \"aiwynsb_API_ADMIN\", \"aiwynsb_RECD_C\", \"aiwynsb_CUSTYP_C\"],\n \"email\": \"user@aiwyn.ai\",\n \"authKeyId\": 11,\n \"iss\": \"https://securetoken.google.com/an-staging-302521\",\n \"aud\": \"an-staging-302521\",\n \"auth_time\": 1758777932,\n \"user_id\": \"ocGkQDCe0MgLudgrjR18h5oKuVE2\",\n \"sub\": \"ocGkQDCe0MgLudgrjR18h5oKuVE2\",\n \"iat\": 1758777932,\n \"exp\": 1758781532,\n \"email_verified\": true,\n \"firebase\": {\n \"identities\": {\n \"saml.google\": [\"user@aiwyn.ai\"],\n \"email\": [\"user@aiwyn.ai\"]\n },\n \"sign_in_provider\": \"custom\",\n \"tenant\": \"aiwynsandbox-firm-o64vu\"\n }\n}\n```\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\" \\\n https://api.yourdomain.com/v1/clients\n```\n" }, "SecurityHeaders": { "type": "object", "description": "Additional security headers that may be required or optional\ndepending on the authentication method and tenant configuration.\n", "properties": { "X-Tenant-ID": { "type": "string", "description": "Explicit tenant identifier (optional when using JWT tokens that contain tenant info)\n", "example": "aiwynsb" }, "X-Request-ID": { "type": "string", "format": "uuid", "description": "Unique request identifier for tracing and debugging\n", "example": "550e8400-e29b-41d4-a716-446655440000" }, "X-Client-Version": { "type": "string", "description": "Client application version for compatibility checking\n", "example": "1.2.3" }, "X-Forwarded-For": { "type": "string", "description": "Original client IP address (when using proxy/load balancer)\n", "example": "203.0.113.195" } } } } } }