{ "openapi": "3.0.3", "info": { "title": "COUNT Partner API", "description": "Official documentation for the COUNT Partner API — build accounting integrations with a consistent reference, guides, and tools.", "version": "2026-07-28" }, "servers": [ { "url": "https://api.getcount.com", "description": "Prod" }, { "url": "https://dev-api.getcount.com", "description": "Dev" } ], "tags": [ { "name": "Customers", "description": "Customers are the people and businesses you invoice. A customer carries its contact details, billing and shipping addresses, contacts, and tax settings." }, { "name": "Invoices", "description": "Invoices, estimates, and credit memos share the same routes, distinguished by invoiceType. Every invoice object includes a derived status field (draft, approved, sent, unpaid, partial, paid, overdue, void) alongside the raw isDraft / approved / isSent / paymentStatus flags. All references use UUIDs." }, { "name": "Credit Memos", "description": "Credit memos reduce what a customer owes. They are invoice records with invoiceType memo and use the same /partners/invoices routes as invoices and estimates. Apply approved memos to open invoices with the credit-application endpoints." }, { "name": "Recurring Invoice Templates", "description": "Recurring invoice templates define a schedule that automatically generates invoices (or estimates) in a workspace. Each template stores the invoice payload, recurrence cadence, and next run date. Credit memos cannot be recurring." }, { "name": "Bills", "description": "Bills are vendor payables — amounts your workspace owes to suppliers. Partner routes cover listing, creating, updating, approving, and deleting bills, applying vendor memos, and removing transaction payments. All references use UUIDs." }, { "name": "Transactions", "description": "Transactions are the individual money movements on a workspace account. Amounts are signed: negative for money out (expense) and positive for money in (income). All references (account, category, vendor, customer, tags) use UUIDs." }, { "name": "Chart of Accounts", "description": "The chart of accounts is the workspace general ledger. Every transaction, bill, invoice line, and journal entry line posts to an account. Accounts are organized by high-level type (Assets, Liabilities, Equity, Income, Expenses) and a numeric sub-type." }, { "name": "Vendors", "description": "Vendors are the suppliers, merchants, contractors, and contacts you pay through bills and expense transactions. A vendor holds contact details, an optional address, 1099 tax settings, and status." }, { "name": "Products & Services", "description": "Products and services are the catalog items you sell on invoices and estimates. Each record carries pricing, optional inventory tracking, income and purchase category accounts, and tax configuration." }, { "name": "Journal Entries", "description": "Journal entries are manual double-entry postings to the general ledger. Each posting has a memo, date, optional reference number, and balanced debit/credit lines that reference chart-of-accounts UUIDs." }, { "name": "Budgets", "description": "Budgets let partners create workspace financial plans with versioned cell grids. Partner responses expose budget UUIDs as `id`, strip internal numeric foreign keys, and require `accountUuid` (not numeric `accountId`) on cell update payloads." }, { "name": "Tags", "description": "Tags are workspace labels used to classify transactions, journal entries, invoices, bills, and other records. Tag groups organize related tags — each tag may belong to at most one group." }, { "name": "Webhooks", "description": "Subscribe to workspace events and receive HTTPS POST deliveries when matching records change. Each subscription covers one event type per workspace." }, { "name": "Documents", "description": "Upload, list, update, and delete files in a workspace document library. Large files use a chunked upload flow. Partner responses omit internal storage paths and download URLs." }, { "name": "People", "description": "People are workspace members — employees, contractors, and other payroll or expense-reporting contacts. Partner responses expose UUIDs as `id` and omit internal numeric foreign keys." }, { "name": "Projects", "description": "Projects group work for a customer with a status, schedule, and associated tasks. Partner responses use UUIDs; numeric `customerId` and `statusId` fields are stripped." }, { "name": "Tasks", "description": "Tasks are units of work with assignees, statuses, deadlines, and optional project links. Partner responses expose UUIDs; numeric foreign keys on the task root are stripped." }, { "name": "Time Entries", "description": "Time entries record minutes logged by a person against projects, customers, and billable services. Partner responses use UUIDs; entries in processed pay periods are read-only." }, { "name": "Expense Receipts", "description": "Expense receipts (pending receipts) capture out-of-pocket expenses before they are matched to bank transactions. Upload receipt images via multipart form data; API responses omit receiptUrl by design." }, { "name": "Connections", "description": "List and manage bank-feed connections (Plaid, Akahu, and similar). New connections require a human to complete Plaid Hosted Link in a browser." }, { "name": "Reconciliations", "description": "Start a bank reconciliation draft for an account statement period, then complete it to mark reviewed journal entries as reconciled." }, { "name": "Opening Balance", "description": "Read and publish the workspace opening (conversion) balance as of the cutover date. Total debits must equal total credits." }, { "name": "Workspace", "description": "Update workspace-level settings for the authenticated workspace. Currently supports setting the cutover date." }, { "name": "Reports", "description": "Generate trial balance, profit and loss, balance sheet, AR/AP aging, sales analytics, and customer activity reports for a workspace. All routes use POST with filters on the query string — there is no request body." }, { "name": "Workspace Stats", "description": "Aggregated CFO-style business snapshot for a workspace — cash, profitability, receivables, payables, tax obligations, and bank connections in one GET call." } ], "paths": { "/partners/customers": { "get": { "operationId": "customers_list-customers", "summary": "Returns a paginated list of customers in the workspace.", "tags": [ "Customers" ], "description": "Customers are returned with their billing/shipping addresses, contacts, taxes, and sales rep embedded. Use search, status, and ordering to narrow the results. The response includes a `filters` object echoing applied query parameters.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match across the customer name, contact name, and contact phone numbers.", "schema": { "type": "string", "example": "acme" } }, { "name": "status", "in": "query", "required": false, "description": "Filters by customer status.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort results by. Defaults to customer.", "schema": { "type": "string", "enum": [ "customer", "email", "createdAt", "updatedAt" ] } }, { "name": "orderDirection", "in": "query", "required": false, "description": "Sort direction. Defaults to ASC.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Paginated list of customers.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching customers.", "data": { "page": 1, "limit": 20, "totalRecords": 1, "totalPages": 1, "records": [ { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "active", "notes": "Preferred customer. Net-30 terms.", "paymentTerm": "net30", "taxNumber": null, "taxAutoCalculate": false, "taxExcluded": false, "contactName": "John Doe", "billingAddress": { "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12", "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "shippingAddress": null, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "phone": "+1234567890", "isPrimary": true } ], "taxes": [], "salesRep": null, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "filters": { "search": null, "status": null, "orderBy": "customer", "orderDirection": "ASC" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "customers_add-customer", "summary": "Creates a new customer in the workspace.", "tags": [ "Customers" ], "description": "Only customer (the name) is required. Addresses, contacts, and taxes can be created inline.", "responses": { "201": { "description": "Customer created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "success on creating customer", "data": { "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "active", "notes": "Preferred customer. Net-30 terms.", "paymentTerm": "net30", "taxNumber": null, "taxAutoCalculate": false, "taxExcluded": false, "contactName": "John Doe", "billingAddress": { "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12", "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "shippingAddress": null, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "phone": "+1234567890", "isPrimary": true } ], "taxes": [], "salesRep": null, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Bad request — validation failed." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "string", "description": "Customer or business name. The only required field." }, "email": { "type": "string", "description": "Primary contact email. Optional; does not need to be unique." }, "mainPhone": { "type": "string", "description": "Primary phone number. International format recommended." }, "website": { "type": "string", "description": "Website URL. Stored with an https:// prefix if the protocol is omitted." }, "notes": { "type": "string", "description": "Free-text notes. HTML is sanitized." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Customer status. Defaults to active." }, "paymentTerm": { "type": "string", "description": "Default payment term for invoices (for example net30)." }, "taxNumber": { "type": "string", "description": "Tax registration number." }, "salesRepId": { "type": "integer", "description": "Id of the workspace person to assign as sales representative." }, "taxAutoCalculate": { "type": "boolean", "description": "Auto-calculate tax from the address. Defaults to false." }, "taxExcluded": { "type": "boolean", "description": "Treat amounts as tax-exclusive. Defaults to false." }, "taxes": { "type": "array", "items": {}, "description": "Array of tax ids to apply when taxAutoCalculate is false." }, "billingAddress": { "type": "object", "description": "Billing address for the customer.", "properties": { "street": { "type": "string", "description": "Street address." }, "city": { "type": "string", "description": "City or locality." }, "state": { "type": "string", "description": "State, province, or region." }, "zipCode": { "type": "string", "description": "Postal or ZIP code." }, "country": { "type": "string", "description": "Country name or ISO code." } } }, "shippingAddress": { "type": "object", "description": "Shipping address. Same shape as billingAddress." }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Contact's first name." }, "lastName": { "type": "string", "description": "Contact's last name." }, "email": { "type": "string", "description": "Contact's email address." }, "phone": { "type": "string", "description": "Contact's phone number." }, "isPrimary": { "type": "boolean", "description": "Marks the primary contact." } } }, "description": "Contact people for this customer. The first contact sets the derived contactName." } }, "required": [ "customer" ] }, "example": { "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "active", "paymentTerm": "net30", "billingAddress": { "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "contacts": [ { "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "isPrimary": true } ] } } } } } }, "/partners/customers/{uuid}": { "get": { "operationId": "customers_get-customer", "summary": "Retrieves a single customer by its id (UUID).", "tags": [ "Customers" ], "description": "Returns the customer with its contacts and addresses embedded. Pass include=balance to also return the customer’s outstanding balance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The customer UUID as returned in responses.", "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated extras to embed. Supports balance to add the outstanding balance.", "schema": { "type": "string", "example": "balance" } } ], "responses": { "200": { "description": "The requested customer.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching customer data.", "data": { "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "active", "notes": "Preferred customer. Net-30 terms.", "paymentTerm": "net30", "taxNumber": null, "taxAutoCalculate": false, "taxExcluded": false, "contactName": "John Doe", "billingAddress": { "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12", "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "shippingAddress": null, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "phone": "+1234567890", "isPrimary": true } ], "taxes": [], "salesRep": null, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Customer not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "put": { "operationId": "customers_update-customer", "summary": "Updates an existing customer. Only the fields you send are changed.", "tags": [ "Customers" ], "description": "Send any subset of the writable fields. Fields belonging to firm-managed (system-created) customers, and internal fields such as originalClientId, are ignored.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The customer UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customer updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating a customer", "data": { "updatedCustomer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "inactive", "notes": "Preferred customer. Net-30 terms.", "paymentTerm": "net30", "taxNumber": null, "taxAutoCalculate": false, "taxExcluded": false, "contactName": "John Doe", "billingAddress": { "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12", "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "shippingAddress": null, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "phone": "+1234567890", "isPrimary": true } ], "taxes": [], "salesRep": null, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Customer not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "string", "description": "Updated customer or business name." }, "email": { "type": "string", "description": "Updated email." }, "mainPhone": { "type": "string", "description": "Updated phone number." }, "website": { "type": "string", "description": "Updated website URL." }, "notes": { "type": "string", "description": "Updated notes." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Updated status." }, "paymentTerm": { "type": "string", "description": "Updated payment term." }, "billingAddress": { "type": "object", "description": "Updated billing address." }, "shippingAddress": { "type": "object", "description": "Updated shipping address." }, "contacts": { "type": "array", "items": {}, "description": "Updated list of contacts." } } }, "example": { "mainPhone": "+1987654321", "status": "inactive" } } } } }, "delete": { "operationId": "customers_delete-customer", "summary": "Soft-deletes a customer (sets its status to inactive).", "tags": [ "Customers" ], "description": "Returns 204 No Content on success with an empty body. A customer cannot be deleted if it is linked to an invoice, project, or transaction, or if it is a firm-managed customer.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The customer UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Customer deleted successfully. No response body." }, "400": { "description": "Customer is linked to an invoice, project, or transaction, or is firm-managed." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Customer not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/customers/bulk": { "post": { "operationId": "customers_bulk-create-customers", "summary": "Creates up to 100 customers in one request with partial-success semantics.", "tags": [ "Customers" ], "description": "Each row uses the same shape as Add a customer. Rows are processed independently — one failure does not roll back others. Returns the bulk batch shape documented in Response shapes (HTTP 201). Recommended batch size ~25 for large migrations.", "responses": { "201": { "description": "Batch accepted. Check successCount and per-row results.", "content": { "application/json": { "example": { "successCount": 2, "errorCount": 0, "results": [ { "index": 0, "success": true, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "active", "notes": "Preferred customer. Net-30 terms.", "paymentTerm": "net30", "taxNumber": null, "taxAutoCalculate": false, "taxExcluded": false, "contactName": "John Doe", "billingAddress": { "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12", "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "shippingAddress": null, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "phone": "+1234567890", "isPrimary": true } ], "taxes": [], "salesRep": null, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } ] } } } }, "400": { "description": "Batch-level validation failed (empty array, over 100 rows, etc.)." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": {}, "description": "Array of customer create payloads (same fields as POST /partners/customers)." } }, "required": [ "customers" ] }, "example": { "customers": [ { "customer": "Acme Corporation", "email": "billing@acme.com" }, { "customer": "Beta LLC", "mainPhone": "+1234567890" } ] } } } } }, "patch": { "operationId": "customers_bulk-update-customers", "summary": "Updates up to 100 customers in one request with partial-success semantics.", "tags": [ "Customers" ], "description": "Each row must include `uuid` (same value as `id` from API responses) plus fields to patch. Returns the bulk batch shape documented in Response shapes (HTTP 201).", "responses": { "201": { "description": "Batch accepted. Check successCount and per-row results.", "content": { "application/json": { "example": { "successCount": 1, "errorCount": 1, "results": [ { "index": 0, "success": true, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "mainPhone": "+1234567890", "website": "https://acme.com", "status": "active", "notes": "Preferred customer. Net-30 terms.", "paymentTerm": "net30", "taxNumber": null, "taxAutoCalculate": false, "taxExcluded": false, "contactName": "John Doe", "billingAddress": { "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12", "street": "123 Main St", "city": "San Francisco", "state": "CA", "zipCode": "94102", "country": "USA" }, "shippingAddress": null, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "John", "lastName": "Doe", "email": "john@acme.com", "phone": "+1234567890", "isPrimary": true } ], "taxes": [], "salesRep": null, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } }, { "index": 1, "success": false, "error": "Customer not found" } ] } } } }, "400": { "description": "Batch-level validation failed." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": {}, "description": "Array of `{ uuid, ...fields }` update payloads." } }, "required": [ "customers" ] }, "example": { "customers": [ { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "email": "updated@acme.com" }, { "uuid": "00000000-0000-4000-8000-000000000099", "mainPhone": "+1987654321" } ] } } } } } }, "/partners/invoices": { "get": { "operationId": "credit-memo_list-credit-memos", "summary": "Returns a paginated list of credit memos in the workspace.", "tags": [ "Credit Memos" ], "description": "Pass invoiceType=memo to return only credit memos. Other filters match the Invoices API list.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "invoiceType", "in": "query", "required": true, "description": "Must be memo to list credit memos only.", "schema": { "type": "string", "enum": [ "memo" ] } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated lifecycle statuses.", "schema": { "type": "string" } }, { "name": "paymentStatus", "in": "query", "required": false, "description": "Comma-separated payment statuses.", "schema": { "type": "string" } }, { "name": "approvalStatus", "in": "query", "required": false, "description": "Filter by approval state.", "schema": { "type": "string", "enum": [ "draft", "approved" ] } }, { "name": "startDate", "in": "query", "required": false, "description": "Filter on memo date (ISO).", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": false, "description": "Filter on memo date (ISO).", "schema": { "type": "string", "format": "date" } }, { "name": "isDraft", "in": "query", "required": false, "description": "Explicit draft filter.", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of credit memos.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching invoices.", "results": 1, "totalRecords": 1, "page": 1, "limit": 50, "data": { "invoices": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "invoiceNumber": "CM-0042", "invoiceType": "memo", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "date": "2026-03-01", "dueDate": null, "currency": "USD", "status": "approved", "isDraft": false, "approved": true, "isSent": false, "paymentStatus": "unpaid", "subtotal": 500, "taxTotal": 0, "total": 500, "amountDue": 500, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "credit-memo_create-credit-memo", "summary": "Creates a credit memo for a customer.", "tags": [ "Credit Memos" ], "description": "Set invoiceType to memo. Optionally pass appliedToInvoiceUuid to link the memo to an open invoice at create time. Line item rules match invoice create. invoiceNumber is required.", "responses": { "201": { "description": "Credit memo created.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "invoiceNumber": "CM-0042", "invoiceType": "memo", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "date": "2026-03-01", "dueDate": null, "currency": "USD", "status": "draft", "isDraft": true, "approved": false, "isSent": false, "paymentStatus": "unpaid", "subtotal": 500, "taxTotal": 0, "total": 500, "amountDue": 500, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "400": { "description": "Validation failed." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Customer, product, or applied invoice not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerUuid": { "type": "string", "format": "uuid", "description": "UUID of the customer receiving the credit." }, "invoiceType": { "type": "string", "enum": [ "memo" ], "description": "Must be memo." }, "invoiceNumber": { "type": "string", "description": "Credit memo number shown to the customer." }, "date": { "type": "string", "format": "date", "description": "Memo date (ISO)." }, "appliedToInvoiceUuid": { "type": "string", "format": "uuid", "description": "UUID of an open invoice to credit at create time." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "products": { "type": "array", "items": { "type": "object", "properties": { "productUuid": { "type": "string", "format": "uuid", "description": "Product UUID from list_products. `uuid` is accepted as an alias." }, "description": { "type": "string", "description": "Line description." }, "quantity": { "type": "number", "description": "Quantity." }, "unitPrice": { "type": "number", "description": "Credit amount per unit." }, "nonTaxable": { "type": "boolean", "description": "When true, clears tax on the line." } } }, "description": "Credit line items." }, "notes": { "type": "string", "description": "Memo notes visible to the customer." }, "tagUuids": { "type": "array", "items": {}, "description": "Tag UUIDs to attach." } }, "required": [ "customerUuid", "invoiceType", "invoiceNumber", "date", "products" ] }, "example": { "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "invoiceType": "memo", "invoiceNumber": "CM-0042", "date": "2026-03-01", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "currency": "USD", "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ] } } } } } }, "/partners/invoices/{uuid}": { "get": { "operationId": "credit-memo_get-credit-memo", "summary": "Retrieves a single credit memo by its UUID.", "tags": [ "Credit Memos" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The credit memo UUID (the id field on memo objects).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested credit memo.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "invoiceNumber": "CM-0042", "invoiceType": "memo", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "date": "2026-03-01", "dueDate": null, "currency": "USD", "status": "approved", "isDraft": false, "approved": true, "isSent": false, "paymentStatus": "unpaid", "subtotal": 500, "taxTotal": 0, "total": 500, "amountDue": 500, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Credit memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "credit-memo_update-credit-memo", "summary": "Updates a credit memo. Edits to non-draft memos are field-specific and may be rejected.", "tags": [ "Credit Memos" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The credit memo UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit memo updated.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "invoiceNumber": "CM-0042", "invoiceType": "memo", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "date": "2026-03-01", "dueDate": null, "currency": "USD", "status": "approved", "isDraft": false, "approved": true, "isSent": false, "paymentStatus": "unpaid", "subtotal": 500, "taxTotal": 0, "total": 500, "amountDue": 500, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z", "notes": "Adjusted credit reason" } } } } } }, "400": { "description": "Change not allowed on approved memo." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Credit memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Updated memo date." }, "notes": { "type": "string", "description": "Updated notes." }, "products": { "type": "array", "items": {}, "description": "Replacement line items (draft memos only)." } } }, "example": { "notes": "Adjusted credit reason" } } } } }, "delete": { "operationId": "credit-memo_delete-credit-memo", "summary": "Deletes a credit memo.", "tags": [ "Credit Memos" ], "description": "Memos with applied credit or payments may be restricted — expect 400 when deletion is not allowed.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The credit memo UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit memo deleted.", "content": { "application/json": { "example": { "status": "success", "message": "Invoice deleted." } } } }, "400": { "description": "Memo cannot be deleted in its current state." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Credit memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/invoices/{uuid}/approve": { "patch": { "operationId": "credit-memo_approve-credit-memo", "summary": "Approves a draft credit memo so its balance can be applied to invoices.", "tags": [ "Credit Memos" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The credit memo UUID to approve.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit memo approved.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "invoiceNumber": "CM-0042", "invoiceType": "memo", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "date": "2026-03-01", "dueDate": null, "currency": "USD", "status": "approved", "isDraft": false, "approved": true, "isSent": false, "paymentStatus": "unpaid", "subtotal": 500, "taxTotal": 0, "total": 500, "amountDue": 500, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Credit memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skipJesOnboarding": { "type": "boolean", "description": "Skip journal-entry onboarding prompts." } } }, "example": { "skipJesOnboarding": true } } } } } }, "/partners/invoices/{uuid}/send": { "post": { "operationId": "invoices_send-invoice", "summary": "Emails the invoice to the customer. Requires a non-draft invoice with a customer and products.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invoice sent.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042", "invoiceType": "invoice", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "date": "2026-03-01", "dueDate": "2026-03-31", "currency": "USD", "status": "sent", "isDraft": false, "approved": true, "isSent": true, "paymentStatus": "unpaid", "subtotal": 1000, "taxTotal": 85, "total": 1085, "amountDue": 1085, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "nonTaxable": false } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "400": { "description": "Bad request — invoice is still a draft or missing required data." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "array", "items": {}, "description": "Override recipient email addresses." }, "message": { "type": "string", "description": "Custom message to include in the email." } } }, "example": { "to": [ "contact@acme.com" ], "message": "Thanks for your business!" } } } } } }, "/partners/invoices/{uuid}/public-link": { "get": { "operationId": "invoices_get-invoice-public-link", "summary": "Returns a shareable public link for the invoice, creating the public token if needed.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The public token and URL.", "content": { "application/json": { "example": { "status": "success", "data": { "publicToken": "pub_3fa85f64", "publicUrl": "https://app.getcount.com/public/invoice-estimate/pub_3fa85f64" } } } } }, "404": { "description": "Invoice not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/invoices/{uuid}/audit-log": { "get": { "operationId": "invoices_get-invoice-audit-log", "summary": "Returns the audit history for an invoice, estimate, or credit memo.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit log entries for the invoice.", "content": { "application/json": { "example": { "status": "success", "data": { "auditLog": [ { "action": "created", "timestamp": "2026-03-01T09:00:00.000Z", "userId": null }, { "action": "approved", "timestamp": "2026-03-01T10:00:00.000Z", "userId": null } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/invoices/{uuid}/send-history": { "get": { "operationId": "invoices_get-invoice-send-history", "summary": "Returns email send history and public-view analytics for an invoice, estimate, or credit memo.", "tags": [ "Invoices" ], "description": "Queued in-flight send stubs are excluded from the `sends` array. Rows with `deliveryStatus: \"sent\"` but no MailerSend message id are surfaced as `failed`.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Send history and public view summary.", "content": { "application/json": { "example": { "success": true, "data": { "isSent": true, "lastSendDate": "2026-03-02T14:30:00.000Z", "sendCount": 1, "sends": [ { "id": "send-uuid-001", "recipientEmail": "contact@acme.com", "sentAt": "2026-03-02T14:30:00.000Z", "deliveryStatus": "delivered", "delivered": true, "firstOpenedAt": "2026-03-02T15:00:00.000Z", "openCount": 2, "firstClickedAt": null, "clickCount": 0 } ], "publicViews": { "count": 3, "firstViewedAt": "2026-03-02T16:00:00.000Z", "lastViewedAt": "2026-03-03T09:00:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/invoices/{uuid}/attachments": { "post": { "operationId": "invoices_add-invoice-attachments", "summary": "Attaches files to an invoice by URL.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachments added.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042", "invoiceType": "invoice", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "date": "2026-03-01", "dueDate": "2026-03-31", "currency": "USD", "status": "sent", "isDraft": false, "approved": true, "isSent": true, "paymentStatus": "unpaid", "subtotal": 1000, "taxTotal": 85, "total": 1085, "amountDue": 1085, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "nonTaxable": false } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Public URL of the file." }, "title": { "type": "string", "description": "Display title for the attachment." } } }, "description": "Files to attach by URL." } }, "required": [ "attachments" ] }, "example": { "attachments": [ { "url": "https://cdn.example.com/contract.pdf", "title": "Signed contract" } ] } } } } } }, "/partners/invoices/{uuid}/attachments/upload": { "post": { "operationId": "invoices_upload-invoice-attachment", "summary": "Uploads a file attachment via multipart form data.", "tags": [ "Invoices" ], "description": "Send multipart/form-data with a `documents` field. Sign the request with an empty-object body hash.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment uploaded.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042", "invoiceType": "invoice", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "date": "2026-03-01", "dueDate": "2026-03-31", "currency": "USD", "status": "sent", "isDraft": false, "approved": true, "isSent": true, "paymentStatus": "unpaid", "subtotal": 1000, "taxTotal": 85, "total": 1085, "amountDue": 1085, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "nonTaxable": false } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "400": { "description": "Missing file or validation error." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/invoices/{uuid}/apply-multiple-credit-to-invoice": { "patch": { "operationId": "credit-memo_apply-multiple-credit-to-invoice", "summary": "Applies one or more credit memos to the target invoice.", "tags": [ "Credit Memos" ], "description": "Path is the target invoice UUID. Each creditMemos[].id is a credit memo UUID.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The target invoice UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credits applied to the invoice.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042", "invoiceType": "invoice", "amountDue": 585, "total": 1085 } } } } } }, "400": { "description": "Invalid credit amount or memo not approved." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice or credit memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditMemos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Credit memo UUID." }, "amount": { "type": "number", "description": "Amount of credit to apply." } } }, "description": "Credit memos to apply." } }, "required": [ "creditMemos" ] }, "example": { "creditMemos": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount": 500 } ] } } } } } }, "/partners/invoices/{uuid}/apply-credit-to-multiple-invoices": { "patch": { "operationId": "credit-memo_apply-credit-to-multiple-invoices", "summary": "Applies a credit memo to one or more target invoices.", "tags": [ "Credit Memos" ], "description": "Path is the credit memo UUID. Each invoices[].id is a target invoice UUID.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The credit memo UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit applied to invoices.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "invoiceNumber": "CM-0042", "invoiceType": "memo", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "appliedToInvoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "date": "2026-03-01", "dueDate": null, "currency": "USD", "status": "approved", "isDraft": false, "approved": true, "isSent": false, "paymentStatus": "paid", "subtotal": 500, "taxTotal": 0, "total": 500, "amountDue": 0, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Credit for overbilling on prior invoice", "quantity": 1, "unitPrice": 500, "nonTaxable": true } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "400": { "description": "Invalid credit amount or invoice state." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Credit memo or invoice not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Target invoice UUID." }, "amount": { "type": "number", "description": "Amount of credit to apply." } } }, "description": "Invoices to apply credit against." } }, "required": [ "invoices" ] }, "example": { "invoices": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "amount": 500 } ] } } } } } }, "/partners/invoices/{uuid}/remove-credit": { "patch": { "operationId": "credit-memo_remove-credit-from-invoice", "summary": "Unapplies a credit memo from an invoice.", "tags": [ "Credit Memos" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The invoice UUID the credit was applied to.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit removed from invoice.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042", "amountDue": 1085 } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice or credit memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memoId": { "type": "string", "format": "uuid", "description": "UUID of the credit memo to unapply." } }, "required": [ "memoId" ] }, "example": { "memoId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "/partners/invoices/{uuid}/remove-transaction": { "patch": { "operationId": "invoices_remove-invoice-transaction", "summary": "Unassigns a payment transaction from an invoice.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the invoice.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction removed from invoice.", "content": { "application/json": { "example": { "status": "success", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042", "invoiceType": "invoice", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "date": "2026-03-01", "dueDate": "2026-03-31", "currency": "USD", "status": "sent", "isDraft": false, "approved": true, "isSent": true, "paymentStatus": "unpaid", "subtotal": 1000, "taxTotal": 85, "total": 1085, "amountDue": 1085, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "nonTaxable": false } ], "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-02T11:15:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Invoice or transaction not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "UUID of the payment transaction to remove." } }, "required": [ "transactionId" ] }, "example": { "transactionId": "b7c8d9e0-f1a2-3456-bcde-678901234567" } } } } } }, "/partners/recurring-invoice-templates": { "get": { "operationId": "recurring-invoice-templates_list-recurring-invoice-templates", "summary": "Returns a paginated list of recurring invoice templates in the workspace.", "tags": [ "Recurring Invoice Templates" ], "description": "Defaults to non-draft templates. Pass isDraft=true to retrieve templates still seeded from a draft invoice, or isDraft=all for both. Results embed the customer and line items. Use search and ordering to narrow the list.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match across invoice title, summary, email, customer name, and total amount.", "schema": { "type": "string", "example": "retainer" } }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by. Defaults to nextInvoiceDate.", "schema": { "type": "string", "enum": [ "customer", "nextInvoiceDate", "createdAt", "updatedAt", "total" ] } }, { "name": "orderDirection", "in": "query", "required": false, "description": "Sort direction. Defaults to DESC.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "isDraft", "in": "query", "required": false, "description": "Draft filter: true returns only templates still seeded from a draft invoice, false (default) returns only active templates, all returns both.", "schema": { "type": "string", "enum": [ "true", "false", "all" ] } } ], "responses": { "200": { "description": "Paginated list of recurring invoice templates.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching recurring invoice templates", "data": { "result": [ { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "invoiceTitle": "Monthly consulting retainer", "summary": "Recurring monthly invoice for Acme Corporation", "email": "contact@acme.com", "currency": "USD", "subtotal": 1000, "taxTotal": 85, "total": 1085, "invoiceType": "invoice", "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "contactName": "John Doe" }, "invoiceProducts": [ { "id": "d5e6f7a8-b9c0-1234-defa-567890123456", "productServiceId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "price": 100, "nonTaxable": false } ], "createdInvoiceTemplate": { "recurrencePattern": "monthly", "recurrenceInterval": 1, "occurrenceCount": null, "remainingOccurrence": null, "recurrenceEndDate": null, "nextInvoiceDate": "2026-04-01", "inAdvanceCreationDays": 0, "creationDate": "2026-04-01", "emailCustomer": true }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalPages": 1, "totalRecords": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "recurring-invoice-templates_create-recurring-invoice-template", "summary": "Creates a draft invoice plus a recurring template with the supplied schedule.", "tags": [ "Recurring Invoice Templates" ], "description": "Same UUID payload rules as invoice create, plus required `recurrencePattern`. `invoiceType` defaults to invoice; memo is rejected, which also makes `dueDate` effectively required. `isDraft` defaults to true, so `customerUuid` is not required unless `isDraft` is set to false — resume the template to start generation.", "responses": { "201": { "description": "Template and draft invoice created.", "content": { "application/json": { "example": { "status": "success", "message": "Invoice and recurring template created", "data": { "invoice": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "invoiceNumber": "INV-1042" }, "recurringTemplate": { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "invoiceTitle": "Monthly consulting retainer", "summary": "Recurring monthly invoice for Acme Corporation", "email": "contact@acme.com", "currency": "USD", "subtotal": 1000, "taxTotal": 85, "total": 1085, "invoiceType": "invoice", "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "contactName": "John Doe" }, "invoiceProducts": [ { "id": "d5e6f7a8-b9c0-1234-defa-567890123456", "productServiceId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "price": 100, "nonTaxable": false } ], "createdInvoiceTemplate": { "recurrencePattern": "monthly", "recurrenceInterval": 1, "occurrenceCount": null, "remainingOccurrence": null, "recurrenceEndDate": null, "nextInvoiceDate": "2026-04-01", "inAdvanceCreationDays": 0, "creationDate": "2026-04-01", "emailCustomer": true }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed — missing recurrencePattern, invoiceNumber, date, or dueDate; memo invoiceType; or invalid UUID references." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerUuid": { "type": "string", "format": "uuid", "description": "UUID of the customer billed on each generated invoice. Required only when isDraft is false." }, "recurrencePattern": { "type": "string", "description": "Schedule cadence: daily, weekly, biweekly, monthly, quarterly, or yearly." }, "invoiceType": { "type": "string", "enum": [ "invoice", "estimate" ], "description": "Document type. Defaults to invoice. Must not be memo." }, "invoiceNumber": { "type": "string", "description": "Invoice number shown on the generated invoice." }, "date": { "type": "string", "format": "date", "description": "Initial invoice date (ISO)." }, "dueDate": { "type": "string", "format": "date", "description": "Due date on generated invoices (ISO). Effectively required because memo invoiceType is rejected on this endpoint." }, "currency": { "type": "string", "description": "ISO 4217 currency code. Defaults to workspace currency." }, "recurrenceInterval": { "type": "integer", "description": "Interval multiplier for the pattern. Defaults to 1." }, "recurrenceEndDate": { "type": "string", "format": "date", "description": "Optional end date for the schedule (ISO)." }, "occurrenceCount": { "type": "integer", "description": "Limit total occurrences when set." }, "inAdvanceCreationDays": { "type": "integer", "description": "Days before each scheduled date to create the invoice instance." }, "emailCustomer": { "type": "boolean", "description": "Email the customer when each invoice is generated." }, "isDraft": { "type": "boolean", "description": "When true (default), the template is paused until resumed." }, "products": { "type": "array", "items": { "type": "object", "properties": { "productUuid": { "type": "string", "format": "uuid", "description": "Product UUID from list_products. `uuid` is accepted as an alias." }, "description": { "type": "string", "description": "Line description." }, "quantity": { "type": "number", "description": "Quantity billed." }, "unitPrice": { "type": "number", "description": "Price per unit." }, "nonTaxable": { "type": "boolean", "description": "When true, clears tax on the line." } } }, "description": "Products or services on each generated invoice." }, "tagUuids": { "type": "array", "items": {}, "description": "Tag UUIDs to attach to generated invoices." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Optional project UUID." } }, "required": [ "recurrencePattern", "invoiceNumber", "date", "dueDate", "products" ] }, "example": { "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "invoiceType": "invoice", "invoiceNumber": "INV-1042", "date": "2026-03-01", "dueDate": "2026-03-31", "currency": "USD", "recurrencePattern": "monthly", "recurrenceInterval": 1, "inAdvanceCreationDays": 0, "emailCustomer": true, "isDraft": true, "products": [ { "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "nonTaxable": false } ] } } } } } }, "/partners/recurring-invoice-templates/{uuid}": { "get": { "operationId": "recurring-invoice-templates_get-recurring-invoice-template", "summary": "Retrieves a single recurring invoice template by its UUID.", "tags": [ "Recurring Invoice Templates" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The template UUID as returned in list and create responses.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested template.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching recurring invoice template", "data": { "result": { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "invoiceTitle": "Monthly consulting retainer", "summary": "Recurring monthly invoice for Acme Corporation", "email": "contact@acme.com", "currency": "USD", "subtotal": 1000, "taxTotal": 85, "total": 1085, "invoiceType": "invoice", "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "contactName": "John Doe" }, "invoiceProducts": [ { "id": "d5e6f7a8-b9c0-1234-defa-567890123456", "productServiceId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "price": 100, "nonTaxable": false } ], "createdInvoiceTemplate": { "recurrencePattern": "monthly", "recurrenceInterval": 1, "occurrenceCount": null, "remainingOccurrence": null, "recurrenceEndDate": null, "nextInvoiceDate": "2026-04-01", "inAdvanceCreationDays": 0, "creationDate": "2026-04-01", "emailCustomer": true }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Recurring invoice template not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "recurring-invoice-templates_update-recurring-invoice-template", "summary": "Updates an existing recurring invoice template. Only sent fields are changed.", "tags": [ "Recurring Invoice Templates" ], "description": "You may update invoice fields (customer, line items, totals), recurrence settings, and `nextInvoiceDate`. Changing recurrence recalculates remaining occurrences when an end date is set.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The template UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template updated successfully.", "content": { "application/json": { "example": { "status": "Success", "message": "Success on updating recurring invoice template", "data": { "result": { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "invoiceTitle": "Monthly consulting retainer", "summary": "Recurring monthly invoice for Acme Corporation", "email": "contact@acme.com", "currency": "USD", "subtotal": 1000, "taxTotal": 85, "total": 1085, "invoiceType": "invoice", "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "contactName": "John Doe" }, "invoiceProducts": [ { "id": "d5e6f7a8-b9c0-1234-defa-567890123456", "productServiceId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "price": 100, "nonTaxable": false } ], "createdInvoiceTemplate": { "recurrencePattern": "monthly", "recurrenceInterval": 2, "occurrenceCount": null, "remainingOccurrence": null, "recurrenceEndDate": null, "nextInvoiceDate": "2026-05-01", "inAdvanceCreationDays": 0, "creationDate": "2026-04-01", "emailCustomer": true }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Invalid recurrence configuration or field change." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Recurring invoice template not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nextInvoiceDate": { "type": "string", "format": "date", "description": "Next scheduled invoice date (ISO). Set to resume a paused template." }, "recurrencePattern": { "type": "string", "description": "Updated schedule cadence." }, "recurrenceInterval": { "type": "integer", "description": "Updated interval multiplier." }, "recurrenceEndDate": { "type": "string", "format": "date", "description": "Updated end date (ISO)." }, "inAdvanceCreationDays": { "type": "integer", "description": "Updated lead time for invoice creation." }, "emailCustomer": { "type": "boolean", "description": "Updated auto-email setting." }, "products": { "type": "array", "items": {}, "description": "Replacement line items (same shape as create)." } } }, "example": { "recurrencePattern": "monthly", "recurrenceInterval": 2, "nextInvoiceDate": "2026-05-01" } } } } }, "delete": { "operationId": "recurring-invoice-templates_delete-recurring-invoice-template", "summary": "Removes a recurring invoice template and stops future generation.", "tags": [ "Recurring Invoice Templates" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The template UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template removed.", "content": { "application/json": { "example": { "status": "Success", "message": "Success on removing recurring invoice template", "data": { "result": { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "isDeleted": true } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Recurring invoice template not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/recurring-invoice-templates/{uuid}/pause": { "post": { "operationId": "recurring-invoice-templates_pause-recurring-invoice-template", "summary": "Pauses generation by clearing nextInvoiceDate.", "tags": [ "Recurring Invoice Templates" ], "description": "No request body is required. The template remains in the workspace but will not generate invoices until resumed.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The template UUID to pause.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template paused.", "content": { "application/json": { "example": { "status": "success", "message": "Recurring invoice template paused", "data": { "result": { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "invoiceTitle": "Monthly consulting retainer", "summary": "Recurring monthly invoice for Acme Corporation", "email": "contact@acme.com", "currency": "USD", "subtotal": 1000, "taxTotal": 85, "total": 1085, "invoiceType": "invoice", "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "contactName": "John Doe" }, "invoiceProducts": [ { "id": "d5e6f7a8-b9c0-1234-defa-567890123456", "productServiceId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "price": 100, "nonTaxable": false } ], "createdInvoiceTemplate": { "recurrencePattern": "monthly", "recurrenceInterval": 1, "occurrenceCount": null, "remainingOccurrence": null, "recurrenceEndDate": null, "nextInvoiceDate": null, "inAdvanceCreationDays": 0, "creationDate": "2026-04-01", "emailCustomer": true }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Recurring invoice template not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/recurring-invoice-templates/{uuid}/resume": { "post": { "operationId": "recurring-invoice-templates_resume-recurring-invoice-template", "summary": "Resumes generation by setting nextInvoiceDate.", "tags": [ "Recurring Invoice Templates" ], "description": "The JSON body must include `nextInvoiceDate` (ISO date). Returns 400 when it is omitted.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The template UUID to resume.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template resumed.", "content": { "application/json": { "example": { "status": "success", "message": "Recurring invoice template resumed", "data": { "result": { "id": "c4d5e6f7-a8b9-0123-cdef-456789012345", "invoiceTitle": "Monthly consulting retainer", "summary": "Recurring monthly invoice for Acme Corporation", "email": "contact@acme.com", "currency": "USD", "subtotal": 1000, "taxTotal": 85, "total": 1085, "invoiceType": "invoice", "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation", "email": "contact@acme.com", "contactName": "John Doe" }, "invoiceProducts": [ { "id": "d5e6f7a8-b9c0-1234-defa-567890123456", "productServiceId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services", "quantity": 10, "unitPrice": 100, "price": 100, "nonTaxable": false } ], "createdInvoiceTemplate": { "recurrencePattern": "monthly", "recurrenceInterval": 1, "occurrenceCount": null, "remainingOccurrence": null, "recurrenceEndDate": null, "nextInvoiceDate": "2026-04-01", "inAdvanceCreationDays": 0, "creationDate": "2026-04-01", "emailCustomer": true }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "nextInvoiceDate is required to resume a recurring invoice template." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Recurring invoice template not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nextInvoiceDate": { "type": "string", "format": "date", "description": "The date of the next invoice to generate (ISO, YYYY-MM-DD)." } }, "required": [ "nextInvoiceDate" ] }, "example": { "nextInvoiceDate": "2026-04-01" } } } } } }, "/partners/bills": { "get": { "operationId": "bills_list-bills", "summary": "Returns a paginated list of bills and vendor memos in the workspace.", "tags": [ "Bills" ], "description": "Each row exposes id as the bill UUID for detail and payment routes. Default limit is 50.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "billType", "in": "query", "required": false, "description": "Filter by document type.", "schema": { "type": "string", "enum": [ "bill", "vendor_memo" ] } }, { "name": "approvalStatus", "in": "query", "required": false, "description": "Filter by approval state.", "schema": { "type": "string", "enum": [ "draft", "approved" ] } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated approval and payment status tokens (for example draft,approved,paid).", "schema": { "type": "string", "example": "approved,unpaid" } }, { "name": "vendorUuids", "in": "query", "required": false, "description": "Comma-separated vendor UUIDs from the Vendors API.", "schema": { "type": "string", "example": "f1a2b3c4-d5e6-7890-abcd-ef1234567890" } }, { "name": "projectUuids", "in": "query", "required": false, "description": "Comma-separated project UUIDs.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Filter by ISO 4217 currency code.", "schema": { "type": "string", "example": "USD" } }, { "name": "search", "in": "query", "required": false, "description": "Substring match against bill number or vendor name.", "schema": { "type": "string", "example": "office" } }, { "name": "startDate", "in": "query", "required": false, "description": "Bill date range start (ISO, inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Bill date range end (ISO, inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "startDueDate", "in": "query", "required": false, "description": "Due date range start (ISO, inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "endDueDate", "in": "query", "required": false, "description": "Due date range end (ISO, inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "amount", "in": "query", "required": false, "description": "Filter by bill total. Pair with amountOperator.", "schema": { "type": "number", "example": 100 } }, { "name": "amountOperator", "in": "query", "required": false, "description": "Comparison operator for amount filter.", "schema": { "type": "string", "enum": [ "eq", "gt", "gte", "lt", "lte" ] } }, { "name": "orderBy", "in": "query", "required": false, "description": "Sort field (for example id, date, dueDate, vendor, status). Defaults to id.", "schema": { "type": "string" } }, { "name": "orderDirection", "in": "query", "required": false, "description": "Sort direction. Defaults to DESC.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "Paginated list of bills.", "content": { "application/json": { "example": { "results": 1, "page": 1, "limit": 50, "totalRecords": 1, "filters": { "search": null, "status": null }, "bills": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1042", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-02-15", "currency": "USD", "approvalStatus": "approved", "status": "unpaid", "total": 250, "paidAmount": 0, "amountDue": 250, "notes": "Office supplies for Q1", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "bills_create-bill", "summary": "Creates a new vendor bill (draft by default, or approved for migrations).", "tags": [ "Bills" ], "description": "Required: exactly one of vendorUuid OR inline vendor object, date, dueDate, and lineItems with categoryAccountUuid, quantity, and price. Optional approvalStatus (draft | approved). Inline vendors are echoed on the response as _partnerInlineCreated.", "responses": { "201": { "description": "Bill created in draft.", "content": { "application/json": { "example": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1043", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-02-15", "currency": "USD", "approvalStatus": "draft", "status": "draft", "total": 250, "paidAmount": 0, "amountDue": 250, "notes": "Office supplies for Q1", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "400": { "description": "Validation failed — missing required fields or invalid UUID references." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorUuid": { "type": "string", "format": "uuid", "description": "Existing vendor UUID from the Vendors API. Mutually exclusive with vendor." }, "vendor": { "type": "object", "description": "Inline vendor to create when vendorUuid is omitted.", "properties": { "name": { "type": "string", "description": "Vendor display name (or use vendor field alias)." }, "email": { "type": "string", "description": "Optional vendor email." } } }, "date": { "type": "string", "format": "date", "description": "Bill date (ISO, YYYY-MM-DD)." }, "dueDate": { "type": "string", "format": "date", "description": "Due date (ISO, YYYY-MM-DD)." }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Expense account UUID from Chart of Accounts." }, "description": { "type": "string", "description": "Line description." }, "quantity": { "type": "number", "description": "Quantity." }, "price": { "type": "number", "description": "Unit price." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Optional project UUID on the line." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Optional customer UUID for billable expenses." } } }, "description": "Expense lines on the bill." }, "billNumber": { "type": "string", "description": "Custom bill number. Auto-assigned when omitted." }, "purchaseOrderNumber": { "type": "string", "description": "Purchase order reference." }, "notes": { "type": "string", "description": "Free-text notes." }, "currency": { "type": "string", "description": "ISO 4217 currency. Defaults to workspace currency." }, "tagUuids": { "type": "array", "items": {}, "description": "Tag UUIDs from the Tags API." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Bill-level project UUID." }, "approvalStatus": { "type": "string", "enum": [ "draft", "approved" ], "description": "Draft (default) or approved — approved posts A/P journals immediately (migration use case)." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Public file URL." }, "title": { "type": "string", "description": "Display title." } } }, "description": "Attachments by public URL." } }, "required": [ "date", "dueDate", "lineItems" ] }, "example": { "vendorUuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "date": "2026-01-15", "dueDate": "2026-02-15", "lineItems": [ { "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "description": "Office supplies", "quantity": 1, "price": 250 } ], "notes": "Q1 office supplies" } } } } } }, "/partners/bills/{uuid}": { "get": { "operationId": "bills_get-bill", "summary": "Retrieves a single bill by its UUID.", "tags": [ "Bills" ], "description": "Returns line items, vendor, transactions (payments), and applied vendor memos. Soft-deleted bills may still be returned — check isDeleted.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The bill UUID from list responses.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested bill.", "content": { "application/json": { "example": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1042", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-02-15", "currency": "USD", "approvalStatus": "approved", "status": "unpaid", "total": 250, "paidAmount": 0, "amountDue": 250, "notes": "Office supplies for Q1", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Bill not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "bills_update-bill", "summary": "Updates a bill. Only the fields you send are changed.", "tags": [ "Bills" ], "description": "Same UUID field names as create. Providing lineItems replaces all lines. Approved or paid bills restrict which fields can change.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The bill UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bill updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Bill updated successfully", "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1042", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-03-01", "currency": "USD", "approvalStatus": "approved", "status": "unpaid", "total": 250, "paidAmount": 0, "amountDue": 250, "notes": "Extended payment terms", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } }, "400": { "description": "Change not allowed on approved or paid bill." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Bill not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorUuid": { "type": "string", "format": "uuid", "description": "Updated vendor UUID." }, "date": { "type": "string", "format": "date", "description": "Updated bill date." }, "dueDate": { "type": "string", "format": "date", "description": "Updated due date." }, "billNumber": { "type": "string", "description": "Updated bill number." }, "purchaseOrderNumber": { "type": "string", "description": "Updated PO number." }, "notes": { "type": "string", "description": "Updated notes." }, "currency": { "type": "string", "description": "Updated currency code." }, "lineItems": { "type": "array", "items": {}, "description": "Replacement line items (same shape as create)." }, "tagUuids": { "type": "array", "items": {}, "description": "Replacement tag UUID list." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Updated project UUID." } } }, "example": { "dueDate": "2026-03-01", "notes": "Extended payment terms" } } } } }, "delete": { "operationId": "bills_delete-bill", "summary": "Soft-deletes a draft bill.", "tags": [ "Bills" ], "description": "Bills with paidAmount > 0 cannot be deleted. Unassign payments first.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The bill UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bill deleted.", "content": { "application/json": { "example": { "status": "success", "message": "Bill deleted successfully", "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "isDeleted": true } } } } }, "400": { "description": "Bill has payments applied and cannot be deleted." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Bill not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/bills/{uuid}/approve": { "post": { "operationId": "bills_approve-bill", "summary": "Approves a draft bill and posts journal entries.", "tags": [ "Bills" ], "description": "Makes the bill eligible for transaction payment and vendor memo application. Returns 400 if already approved or line items are missing.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The bill UUID to approve.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bill approved.", "content": { "application/json": { "example": { "status": "success", "message": "Bill approved", "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1042", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-02-15", "currency": "USD", "approvalStatus": "approved", "status": "unpaid", "total": 250, "paidAmount": 0, "amountDue": 250, "notes": "Office supplies for Q1", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } }, "400": { "description": "Bill is already approved or has no line items." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Bill not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/bills/{uuid}/apply-vendor-memos": { "post": { "operationId": "bills_apply-vendor-memos-to-bill", "summary": "Applies one or more vendor credit memos toward an approved bill.", "tags": [ "Bills" ], "description": "Target bill must be approved with amountDue > 0. Each memo id is a vendor_memo UUID from list bills with billType=vendor_memo. Memos must belong to the same vendor.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The target bill UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vendor memos applied.", "content": { "application/json": { "example": { "status": "success", "message": "Vendor memos applied to bill", "data": { "paidbill": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1042", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-02-15", "currency": "USD", "approvalStatus": "approved", "status": "unpaid", "total": 250, "paidAmount": 100, "amountDue": 150, "notes": "Office supplies for Q1", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [ { "id": "e3f4a5b6-c7d8-9012-efab-345678901234", "amount": 100 } ], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Bill not approved, insufficient memo balance, or vendor mismatch." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Bill or vendor memo not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memosBills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Vendor memo bill UUID." }, "amount": { "type": "number", "description": "Portion of memo balance to apply. Must be > 0." } } }, "description": "Vendor memos to apply." } }, "required": [ "memosBills" ] }, "example": { "memosBills": [ { "id": "e3f4a5b6-c7d8-9012-efab-345678901234", "amount": 100 } ] } } } } } }, "/partners/bills/{uuid}/unassign-transaction": { "post": { "operationId": "bills_unassign-bill-transaction", "summary": "Removes a previously applied expense transaction payment from a bill.", "tags": [ "Bills" ], "description": "Restores the bill open balance and unlinks the transaction from accounts payable. transactionId is the transaction UUID.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The bill UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction unassigned from bill.", "content": { "application/json": { "example": { "status": "success", "message": "Transaction unassigned from bill", "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "billNumber": "BILL-1042", "billType": "bill", "date": "2026-01-15", "dueDate": "2026-02-15", "currency": "USD", "approvalStatus": "approved", "status": "unpaid", "total": 250, "paidAmount": 0, "amountDue": 250, "notes": "Office supplies for Q1", "purchaseOrderNumber": null, "isDeleted": false, "vendor": { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Office Depot", "email": "ap@officedepot.example" }, "lineItems": [ { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "description": "Office supplies", "quantity": 1, "price": 250, "total": 250, "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "transactions": [], "appliedVendorMemos": [], "tagUuids": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Bill or transaction not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "UUID of the payment transaction to remove." }, "withCaution": { "type": "boolean", "description": "When true, allows unassign in edge reconciliation cases." } }, "required": [ "transactionId" ] }, "example": { "transactionId": "b7c8d9e0-f1a2-3456-bcde-678901234567", "withCaution": false } } } } } }, "/partners/transactions": { "get": { "operationId": "transactions_list-transactions", "summary": "Returns a paginated list of transactions, newest first.", "tags": [ "Transactions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number. First page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page. Maximum 100.", "schema": { "type": "integer", "example": 50 } }, { "name": "startDate", "in": "query", "required": false, "description": "Filter on postedDate (ISO, inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Filter on postedDate (ISO, inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "accUuid", "in": "query", "required": false, "description": "Filter by bank/cash account UUID (alias: accountUuid).", "schema": { "type": "string", "format": "uuid" } }, { "name": "categoryAccountUuid", "in": "query", "required": false, "description": "Filter by category account UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "vendorUuid", "in": "query", "required": false, "description": "Filter by vendor UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "customerUuid", "in": "query", "required": false, "description": "Filter by customer UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectUuid", "in": "query", "required": false, "description": "Filter by project UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "tagUuids", "in": "query", "required": false, "description": "Comma-separated tag UUIDs or array of UUIDs.", "schema": { "type": "string" } }, { "name": "transactionTypes", "in": "query", "required": false, "description": "Filter by type.", "schema": { "type": "string", "enum": [ "Expense", "Income", "Transfer", "Journal Entry" ] } }, { "name": "type", "in": "query", "required": false, "description": "Alias for transactionTypes — use one or the other.", "schema": { "type": "string", "enum": [ "Expense", "Income", "Transfer", "Journal Entry" ] } }, { "name": "reviewed", "in": "query", "required": false, "description": "Filter by review state (true/false or \"true\"/\"false\").", "schema": { "type": "boolean" } }, { "name": "reconciled", "in": "query", "required": false, "description": "Filter by reconciliation state.", "schema": { "type": "boolean" } }, { "name": "pending", "in": "query", "required": false, "description": "Filter by pending state.", "schema": { "type": "boolean" } }, { "name": "excluded", "in": "query", "required": false, "description": "Filter by excluded state.", "schema": { "type": "boolean" } }, { "name": "currency", "in": "query", "required": false, "description": "ISO 4217 currency code — match the target bill or invoice currency.", "schema": { "type": "string" } }, { "name": "forAttachment", "in": "query", "required": false, "description": "Bill/invoice picker search mode. Excludes original_amount from amount search.", "schema": { "type": "boolean" } }, { "name": "status", "in": "query", "required": false, "description": "Repeatable status filter tokens.", "schema": { "type": "string", "enum": [ "notAttachedBill", "notAttachedInvoice", "pending", "excluded", "reviewed", "reconciled", "completed", "included" ] } }, { "name": "transactionLevel", "in": "query", "required": false, "description": "Split row mode.", "schema": { "type": "string", "enum": [ "split", "splitParent" ] } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search across description and notes.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of transactions.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching transactions.", "results": 1, "totalRecords": 1, "page": 1, "limit": 50, "data": { "transactions": [ { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } ] } } } } }, "401": { "description": "Unauthorized — authentication failed." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "transactions_create-transaction", "summary": "Records a new transaction on an account.", "tags": [ "Transactions" ], "responses": { "201": { "description": "Transaction created successfully.", "content": { "application/json": { "example": { "status": "success", "data": { "transaction": { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } } } } } }, "400": { "description": "Bad request — validation failed." }, "404": { "description": "Referenced account, category, or vendor not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accUuid": { "type": "string", "format": "uuid", "description": "Bank/cash account UUID from list accounts." }, "amount": { "type": "number", "description": "Positive decimal — server applies sign by transaction type." }, "postedDate": { "type": "string", "format": "date", "description": "Date the transaction posted (YYYY-MM-DD). Alias: date." }, "description": { "type": "string", "description": "Short description of the transaction." }, "type": { "type": "string", "enum": [ "Expense", "Income", "Transfer", "Journal Entry" ], "description": "Transaction type." }, "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Category account UUID — set at creation." }, "vendorUuid": { "type": "string", "format": "uuid", "description": "Vendor UUID for expenses." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Customer UUID when applicable." }, "tagUuids": { "type": "array", "items": {}, "description": "Array of tag UUIDs to attach." }, "notes": { "type": "string", "description": "Free-text notes." } }, "required": [ "accUuid", "amount", "postedDate" ] }, "example": { "accUuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "description": "Office supplies from Amazon", "amount": 150, "type": "Expense", "postedDate": "2026-03-13", "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorUuid": "d4e5f6a7-b8c9-0123-defa-234567890123", "notes": "Q1 office supplies" } } } } } }, "/partners/transactions/{uuid}": { "get": { "operationId": "transactions_get-transaction", "summary": "Retrieves a single transaction by its UUID.", "tags": [ "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the transaction.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested transaction.", "content": { "application/json": { "example": { "status": "success", "data": { "transaction": { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } } } } } }, "404": { "description": "Transaction not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "transactions_update-transaction", "summary": "Updates fields on an existing transaction.", "tags": [ "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the transaction.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction updated.", "content": { "application/json": { "example": { "status": "success", "data": { "transaction": { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": true, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } } } } } }, "404": { "description": "Transaction not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Updated description." }, "notes": { "type": "string", "description": "Updated notes." }, "reviewed": { "type": "boolean", "description": "Mark as reviewed or unreviewed." } } }, "example": { "reviewed": true, "notes": "Reconciled against statement" } } } } }, "delete": { "operationId": "transactions_delete-transaction", "summary": "Deletes a transaction from the workspace.", "tags": [ "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the transaction.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction deleted.", "content": { "application/json": { "example": { "status": "success", "message": "Transaction deleted." } } } }, "404": { "description": "Transaction not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/transactions/bulk": { "post": { "operationId": "transactions_bulk-create-transactions", "summary": "Creates many transactions in a single request.", "tags": [ "Transactions" ], "responses": { "201": { "description": "Transactions created.", "content": { "application/json": { "example": { "status": "success", "data": { "created": 2 } } } } }, "400": { "description": "Bad request — one or more transactions failed validation." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": {}, "description": "Array of transaction objects, each using the same shape as Create a transaction." } }, "required": [ "transactions" ] }, "example": { "transactions": [ { "type": "EXPENSE", "description": "Domain renewal", "amount": -24, "postedDate": "2026-03-10", "accountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, { "type": "INCOME", "description": "Consulting payment", "amount": 1500, "postedDate": "2026-03-12", "accountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } ] } } } } } }, "/partners/transactions/{uuid}/change-category": { "patch": { "operationId": "transactions_change-transaction-category", "summary": "Re-categorizes a transaction to a different chart-of-accounts category.", "tags": [ "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the transaction.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Category updated.", "content": { "application/json": { "example": { "status": "success", "data": { "transaction": { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } } } } } }, "404": { "description": "Transaction or category not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categoryAccountId": { "type": "string", "format": "uuid", "description": "UUID of the new category account." } }, "required": [ "categoryAccountId" ] }, "example": { "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012" } } } } } }, "/partners/transactions/change-category-bulk": { "patch": { "operationId": "transactions_bulk-change-transaction-category", "summary": "Categorizes or uncategorizes up to 100 existing transactions in one call.", "tags": [ "Transactions" ], "description": "Per-row partial success: unresolvable UUIDs or ineligible rows (reviewed, reconciled, pending, attached to bill/invoice/transfer/deposit) appear in `failures` instead of failing the whole batch. Prefer `categoryAccountUuid` (or null to uncategorize). Liabilities physical accounts may create linked transfers; bank/cash Assets physical accounts still return 400 in bulk.", "responses": { "200": { "description": "Bulk category change processed.", "content": { "application/json": { "example": { "status": "success", "message": "Bulk category change processed.", "data": { "successCount": 1, "failedCount": 0, "failures": [], "updatedTransactions": [ { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } ] } } } } }, "400": { "description": "Empty or oversized transactionUuids array." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Category account UUID from list accounts, or null to uncategorize." }, "transactionUuids": { "type": "array", "items": {}, "description": "Non-empty array of transaction UUIDs (max 100)." } }, "required": [ "transactionUuids" ] }, "example": { "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "transactionUuids": [ "b7c8d9e0-f1a2-3456-bcde-678901234567", "b7c8d9e0-f1a2-3456-bcde-678901234568" ] } } } } } }, "/partners/transactions/exclude-bulk": { "patch": { "operationId": "transactions_bulk-exclude-transactions", "summary": "Excludes or un-excludes transactions by UUID list or postedDate range.", "tags": [ "Transactions" ], "description": "Pass either `{ transactionUuids, excluded }` or `{ startDate, endDate, excluded }` — not both. Date-range mode rejects with 400 if more than 100 transactions match. Excluding hides a row from the ledger without deleting it. Same per-row eligibility guards as single-row exclude (unreviewed, unreconciled, not pending, not attached).", "responses": { "200": { "description": "Bulk exclude processed with per-row failures for skipped rows.", "content": { "application/json": { "example": { "status": "success", "data": { "successCount": 1, "failedCount": 0, "failures": [] } } } } }, "400": { "description": "Invalid body — both modes, neither mode, bad dates, or more than 100 matches." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "excluded": { "type": "boolean", "description": "true to exclude, false to un-exclude." }, "transactionUuids": { "type": "array", "items": {}, "description": "UUID mode: non-empty array of transaction UUIDs (max 100). Mutually exclusive with date range." }, "startDate": { "type": "string", "format": "date", "description": "Date-range mode: inclusive postedDate start (YYYY-MM-DD). Requires endDate." }, "endDate": { "type": "string", "format": "date", "description": "Date-range mode: inclusive postedDate end (YYYY-MM-DD). Requires startDate." } }, "required": [ "excluded" ] }, "example": { "excluded": true, "transactionUuids": [ "b7c8d9e0-f1a2-3456-bcde-678901234567" ] } } } } } }, "/partners/transactions/{uuid}/assign-to-bills-invoices": { "post": { "operationId": "transactions_assign-transaction-to-bills-invoices", "summary": "Applies a transaction as payment against one or more bills or invoices.", "tags": [ "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the transaction (the payment).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction assigned.", "content": { "application/json": { "example": { "status": "success", "message": "Transaction assigned." } } } }, "400": { "description": "Bad request — assignment amount exceeds the transaction or target balance." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "matchingType": { "type": "string", "enum": [ "bill", "invoice" ], "description": "Whether to apply against bills or invoices." }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of the bill or invoice." }, "paymentAmount": { "type": "number", "description": "Amount of this transaction to apply to the target." } } }, "description": "Targets to apply the transaction against." }, "withCaution": { "type": "boolean", "description": "When true, skips some reconciliation guards. Use sparingly." } }, "required": [ "matchingType", "records" ] }, "example": { "matchingType": "invoice", "records": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "paymentAmount": 150 } ], "withCaution": false } } } } } }, "/partners/transactions/{uuid}/split": { "put": { "operationId": "transactions_split-transaction", "summary": "Splits a transaction into a parent row and child rows before bill or invoice assignment.", "tags": [ "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The UUID of the transaction to split.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction split. Returns parent and transactionToAssign rows with UUID ids.", "content": { "application/json": { "example": { "parent": { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" }, "transactionToAssign": { "id": "b7c8d9e0-f1a2-3456-bcde-678901234567", "type": "EXPENSE", "description": "Office supplies from Amazon", "amount": -150, "currency": "USD", "postedDate": "2026-03-01", "authorizedDate": "2026-03-01", "notes": "Q1 office supplies", "paymentChannel": "online", "reviewed": false, "excluded": false, "pending": false, "split": false, "accountId": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "vendorId": "d4e5f6a7-b8c9-0123-defa-234567890123", "customerId": null, "billId": null, "invoiceId": null, "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" } ], "createdAt": "2026-03-13T08:30:00.000Z", "updatedAt": "2026-03-13T08:30:00.000Z" } } } } }, "400": { "description": "Bad request — transfer/deposit splits, reviewed/pending guards, or invalid amounts." }, "404": { "description": "Transaction or category account not found." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "forAttachment": { "type": "boolean", "description": "When true, matches the COUNT bill/invoice attachment split flow." }, "splitASplit": { "type": "boolean", "description": "When true, further splits an existing split child row." }, "withCaution": { "type": "boolean", "description": "Required to split reconciled transactions." }, "parent": { "type": "object", "description": "Parent split row. Use categoryAccountUuid from chart of accounts.", "properties": { "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Category account UUID for the parent portion." }, "amount": { "type": "number", "description": "Signed amount for the parent portion." }, "assignThis": { "type": "boolean", "description": "When true, this row is the one to assign to the bill or invoice." } } }, "splits": { "type": "array", "items": { "type": "object", "properties": { "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Category account UUID for the child portion." }, "amount": { "type": "number", "description": "Signed amount for the child portion." } } }, "description": "Child split rows." } } }, "example": { "forAttachment": true, "parent": { "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "amount": -100, "assignThis": true }, "splits": [ { "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "amount": -50 } ] } } } } } }, "/partners/chart-of-accounts": { "get": { "operationId": "chart-of-accounts_list-chart-of-accounts", "summary": "Returns the workspace chart of accounts with optional filters.", "tags": [ "Chart of Accounts" ], "description": "Accounts are returned with nested `subType` and `institution` shapes. Use boolean-string query flags such as `includeBalances` or `includeHiddenAccounts` to control optional fields.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by high-level account type. Case-sensitive plural values only.", "schema": { "type": "string", "enum": [ "Assets", "Liabilities", "Equity", "Income", "Expenses" ] } }, { "name": "subTypeId", "in": "query", "required": false, "description": "Filter by numeric AccountSubType id.", "schema": { "type": "integer", "example": 1 } }, { "name": "search", "in": "query", "required": false, "description": "Partial match against account name or account number.", "schema": { "type": "string", "example": "bank" } }, { "name": "inactive", "in": "query", "required": false, "description": "When `\"true\"`, include inactive accounts.", "schema": { "type": "string", "example": "false" } }, { "name": "includeBalances", "in": "query", "required": false, "description": "When `\"true\"`, include `systemBalance` on each account and sub-account, plus `providerBalances` and `reconcileBalances` on top-level rows only.", "schema": { "type": "string", "example": "true" } }, { "name": "includeHidden", "in": "query", "required": false, "description": "When `\"true\"`, include hidden accounts.", "schema": { "type": "string", "example": "false" } }, { "name": "includeHiddenAccounts", "in": "query", "required": false, "description": "Alias for including hidden accounts.", "schema": { "type": "string", "example": "false" } }, { "name": "onlyCategoryAccounts", "in": "query", "required": false, "description": "When `\"true\"`, restrict to category-style accounts used for coding transactions.", "schema": { "type": "string", "example": "true" } }, { "name": "includeDeleteMeta", "in": "query", "required": false, "description": "When `\"true\"`, include `canDelete` and `deleteBlockedReason` on each row so integrations can tell whether delete will succeed.", "schema": { "type": "string", "example": "true" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Chart of accounts rows.", "content": { "application/json": { "example": { "page": 1, "limit": 50, "totalRecords": 1, "filters": { "type": null, "subTypeId": null, "search": null }, "accounts": [ { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Operating Bank Account", "accountNumber": "1000", "type": "Assets", "status": "active", "currency": "USD", "description": "Primary business checking account", "color": "#4A90D9", "subType": { "id": 1, "type": "Assets", "name": "Bank", "anchorTier": null }, "institution": { "name": "Chase", "logoUrl": null }, "subAccounts": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } }, "400": { "description": "Invalid query parameters (for example malformed `type` or `subTypeId`)." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "chart-of-accounts_create-account", "summary": "Creates a new chart-of-accounts entry.", "tags": [ "Chart of Accounts" ], "description": "Requires `name` and `subTypeId`. The high-level `type` is derived server-side from `subTypeId` — do not send `type`. For New Zealand workspaces, `taxes` (numeric tax ids) may be required.", "responses": { "201": { "description": "Account created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating account.", "data": { "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Operating Bank Account", "accountNumber": "1000", "type": "Assets", "status": "active", "currency": "USD", "description": "Primary business checking account", "color": "#4A90D9", "subType": { "id": 1, "type": "Assets", "name": "Bank", "anchorTier": null }, "institution": { "name": "Chase", "logoUrl": null }, "subAccounts": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed — missing name/subTypeId or invalid sub-type." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the account." }, "subTypeId": { "type": "integer", "description": "Numeric AccountSubType id from an existing account in the target bucket (`subType.id` on list rows)." }, "accountNumber": { "type": "string", "description": "Optional account number or code." }, "currency": { "type": "string", "description": "ISO 4217 currency. Defaults to the workspace currency." }, "description": { "type": "string", "description": "Free-text description." }, "color": { "type": "string", "description": "Hex color for UI display." }, "parentAccountId": { "type": "integer", "description": "Numeric id of the parent account when creating a sub-account." }, "institutionId": { "type": "integer", "description": "Institution id for connected feed accounts." }, "taxes": { "type": "array", "items": {}, "description": "Array of numeric tax ids (required for NZ workspaces)." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Account status. Defaults to active." } }, "required": [ "name", "subTypeId" ] }, "example": { "name": "Petty Cash", "subTypeId": 1, "accountNumber": "1010", "currency": "USD", "status": "active" } } } } } }, "/partners/account-sub-types": { "get": { "operationId": "chart-of-accounts_list-account-sub-types", "summary": "Returns the catalog of account sub-types for the workspace country.", "tags": [ "Chart of Accounts" ], "description": "Sub-type ids are global integers (not UUIDs). Pass the chosen `id` as `subTypeId` when creating a chart-of-accounts entry. Optional `type` filter accepts Assets, Liabilities, Equity, Income, or Expenses.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by high-level account type. Case-sensitive plural values only.", "schema": { "type": "string", "enum": [ "Assets", "Liabilities", "Equity", "Income", "Expenses" ] } } ], "responses": { "200": { "description": "Array of account sub-type rows.", "content": { "application/json": { "example": [ { "id": 1, "type": "Assets", "name": "Bank", "anchorTier": null, "description": "Cash and bank accounts" }, { "id": 2, "type": "Assets", "name": "Accounts Receivable", "anchorTier": null, "description": "Amounts owed by customers" } ] } } }, "400": { "description": "Invalid `type` query parameter." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/chart-of-accounts/{uuid}": { "patch": { "operationId": "chart-of-accounts_update-account", "summary": "Updates an existing account. Only the fields you send are changed.", "tags": [ "Chart of Accounts" ], "description": "Editable fields include name, accountNumber, description, color, status, subTypeId (same high-level type only), and parentAccountId. Pass `isChildAccount: false` to detach from a parent. An empty body returns 400. Partner-created accounts remain editable until system-mapped or used in postings; system accounts may reject protected fields with 403.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The account UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating account.", "data": { "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Operating Bank Account", "accountNumber": "1000", "type": "Assets", "status": "active", "currency": "USD", "description": "Primary business checking account", "color": "#4A90D9", "subType": { "id": 1, "type": "Assets", "name": "Bank", "anchorTier": null }, "institution": { "name": "Chase", "logoUrl": null }, "subAccounts": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Empty body or invalid field combination." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Account not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated display name." }, "accountNumber": { "type": "string", "description": "Updated account number." }, "description": { "type": "string", "description": "Updated description." }, "color": { "type": "string", "description": "Updated hex color." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Updated status." }, "subTypeId": { "type": "integer", "description": "Updated sub-type id (must stay in the same high-level type)." }, "parentAccountId": { "type": "integer", "description": "Parent account id to nest under, or omit to leave unchanged." }, "isChildAccount": { "type": "boolean", "description": "Set to false to detach from the current parent." }, "connectionSyncEnabled": { "type": "boolean", "description": "Toggle feed sync on connected accounts only." } } }, "example": { "name": "Operating Bank Account — Primary", "status": "active" } } } } }, "delete": { "operationId": "chart-of-accounts_delete-account", "summary": "Deletes a chart-of-accounts entry by UUID.", "tags": [ "Chart of Accounts" ], "description": "Partner-created accounts are deletable until they have journal entries, sub-accounts, invoice products, or payroll mappings. If delete fails because of posted activity, deactivate the account with PATCH instead. Use GET with `includeDeleteMeta=true` to read `canDelete` and `deleteBlockedReason` before calling delete.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The account UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account deleted successfully." }, "400": { "description": "Account cannot be deleted due to linked activity." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Account not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/chart-of-accounts/bulk": { "post": { "operationId": "chart-of-accounts_bulk-create-accounts", "summary": "Creates up to 100 chart-of-accounts entries in one request with partial-success semantics.", "tags": [ "Chart of Accounts" ], "description": "Each row uses the same shape as Create account. Rows are processed independently — one failure does not roll back others. Returns the bulk batch shape documented in Response shapes (HTTP 201). Recommended batch size ~25 for migrations. Complete the chart of accounts before importing bills or transactions.", "responses": { "201": { "description": "Batch accepted. Check successCount and per-row results.", "content": { "application/json": { "example": { "successCount": 2, "errorCount": 0, "results": [ { "index": 0, "success": true, "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Operating Bank Account", "accountNumber": "1000", "type": "Assets", "status": "active", "currency": "USD", "description": "Primary business checking account", "color": "#4A90D9", "subType": { "id": 1, "type": "Assets", "name": "Bank", "anchorTier": null }, "institution": { "name": "Chase", "logoUrl": null }, "subAccounts": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } ] } } } }, "400": { "description": "Batch-level validation failed (empty array, over 100 rows, etc.)." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": {}, "description": "Array of account create payloads (same fields as POST /partners/chart-of-accounts)." } }, "required": [ "accounts" ] }, "example": { "accounts": [ { "name": "Office Supplies", "subTypeId": 42, "accountNumber": "6100" }, { "name": "Software Subscriptions", "subTypeId": 42, "accountNumber": "6200" } ] } } } } } }, "/partners/vendors": { "get": { "operationId": "vendors_list-vendors", "summary": "Returns a paginated list of vendors in the workspace.", "tags": [ "Vendors" ], "description": "Vendors are returned with address and contacts embedded. Results are sorted by name ascending.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Partial match on vendor name, account number, or contact email.", "schema": { "type": "string", "example": "office" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by vendor status.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Paginated list of vendors.", "content": { "application/json": { "example": { "page": 1, "limit": 50, "totalRecords": 1, "filters": { "search": null, "status": null }, "vendors": [ { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Office Depot", "email": "ap@officedepot.com", "mainPhone": "+18001234567", "website": "https://officedepot.com", "accountNumber": "V-1001", "status": "active", "type": "SUPPLIER", "legalName": "Office Depot Inc.", "businessName": null, "taxNumber": null, "taxType": "none", "is1099": false, "address": { "street": "500 Supply Chain Blvd", "city": "Boca Raton", "state": "FL", "zipCode": "33431", "country": "USA" }, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "Accounts", "lastName": "Payable", "email": "ap@officedepot.com", "phone": "+18001234567", "isPrimary": true } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "vendors_create-vendor", "summary": "Creates a new vendor in the workspace.", "tags": [ "Vendors" ], "description": "Only `name` is required. Address and contacts can be created inline.", "responses": { "201": { "description": "Vendor created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating vendor.", "data": { "vendor": { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Office Depot", "email": "ap@officedepot.com", "mainPhone": "+18001234567", "website": "https://officedepot.com", "accountNumber": "V-1001", "status": "active", "type": "SUPPLIER", "legalName": "Office Depot Inc.", "businessName": null, "taxNumber": null, "taxType": "none", "is1099": false, "address": { "street": "500 Supply Chain Blvd", "city": "Boca Raton", "state": "FL", "zipCode": "33431", "country": "USA" }, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "Accounts", "lastName": "Payable", "email": "ap@officedepot.com", "phone": "+18001234567", "isPrimary": true } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed or an active vendor with the same name already exists." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Vendor display name." }, "email": { "type": "string", "description": "Primary email address." }, "mainPhone": { "type": "string", "description": "Primary phone number." }, "website": { "type": "string", "description": "Website URL." }, "accountNumber": { "type": "string", "description": "Your vendor account number." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Vendor status. Defaults to active." }, "type": { "type": "string", "enum": [ "MERCHANT", "SUPPLIER", "CONTRACTOR", "CONTACT", "OWNER" ], "description": "Vendor classification. Defaults to MERCHANT." }, "legalName": { "type": "string", "description": "Legal entity name." }, "businessName": { "type": "string", "description": "Doing-business-as name." }, "taxNumber": { "type": "string", "description": "Tax identification number." }, "taxType": { "type": "string", "enum": [ "none", "ssn", "ein", "itin", "atin" ], "description": "Tax id type." }, "is1099": { "type": "boolean", "description": "Whether the vendor is a 1099 contractor." }, "addToContractorGroup": { "type": "boolean", "description": "Add vendor to the contractor group." }, "address": { "type": "object", "description": "Mailing address for the vendor.", "properties": { "street": { "type": "string", "description": "Street address." }, "city": { "type": "string", "description": "City or locality." }, "state": { "type": "string", "description": "State, province, or region." }, "zipCode": { "type": "string", "description": "Postal or ZIP code." }, "country": { "type": "string", "description": "Country name or ISO code." } } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Contact's first name." }, "lastName": { "type": "string", "description": "Contact's last name." }, "email": { "type": "string", "description": "Contact's email address." }, "phone": { "type": "string", "description": "Contact's phone number." }, "isPrimary": { "type": "boolean", "description": "Marks the primary contact." } } }, "description": "Contact people for this vendor." } }, "required": [ "name" ] }, "example": { "name": "Office Depot", "email": "ap@officedepot.com", "type": "SUPPLIER", "status": "active", "address": { "street": "500 Supply Chain Blvd", "city": "Boca Raton", "state": "FL", "zipCode": "33431", "country": "USA" } } } } } } }, "/partners/vendors/{uuid}": { "patch": { "operationId": "vendors_update-vendor", "summary": "Updates an existing vendor. Only the fields you send are changed.", "tags": [ "Vendors" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The vendor UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vendor updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating vendor.", "data": { "vendor": { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "name": "Office Depot", "email": "ap@officedepot.com", "mainPhone": "+18001234567", "website": "https://officedepot.com", "accountNumber": "V-1001", "status": "active", "type": "SUPPLIER", "legalName": "Office Depot Inc.", "businessName": null, "taxNumber": null, "taxType": "none", "is1099": false, "address": { "street": "500 Supply Chain Blvd", "city": "Boca Raton", "state": "FL", "zipCode": "33431", "country": "USA" }, "contacts": [ { "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67", "firstName": "Accounts", "lastName": "Payable", "email": "ap@officedepot.com", "phone": "+18001234567", "isPrimary": true } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed or restricted contractor vendor field." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Vendor not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated vendor name." }, "email": { "type": "string", "description": "Updated email." }, "mainPhone": { "type": "string", "description": "Updated phone number." }, "website": { "type": "string", "description": "Updated website URL." }, "accountNumber": { "type": "string", "description": "Updated account number." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Updated status." }, "type": { "type": "string", "enum": [ "MERCHANT", "SUPPLIER", "CONTRACTOR", "CONTACT", "OWNER" ], "description": "Updated classification." }, "legalName": { "type": "string", "description": "Updated legal name." }, "taxNumber": { "type": "string", "description": "Updated tax number." }, "is1099": { "type": "boolean", "description": "Updated 1099 flag." }, "address": { "type": "object", "description": "Updated address object." }, "contacts": { "type": "array", "items": {}, "description": "Updated contacts array." } } }, "example": { "mainPhone": "+18009876543", "status": "active" } } } } }, "delete": { "operationId": "vendors_delete-vendor", "summary": "Deletes a vendor by UUID.", "tags": [ "Vendors" ], "description": "Vendors linked to bills, transactions, or other records may not be deletable.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The vendor UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vendor deleted successfully." }, "400": { "description": "Vendor is linked to records and cannot be deleted." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Vendor not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/products": { "get": { "operationId": "products-and-services_list-products", "summary": "Returns a paginated list of products and services.", "tags": [ "Products & Services" ], "description": "Partner list responses embed nested category accounts and taxes. Hidden products are excluded unless `includeHidden=true`.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Partial match on name, code, description, or numeric price fields.", "schema": { "type": "string", "example": "consulting" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by product status.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by. Defaults to name.", "schema": { "type": "string", "example": "name" } }, { "name": "orderDirection", "in": "query", "required": false, "description": "Sort direction. Defaults to ASC.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "requireCategory", "in": "query", "required": false, "description": "When `\"true\"`, return only products with an income category account assigned.", "schema": { "type": "string", "example": "true" } }, { "name": "includeHidden", "in": "query", "required": false, "description": "When `\"true\"`, include hidden products.", "schema": { "type": "string", "example": "false" } }, { "name": "hidden", "in": "query", "required": false, "description": "Filter explicitly on hidden flag (`\"true\"` or `\"false\"`).", "schema": { "type": "string", "example": "false" } }, { "name": "isTimeEntry", "in": "query", "required": false, "description": "When `\"true\"`, return only time-entry tasks.", "schema": { "type": "string", "example": "false" } } ], "responses": { "200": { "description": "Paginated list of products.", "content": { "application/json": { "example": { "status": "success", "results": 1, "message": { "products": [ { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "name": "Consulting — hourly", "code": "SVC-001", "description": "Consulting services", "unitPrice": 150, "purchasePrice": null, "total": 150, "tax": 0, "currency": "USD", "status": "active", "pricingMethod": "hour", "hidden": false, "stockQuantity": null, "timeEntryTask": false, "categoryAccount": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Professional Services Income", "type": "Income" }, "purchaseCategoryAccount": null, "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "totalRecords": 1, "page": 1, "limit": 50, "orderBy": "name", "orderDirection": "ASC" } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "products-and-services_create-product", "summary": "Creates a new product or service.", "tags": [ "Products & Services" ], "description": "Use `categoryAccountUuid` and `purchaseCategoryAccountUuid` for chart-of-accounts references and `taxUuids` for taxes.", "responses": { "201": { "description": "Product created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating product", "data": { "productService": { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "name": "Consulting — hourly", "code": "SVC-001", "description": "Consulting services", "unitPrice": 150, "purchasePrice": null, "total": 150, "tax": 0, "currency": "USD", "status": "active", "pricingMethod": "hour", "hidden": false, "stockQuantity": null, "timeEntryTask": false, "categoryAccount": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Professional Services Income", "type": "Income" }, "purchaseCategoryAccount": null, "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed or unknown account/tax UUID." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Product or service name." }, "code": { "type": "string", "description": "Optional SKU or item code." }, "description": { "type": "string", "description": "Longer description." }, "unitPrice": { "type": "number", "description": "Default sell price." }, "purchasePrice": { "type": "number", "description": "Default purchase/cost price." }, "currency": { "type": "string", "description": "ISO 4217 currency. Defaults to workspace currency." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Product status." }, "pricingMethod": { "type": "string", "enum": [ "hour", "item" ], "description": "Pricing basis." }, "hidden": { "type": "boolean", "description": "Hide from default product pickers." }, "stockAdjustment": { "type": "integer", "description": "Initial stock quantity when enabling inventory." }, "timeEntryTask": { "type": "boolean", "description": "Expose as a time-entry task." }, "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Income category account UUID from chart of accounts." }, "purchaseCategoryAccountUuid": { "type": "string", "format": "uuid", "description": "Purchase/expense category account UUID." }, "taxUuids": { "type": "array", "items": {}, "description": "Array of tax UUIDs to attach." }, "notes": { "type": "string", "description": "Internal notes." } }, "required": [ "name" ] }, "example": { "name": "Consulting — hourly", "code": "SVC-001", "description": "Consulting services", "unitPrice": 150, "currency": "USD", "pricingMethod": "hour", "categoryAccountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "status": "active" } } } } } }, "/partners/products/{uuid}": { "get": { "operationId": "products-and-services_get-product", "summary": "Retrieves a single product or service by UUID.", "tags": [ "Products & Services" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The product UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested product.", "content": { "application/json": { "example": { "status": "success", "message": "success on gettng Consulting — hourly product", "data": { "product": { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "name": "Consulting — hourly", "code": "SVC-001", "description": "Consulting services", "unitPrice": 150, "purchasePrice": null, "total": 150, "tax": 0, "currency": "USD", "status": "active", "pricingMethod": "hour", "hidden": false, "stockQuantity": null, "timeEntryTask": false, "categoryAccount": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Professional Services Income", "type": "Income" }, "purchaseCategoryAccount": null, "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Product not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "products-and-services_update-product", "summary": "Updates an existing product. Only the fields you send are changed.", "tags": [ "Products & Services" ], "description": "Use `categoryAccountUuid`, `purchaseCategoryAccountUuid`, and `taxUuids` for account and tax references (same as create). An empty body returns 400.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The product UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Product updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating product", "data": { "updatedProduct": { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "name": "Consulting — hourly", "code": "SVC-001", "description": "Consulting services", "unitPrice": 175, "purchasePrice": null, "total": 150, "tax": 0, "currency": "USD", "status": "active", "pricingMethod": "hour", "hidden": false, "stockQuantity": null, "timeEntryTask": false, "categoryAccount": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Professional Services Income", "type": "Income" }, "purchaseCategoryAccount": null, "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Empty body or validation error." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Product not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name." }, "code": { "type": "string", "description": "Updated code." }, "description": { "type": "string", "description": "Updated description." }, "unitPrice": { "type": "number", "description": "Updated sell price." }, "purchasePrice": { "type": "number", "description": "Updated purchase price." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Updated status." }, "pricingMethod": { "type": "string", "enum": [ "hour", "item" ], "description": "Updated pricing method." }, "hidden": { "type": "boolean", "description": "Updated hidden flag." }, "stockAdjustment": { "type": "integer", "description": "Stock quantity adjustment." }, "stockReason": { "type": "string", "description": "Reason for stock adjustment." }, "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Updated income category account UUID." }, "purchaseCategoryAccountUuid": { "type": "string", "format": "uuid", "description": "Updated purchase category account UUID." }, "taxUuids": { "type": "array", "items": {}, "description": "Replacement tax UUID set." }, "notes": { "type": "string", "description": "Updated notes." } } }, "example": { "unitPrice": 175, "status": "active" } } } } }, "delete": { "operationId": "products-and-services_delete-product", "summary": "Soft-deletes a product or service by UUID.", "tags": [ "Products & Services" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The product UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Product deleted successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on deleting Consulting — hourly product.", "data": { "deletedProduct": { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "name": "Consulting — hourly", "code": "SVC-001", "description": "Consulting services", "unitPrice": 150, "purchasePrice": null, "total": 150, "tax": 0, "currency": "USD", "status": "active", "pricingMethod": "hour", "hidden": false, "stockQuantity": null, "timeEntryTask": false, "categoryAccount": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Professional Services Income", "type": "Income" }, "purchaseCategoryAccount": null, "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Product not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/journal-entries": { "get": { "operationId": "journal-entries_list-journal-entries", "summary": "Returns a paginated list of journal entry lines.", "tags": [ "Journal Entries" ], "description": "Partner list responses embed nested account objects on each line. Use date, account, and search filters to narrow results.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search across memo and line descriptions.", "schema": { "type": "string", "example": "rent" } }, { "name": "startDate", "in": "query", "required": false, "description": "Filter on posting date (ISO, inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Filter on posting date (ISO, inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "accounts", "in": "query", "required": false, "description": "Comma-separated account UUIDs to filter by.", "schema": { "type": "string" } }, { "name": "accountType", "in": "query", "required": false, "description": "Filter by account high-level type.", "schema": { "type": "string", "enum": [ "Assets", "Liabilities", "Equity", "Income", "Expenses" ] } }, { "name": "reviewed", "in": "query", "required": false, "description": "Filter by reviewed state.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated journal entry lines.", "content": { "application/json": { "example": { "status": "success", "message": "Successfully found all journal entries", "data": { "page": 1, "limit": 50, "totalRecords": 2, "totalSplitJeCount": 0, "records": 2, "filters": { "search": null, "startDate": null, "endDate": null }, "results": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "descriptionEntry": "Accrue March rent", "descriptionLine": "Rent expense", "date": "2026-03-01", "refNumber": "JE-2026-003", "amountDebit": "2500.00", "amountCredit": null, "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Rent Expense", "type": "Expenses" }, "journalLinkUuid": "a9b8c7d6-e5f4-3210-abcd-ef9876543210", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "journal-entries_create-journal-entry", "summary": "Creates a manual journal entry posting.", "tags": [ "Journal Entries" ], "description": "Required body fields: `descriptionEntry`, `date`, and `lines`. Each line needs `accountUuid` and exactly one of `amountDebit` or `amountCredit`.", "responses": { "201": { "description": "Journal entry created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Successfully created journal entry", "data": { "results": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "descriptionEntry": "Accrue March rent", "descriptionLine": "Rent expense", "date": "2026-03-01", "refNumber": "JE-2026-003", "amountDebit": "2500.00", "amountCredit": null, "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Rent Expense", "type": "Expenses" }, "journalLinkUuid": "a9b8c7d6-e5f4-3210-abcd-ef9876543210", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } } }, "400": { "description": "Unbalanced lines, unknown account UUID, locked period, or validation error." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descriptionEntry": { "type": "string", "description": "Posting memo." }, "date": { "type": "string", "format": "date", "description": "Posting date (YYYY-MM-DD)." }, "refNumber": { "type": "string", "description": "Optional reference number." }, "withCaution": { "type": "boolean", "description": "Skip book-closeness checks when true (use sparingly)." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "accountUuid": { "type": "string", "format": "uuid", "description": "Chart-of-accounts UUID for this line." }, "amountDebit": { "type": "string", "description": "Debit amount. Provide this or amountCredit, not both." }, "amountCredit": { "type": "string", "description": "Credit amount. Provide this or amountDebit, not both." }, "descriptionLine": { "type": "string", "description": "Optional per-line description." } } }, "description": "Debit and credit lines. Must balance." } }, "required": [ "descriptionEntry", "date", "lines" ] }, "example": { "descriptionEntry": "Accrue March rent", "date": "2026-03-01", "refNumber": "JE-2026-003", "lines": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "amountDebit": "2500.00", "descriptionLine": "Rent expense" }, { "accountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "amountCredit": "2500.00", "descriptionLine": "Accrued rent payable" } ] } } } } } }, "/partners/journal-entries/bulk": { "post": { "operationId": "journal-entries_bulk-create-journal-entries", "summary": "Creates up to 100 journal entry postings in one request with partial-success semantics.", "tags": [ "Journal Entries" ], "description": "Body: `{ journalEntries: [, ...] }` where each posting uses the same shape as create journal entry. Each posting runs in its own transaction. HTTP 201 is returned when the batch is accepted, even if all postings fail — read `errorCount` and per-row `results`.", "responses": { "201": { "description": "Batch accepted. Check successCount and per-row results.", "content": { "application/json": { "example": { "successCount": 1, "errorCount": 0, "results": [ { "index": 0, "success": true, "journalEntry": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "descriptionEntry": "Accrue March rent", "descriptionLine": "Rent expense", "date": "2026-03-01", "refNumber": "JE-2026-003", "amountDebit": "2500.00", "amountCredit": null, "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Rent Expense", "type": "Expenses" }, "journalLinkUuid": "a9b8c7d6-e5f4-3210-abcd-ef9876543210", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } ] } } } }, "400": { "description": "Batch-level validation failed (empty array, over 100 postings, etc.)." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journalEntries": { "type": "array", "items": {}, "description": "Array of journal entry create payloads (same fields as POST /partners/journal-entries). Maximum 100 per request." } }, "required": [ "journalEntries" ] }, "example": { "journalEntries": [ { "descriptionEntry": "Accrue March rent", "date": "2026-03-01", "refNumber": "JE-2026-003", "lines": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "amountDebit": "2500.00", "descriptionLine": "Rent expense" }, { "accountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "amountCredit": "2500.00", "descriptionLine": "Accrued rent payable" } ] } ] } } } } } }, "/partners/journal-entries/{uuid}": { "patch": { "operationId": "journal-entries_update-journal-entry", "summary": "Updates a manually-created journal entry by UUID.", "tags": [ "Journal Entries" ], "description": "Same body shape as create: `descriptionEntry`, `date`, optional `refNumber`, and the full replacement `lines` array. System-generated entries return 400.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of any line in the posting (anchor line).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Journal entry updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Successfully updated journal entry", "data": { "results": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "descriptionEntry": "Accrue March rent", "descriptionLine": "Rent expense", "date": "2026-03-01", "refNumber": "JE-2026-003", "amountDebit": "2500.00", "amountCredit": null, "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "account": { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Rent Expense", "type": "Expenses" }, "journalLinkUuid": "a9b8c7d6-e5f4-3210-abcd-ef9876543210", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } } }, "400": { "description": "System-generated entry, validation error, or unbalanced lines." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Journal entry not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descriptionEntry": { "type": "string", "description": "Updated posting memo." }, "date": { "type": "string", "format": "date", "description": "Updated posting date." }, "refNumber": { "type": "string", "description": "Updated reference number." }, "withCaution": { "type": "boolean", "description": "Skip book-closeness checks when true." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "accountUuid": { "type": "string", "format": "uuid", "description": "Chart-of-accounts UUID." }, "amountDebit": { "type": "string", "description": "Debit amount." }, "amountCredit": { "type": "string", "description": "Credit amount." }, "descriptionLine": { "type": "string", "description": "Per-line description." } } }, "description": "Full replacement lines array." } } }, "example": { "descriptionEntry": "Accrue March rent — revised", "date": "2026-03-01", "lines": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "amountDebit": "2500.00", "descriptionLine": "Rent expense" }, { "accountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "amountCredit": "2500.00", "descriptionLine": "Accrued rent payable" } ] } } } } }, "delete": { "operationId": "journal-entries_delete-journal-entry", "summary": "Deletes a journal entry posting by UUID.", "tags": [ "Journal Entries" ], "description": "Removes all lines sharing the same journal link. System-generated entries return 400.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of any line in the posting.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "203": { "description": "Journal entry deleted successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Successfully deleted journal entry" } } } }, "400": { "description": "System-generated entry cannot be deleted." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Journal entry not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/budgets/overall": { "get": { "operationId": "budgets_get-overall-budget", "summary": "Returns the workspace Overall Budget, if one exists.", "tags": [ "Budgets" ], "responses": { "200": { "description": "The Overall Budget record.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching overall budget", "data": { "budget": { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "Overall Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "draft", "lockedAt": null, "isOverall": true, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "No Overall Budget exists for this workspace." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/budgets": { "get": { "operationId": "budgets_list-budgets", "summary": "Returns all budgets in the workspace, optionally filtered by status.", "tags": [ "Budgets" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by budget status.", "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] } } ], "responses": { "200": { "description": "Budget list.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching budgets", "data": { "budgets": [ { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "draft", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "budgets_create-budget", "summary": "Creates a budget and its initial version.", "tags": [ "Budgets" ], "responses": { "201": { "description": "Budget and initial version created.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating budget", "data": { "budget": { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "draft", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" }, "version": { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } } } } } }, "400": { "description": "Validation failed or duplicate budget name." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique budget name (among non-archived budgets)." }, "startPeriod": { "type": "string", "format": "date", "description": "First period start date (ISO)." }, "cadence": { "type": "string", "enum": [ "monthly", "yearly" ], "description": "Period cadence." }, "actualPeriods": { "type": "integer", "description": "Historical actual periods (0 or greater)." }, "budgetPeriods": { "type": "integer", "description": "Forward budget periods (minimum 1)." }, "currencyCode": { "type": "string", "description": "ISO 4217 currency. Defaults to USD." }, "isOverall": { "type": "boolean", "description": "Create as the workspace Overall Budget." } }, "required": [ "name", "startPeriod", "cadence", "actualPeriods", "budgetPeriods" ] }, "example": { "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD" } } } } } }, "/partners/budgets/{uuid}": { "get": { "operationId": "budgets_get-budget", "summary": "Retrieves a single budget by UUID.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested budget.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching budget", "data": { "budget": { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "draft", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "budgets_update-budget", "summary": "Updates budget metadata. Rejected when the budget is published or locked.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Budget updated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating budget", "data": { "budget": { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "draft", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Budget is published, locked, or validation failed." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name." }, "startPeriod": { "type": "string", "format": "date", "description": "Updated start period." }, "cadence": { "type": "string", "enum": [ "monthly", "yearly" ], "description": "Updated cadence." }, "actualPeriods": { "type": "integer", "description": "Updated actual period count." }, "budgetPeriods": { "type": "integer", "description": "Updated budget period count." }, "isOverall": { "type": "boolean", "description": "Promote to Overall Budget when allowed." } } }, "example": { "name": "FY 2026 Operating Budget — Revised" } } } } }, "delete": { "operationId": "budgets_delete-budget", "summary": "Deletes a draft budget.", "tags": [ "Budgets" ], "description": "Only draft budgets can be deleted; the Overall Budget cannot be deleted, and published or archived budgets must be archived instead.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Budget deleted.", "content": { "application/json": { "example": { "status": "success", "message": "Success on deleting budget", "data": null } } } }, "400": { "description": "Budget is the Overall Budget or is not in draft status." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/budgets/{uuid}/grid": { "get": { "operationId": "budgets_get-budget-grid", "summary": "Returns the budget cell grid for a version, with optional actuals.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "versionNumber", "in": "query", "required": false, "description": "Version to load. Defaults to the latest version.", "schema": { "type": "integer", "example": 1 } }, { "name": "includeActuals", "in": "query", "required": false, "description": "When false, omit actual-period columns. Defaults to true.", "schema": { "type": "boolean" } }, { "name": "reportType", "in": "query", "required": false, "description": "Reporting basis for actuals.", "schema": { "type": "string", "enum": [ "accrual", "cash" ] } } ], "responses": { "200": { "description": "Budget grid with account UUIDs on each row.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching budget grid", "data": { "grid": { "meta": { "version": { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } }, "rows": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "parentAccountUuid": null, "accountName": "Sales Revenue", "accountPath": "Income:Sales Revenue", "values": [ 10000, 12000, 11000 ] } ] } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget or version not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/budgets/{uuid}/versions": { "get": { "operationId": "budgets_list-budget-versions", "summary": "Returns version summaries for a budget.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Version list.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching budget versions", "data": { "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "budgets_create-budget-version", "summary": "Creates a new numbered version for the budget.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Version created.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating budget version", "data": { "version": { "versionNumber": 2, "label": "Q2 revision", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Optional version label." } } }, "example": { "label": "Q2 revision" } } } } } }, "/partners/budgets/{uuid}/versions/{versionNumber}/cells": { "patch": { "operationId": "budgets_update-budget-cells", "summary": "Updates one or more cells in a budget version.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "versionNumber", "in": "path", "required": true, "description": "Target version number.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Cells updated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating budget cells", "data": { "updatedCount": 1 } } } } }, "400": { "description": "Invalid account UUID, amount, or legacy accountId field." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget or version not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "array", "items": { "type": "object", "properties": { "accountUuid": { "type": "string", "format": "uuid", "description": "Chart-of-accounts UUID for the row." }, "periodStart": { "type": "string", "format": "date", "description": "Period start date for the cell (ISO)." }, "amount": { "type": "number", "description": "Budget amount for the period." } } }, "description": "Cell updates to apply." } }, "required": [ "updates" ] }, "example": { "updates": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "periodStart": "2026-01-01", "amount": 10000 } ] } } } } } }, "/partners/budgets/{uuid}/versions/{versionNumber}/cells/bulk": { "post": { "operationId": "budgets_bulk-update-budget-cells", "summary": "Applies many cell updates in one request with per-row success/failure results.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "versionNumber", "in": "path", "required": true, "description": "Target version number.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "201": { "description": "Bulk update summary with per-row results.", "content": { "application/json": { "example": { "successCount": 2, "failureCount": 0, "results": [ { "index": 0, "success": true, "budgetCellUpdate": { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "periodStart": "2026-01-01", "amount": 10000 } }, { "index": 1, "success": true, "budgetCellUpdate": { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "periodStart": "2026-02-01", "amount": 12000 } } ] } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "array", "items": { "type": "object", "properties": { "accountUuid": { "type": "string", "format": "uuid", "description": "Chart-of-accounts UUID." }, "periodStart": { "type": "string", "format": "date", "description": "Period start date (ISO)." }, "amount": { "type": "number", "description": "Budget amount." } } }, "description": "Cell updates (same shape as the single-cell route)." } }, "required": [ "updates" ] }, "example": { "updates": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "periodStart": "2026-01-01", "amount": 10000 }, { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "periodStart": "2026-02-01", "amount": 12000 } ] } } } } } }, "/partners/budgets/{uuid}/publish": { "post": { "operationId": "budgets_publish-budget", "summary": "Publishes a budget version snapshot.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Budget published.", "content": { "application/json": { "example": { "status": "success", "message": "Success on publishing budget", "data": { "budget": { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "published", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" }, "version": { "versionNumber": 1, "label": "Initial", "isPublished": true, "createdAt": "2026-01-15T10:30:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget or version not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "versionNumber": { "type": "integer", "description": "Version to publish. Defaults to the latest version when omitted." } } }, "example": { "versionNumber": 1 } } } } } }, "/partners/budgets/{uuid}/archive": { "post": { "operationId": "budgets_archive-budget", "summary": "Archives a budget.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Budget archived.", "content": { "application/json": { "example": { "status": "success", "message": "Success on archiving budget", "data": { "budget": { "id": "55667788-99aa-bbcc-ddee-ff0011223344", "name": "FY 2026 Operating Budget", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "archived", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/budgets/{uuid}/duplicate": { "post": { "operationId": "budgets_duplicate-budget", "summary": "Creates a copy of a budget, optionally carrying cell values forward.", "tags": [ "Budgets" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The source budget UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Budget duplicated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on duplicating budget", "data": { "budget": { "id": "66778899-aabb-ccdd-eeff-001122334455", "name": "FY 2026 Operating Budget — Copy", "startPeriod": "2026-01-01", "cadence": "monthly", "actualPeriods": 3, "budgetPeriods": 12, "currencyCode": "USD", "status": "draft", "lockedAt": null, "isOverall": false, "versions": [ { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" }, "version": { "versionNumber": 1, "label": "Initial", "isPublished": false, "createdAt": "2026-01-15T10:30:00.000Z" } } } } } }, "400": { "description": "Duplicate name or Overall Budget conflict." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Source budget not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newName": { "type": "string", "description": "Name for the duplicated budget." }, "carryValues": { "type": "boolean", "description": "Copy cell values into the new budget." }, "isOverall": { "type": "boolean", "description": "Mark the duplicate as the Overall Budget." }, "versionNumber": { "type": "integer", "description": "Source version to copy from." } }, "required": [ "newName" ] }, "example": { "newName": "FY 2026 Operating Budget — Copy", "carryValues": true } } } } } }, "/partners/tags": { "get": { "operationId": "tags_list-tags", "summary": "Returns all tags in the workspace.", "tags": [ "Tags" ], "description": "Tags are returned with embedded tag group metadata when assigned. Results are sorted by name ascending.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match on tag name.", "schema": { "type": "string", "example": "office" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Array of tags.", "content": { "application/json": { "example": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office", "tagGroups": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ] } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "tags_create-tag", "summary": "Creates a tag in the workspace.", "tags": [ "Tags" ], "description": "If a tag with the same name already exists, the existing tag is returned.", "responses": { "201": { "description": "Tag created (or existing tag returned).", "content": { "application/json": { "example": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office", "tagGroups": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "400": { "description": "Validation failed — missing name." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Tag label. Must be unique per workspace." } }, "required": [ "name" ] }, "example": { "name": "Office" } } } } } }, "/partners/tags/{uuid}": { "get": { "operationId": "tags_get-tag", "summary": "Retrieves a single tag by UUID.", "tags": [ "Tags" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The tag UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested tag.", "content": { "application/json": { "example": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office", "tagGroups": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Tag not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "tags_update-tag", "summary": "Updates a tag name by UUID.", "tags": [ "Tags" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The tag UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tag updated successfully.", "content": { "application/json": { "example": { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office — HQ", "tagGroups": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Tag not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated tag name." } }, "required": [ "name" ] }, "example": { "name": "Office — HQ" } } } } }, "delete": { "operationId": "tags_delete-tag", "summary": "Deletes a tag and removes all of its associations.", "tags": [ "Tags" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The tag UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tag deleted successfully." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Tag not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/tags/groups": { "get": { "operationId": "tags_list-tag-groups", "summary": "Returns all tag groups and tags not assigned to any group.", "tags": [ "Tags" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Partial match on group or ungrouped tag names.", "schema": { "type": "string", "example": "department" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Tag groups and ungrouped tags.", "content": { "application/json": { "example": { "tagGroups": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9", "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" }, { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891", "name": "Marketing" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "unGroupedTags": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "name": "Travel" } ] } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "tags_create-tag-group", "summary": "Creates a tag group and optionally assigns tags.", "tags": [ "Tags" ], "description": "Body requires `name` (unique per workspace). Optional `color` and `tagUuids` (tag UUIDs from list tags). Each tag may belong to at most one group.", "responses": { "201": { "description": "Tag group created successfully.", "content": { "application/json": { "example": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9", "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" }, { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891", "name": "Marketing" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "400": { "description": "Duplicate group name or tag already assigned to another group." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Group name. Unique per workspace." }, "color": { "type": "string", "description": "Display color (for example a hex value)." }, "tagUuids": { "type": "array", "items": {}, "description": "Tag UUIDs to include in the group on create." } }, "required": [ "name" ] }, "example": { "name": "Department", "color": "#4A90D9", "tagUuids": [ "e5f6a7b8-c9d0-1234-efab-345678901234" ] } } } } } }, "/partners/tags/groups/{uuid}": { "get": { "operationId": "tags_get-tag-group", "summary": "Retrieves a single tag group by UUID with its member tags.", "tags": [ "Tags" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The tag group UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested tag group.", "content": { "application/json": { "example": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9", "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" }, { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891", "name": "Marketing" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Tag group not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "tags_update-tag-group", "summary": "Updates a tag group name, color, and/or membership.", "tags": [ "Tags" ], "description": "When `tagUuids` is sent, membership is replaced with that exact set. Pass `[]` to remove all tags from the group.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The tag group UUID to update.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tag group updated successfully.", "content": { "application/json": { "example": { "id": "f6a7b8c9-d0e1-2345-fabc-456789012346", "name": "Department", "color": "#4A90D9", "tags": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901234", "name": "Office" }, { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891", "name": "Marketing" } ], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } }, "400": { "description": "Duplicate name or tag already in another group." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Tag group not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated group name." }, "color": { "type": "string", "description": "Updated color." }, "tagUuids": { "type": "array", "items": {}, "description": "Replacement tag UUID set for group membership." } } }, "example": { "color": "#E48642", "tagUuids": [ "e5f6a7b8-c9d0-1234-efab-345678901234", "a1b2c3d4-e5f6-7890-abcd-ef1234567891" ] } } } } }, "delete": { "operationId": "tags_delete-tag-group", "summary": "Deletes a tag group. Member tags are not deleted.", "tags": [ "Tags" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The tag group UUID to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tag group deleted successfully." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Tag group not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/webhooks": { "get": { "operationId": "webhooks_list-webhooks", "summary": "Returns every webhook subscription for the authorized workspace.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Subscriptions returned under data.webhooks.", "content": { "application/json": { "example": { "status": "success", "data": { "webhooks": [ { "uuid": "e0f1a2b3-c4d5-6789-ef01-234567890abc", "event": "customer.created", "callbackUrl": "https://webhook.site/your-unique-id", "status": "active", "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "webhooks_create-webhook", "summary": "Subscribes to a single event type for the workspace.", "tags": [ "Webhooks" ], "description": "Provide a public HTTPS callback URL. Optionally set a signing secret for delivery verification. Defaults to status `active`.", "responses": { "201": { "description": "Subscription created. Returned under data.webhook.", "content": { "application/json": { "example": { "status": "success", "data": { "webhook": { "uuid": "e0f1a2b3-c4d5-6789-ef01-234567890abc", "event": "customer.created", "callbackUrl": "https://webhook.site/your-unique-id", "status": "active", "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } } } } } }, "400": { "description": "Invalid callback URL, duplicate event subscription, or validation error." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "customer.created", "customer.updated", "customer.deleted", "vendor.created", "vendor.updated", "vendor.deleted", "transaction.created", "transaction.updated", "transaction.deleted", "invoice.created", "invoice.updated", "invoice.deleted", "bill.created", "bill.updated", "bill.deleted" ], "description": "Event type to subscribe to." }, "callbackUrl": { "type": "string", "description": "Public HTTPS URL for deliveries." }, "signingSecret": { "type": "string", "description": "Optional secret for HMAC verification of delivery payloads (1–512 characters)." }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "description": "Initial status. Defaults to active." } }, "required": [ "event", "callbackUrl" ] }, "example": { "event": "customer.created", "callbackUrl": "https://webhook.site/your-unique-id", "status": "active" } } } } } }, "/partners/webhooks/{uuid}": { "patch": { "operationId": "webhooks_update-webhook", "summary": "Updates callback URL, status, or signing secret for an existing subscription.", "tags": [ "Webhooks" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Subscription UUID.", "schema": { "type": "string", "format": "uuid", "example": "e0f1a2b3-c4d5-6789-ef01-234567890abc" } } ], "responses": { "200": { "description": "Subscription updated. Returned under data.webhook.", "content": { "application/json": { "example": { "status": "success", "data": { "webhook": { "uuid": "e0f1a2b3-c4d5-6789-ef01-234567890abc", "event": "customer.created", "callbackUrl": "https://webhook.site/your-unique-id", "status": "paused", "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Subscription not found for this workspace." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callbackUrl": { "type": "string", "description": "New public HTTPS callback URL." }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "description": "New subscription status." }, "signingSecret": { "type": "string", "description": "New signing secret, or null to clear the existing secret." } } }, "example": { "status": "paused" } } } } }, "delete": { "operationId": "webhooks_delete-webhook", "summary": "Removes a webhook subscription. Deliveries stop immediately.", "tags": [ "Webhooks" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Subscription UUID.", "schema": { "type": "string", "format": "uuid", "example": "e0f1a2b3-c4d5-6789-ef01-234567890abc" } } ], "responses": { "200": { "description": "Subscription deleted." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Subscription not found for this workspace." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/documents": { "get": { "operationId": "documents_list-documents", "summary": "Returns a paginated list of documents with optional UUID filters.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "vendorUuids", "in": "query", "required": false, "description": "Comma-separated vendor UUIDs to filter by.", "schema": { "type": "string" } }, { "name": "customerUuids", "in": "query", "required": false, "description": "Comma-separated customer UUIDs to filter by.", "schema": { "type": "string" } }, { "name": "personUuids", "in": "query", "required": false, "description": "Comma-separated person UUIDs to filter by.", "schema": { "type": "string" } }, { "name": "projectUuids", "in": "query", "required": false, "description": "Comma-separated project UUIDs to filter by.", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Filter documents created on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": false, "description": "Filter documents created on or before this date.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated document list.", "content": { "application/json": { "example": { "status": "success", "data": { "page": 1, "limit": 20, "totalRecords": 1, "totalPages": 1, "records": [ { "id": "d9e0f1a2-b3c4-5678-def0-890123456789", "fileName": "contract-acme-2026.pdf", "folderPath": "Contracts", "mimeType": "application/pdf", "fileSize": 245760, "vendor": null, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "person": null, "project": null, "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "documents_upload-document", "summary": "Uploads a file via multipart form data.", "tags": [ "Documents" ], "description": "Send multipart/form-data with a `file` field. Optional text fields: folderPath, vendorUuid, customerUuid, personUuid, projectUuid. Sign the request with an empty-object body hash.", "responses": { "201": { "description": "Document created.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "d9e0f1a2-b3c4-5678-def0-890123456789", "fileName": "contract-acme-2026.pdf", "folderPath": "Contracts", "mimeType": "application/pdf", "fileSize": 245760, "vendor": null, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "person": null, "project": null, "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } } } } }, "400": { "description": "Missing file or validation error." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/documents/{uuid}": { "get": { "operationId": "documents_get-document", "summary": "Returns a single document by UUID.", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Document UUID.", "schema": { "type": "string", "format": "uuid", "example": "d9e0f1a2-b3c4-5678-def0-890123456789" } } ], "responses": { "200": { "description": "Document returned under data.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "d9e0f1a2-b3c4-5678-def0-890123456789", "fileName": "contract-acme-2026.pdf", "folderPath": "Contracts", "mimeType": "application/pdf", "fileSize": 245760, "vendor": null, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "person": null, "project": null, "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Document not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "put": { "operationId": "documents_update-document", "summary": "Updates document metadata and link fields.", "tags": [ "Documents" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Document UUID.", "schema": { "type": "string", "format": "uuid", "example": "d9e0f1a2-b3c4-5678-def0-890123456789" } } ], "responses": { "200": { "description": "Document updated.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "d9e0f1a2-b3c4-5678-def0-890123456789", "fileName": "contract-acme-2026.pdf", "folderPath": "Contracts/2026", "mimeType": "application/pdf", "fileSize": 245760, "vendor": null, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "person": null, "project": null, "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Document not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folderPath": { "type": "string", "description": "New folder path." }, "vendorUuid": { "type": "string", "format": "uuid", "description": "Vendor UUID to link." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Customer UUID to link." }, "personUuid": { "type": "string", "format": "uuid", "description": "Person UUID to link." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Project UUID to link." } } }, "example": { "folderPath": "Contracts/2026", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35" } } } } }, "delete": { "operationId": "documents_delete-document", "summary": "Deletes the document blob and database row.", "tags": [ "Documents" ], "description": "Blocked for Period Close system roots and Bank Statements/ paths.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Document UUID.", "schema": { "type": "string", "format": "uuid", "example": "d9e0f1a2-b3c4-5678-def0-890123456789" } } ], "responses": { "200": { "description": "Document deleted.", "content": { "application/json": { "example": { "status": "success", "message": "Document deleted." } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Document not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/documents/chunk-upload/initiate": { "post": { "operationId": "documents_chunk-upload-initiate", "summary": "Starts a chunked upload session for a large file.", "tags": [ "Documents" ], "responses": { "200": { "description": "Returns uploadProgressId and chunk configuration.", "content": { "application/json": { "example": { "status": "success", "data": { "uploadProgressId": "upload-progress-uuid", "chunkSizeInBytes": 5242880, "totalChunks": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Original file name." }, "folderPath": { "type": "string", "description": "Destination folder path." }, "fileSize": { "type": "integer", "description": "Total file size in bytes." }, "chunkSizeInMB": { "type": "integer", "description": "Chunk size in megabytes." } }, "required": [ "fileName", "folderPath", "fileSize" ] }, "example": { "fileName": "contract-acme-2026.pdf", "folderPath": "Contracts", "fileSize": 5242880, "chunkSizeInMB": 5 } } } } } }, "/partners/documents/chunk-upload/chunk": { "post": { "operationId": "documents_chunk-upload-chunk", "summary": "Uploads a single chunk of a multipart upload.", "tags": [ "Documents" ], "description": "Send multipart/form-data with `file`, `blockId`, and `uploadProgressId`. Sign with empty-object body hash.", "responses": { "200": { "description": "Chunk accepted.", "content": { "application/json": { "example": { "status": "success", "data": { "blockId": "block-1", "uploaded": true } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Binary chunk sent as multipart form field." }, "blockId": { "type": "string", "description": "Identifier for this chunk block." }, "uploadProgressId": { "type": "string", "description": "Upload session identifier from initiate." } }, "required": [ "file", "blockId", "uploadProgressId" ] } } } } } }, "/partners/documents/chunk-upload/complete": { "post": { "operationId": "documents_chunk-upload-complete", "summary": "Finalizes a chunked upload and creates the document record.", "tags": [ "Documents" ], "responses": { "200": { "description": "Document created from assembled chunks.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "d9e0f1a2-b3c4-5678-def0-890123456789", "fileName": "contract-acme-2026.pdf", "folderPath": "Contracts", "mimeType": "application/pdf", "fileSize": 245760, "vendor": null, "customer": { "id": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "person": null, "project": null, "createdAt": "2026-03-01T09:00:00.000Z", "updatedAt": "2026-03-01T09:00:00.000Z" } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadProgressId": { "type": "string", "description": "Upload session identifier from initiate." }, "blockIds": { "type": "array", "items": {}, "description": "Ordered list of block IDs uploaded." }, "vendorUuid": { "type": "string", "format": "uuid", "description": "Optional vendor UUID to link." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Optional customer UUID to link." }, "personUuid": { "type": "string", "format": "uuid", "description": "Optional person UUID to link." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Optional project UUID to link." } }, "required": [ "uploadProgressId", "blockIds" ] }, "example": { "uploadProgressId": "upload-progress-uuid", "blockIds": [ "block-1", "block-2" ], "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35" } } } } } }, "/partners/documents/chunk-upload/progress/{uploadProgressId}": { "get": { "operationId": "documents_chunk-upload-progress", "summary": "Returns progress for an in-flight chunked upload.", "tags": [ "Documents" ], "parameters": [ { "name": "uploadProgressId", "in": "path", "required": true, "description": "Upload session identifier from initiate.", "schema": { "type": "string", "example": "upload-progress-uuid" } } ], "responses": { "200": { "description": "Upload progress details.", "content": { "application/json": { "example": { "status": "success", "data": { "uploadProgressId": "upload-progress-uuid", "uploadedChunks": 1, "totalChunks": 1, "percentComplete": 100 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Upload session not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/people": { "get": { "operationId": "people_list-people", "summary": "Returns a paginated list of people in the workspace.", "tags": [ "People" ], "description": "People are returned with optional nested associations (address, primary job, department). Soft-deleted people are excluded.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match on first name, last name, email, and phone.", "schema": { "type": "string", "example": "jane" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by people type (for example employee, contractor). Also supports `1099 contractor`.", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "required": false, "description": "Filter by active/inactive status.", "schema": { "type": "boolean" } }, { "name": "roles", "in": "query", "required": false, "description": "Comma-separated roles; matches people whose role array contains any listed role.", "schema": { "type": "string" } }, { "name": "payrollEnabled", "in": "query", "required": false, "description": "When true, returns people with the payroll role.", "schema": { "type": "boolean" } }, { "name": "createdByMe", "in": "query", "required": false, "description": "When true, returns only people created by the authenticated user.", "schema": { "type": "boolean" } }, { "name": "isNotExpenseReporter", "in": "query", "required": false, "description": "When true, excludes people who are already expense reporters.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of people.", "content": { "application/json": { "example": { "people": [ { "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@acme.com", "phone": "+19876543210", "type": "employee", "enabled": true, "role": [ "payroll" ], "paymentUnit": "hourly", "rate": 45, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalRecords": 1, "totalPages": 1, "filters": {} } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/people/{uuid}": { "get": { "operationId": "people_get-person", "summary": "Retrieves a single person by UUID.", "tags": [ "People" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The person UUID as returned in list responses.", "schema": { "type": "string", "format": "uuid", "example": "f1a2b3c4-d5e6-4789-a012-3456789abcde" } } ], "responses": { "200": { "description": "The requested person.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching people data.", "data": { "people": { "id": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@acme.com", "phone": "+19876543210", "type": "employee", "enabled": true, "role": [ "payroll" ], "paymentUnit": "hourly", "rate": 45, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Person not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/projects/statuses": { "get": { "operationId": "projects_list-project-statuses", "summary": "Returns the project statuses available in the workspace.", "tags": [ "Projects" ], "description": "Each status includes its UUID, name, color, and ordering. Use the UUID as `statusUuid` on create/update or in `statusUuids` list filters.", "responses": { "200": { "description": "Workspace project statuses.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching project statuses", "data": { "statuses": [ { "uuid": "aabbccdd-eeff-4012-8000-001122334455", "name": "In Progress", "color": "#E48642", "order": 1, "isDefault": false } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/projects": { "get": { "operationId": "projects_list-projects", "summary": "Returns a paginated list of projects.", "tags": [ "Projects" ], "description": "Soft-deleted projects are excluded. Filter by customer, status, and name search.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match on project name.", "schema": { "type": "string", "example": "website" } }, { "name": "customerUuids", "in": "query", "required": false, "description": "Comma-separated customer UUIDs to filter by.", "schema": { "type": "string", "example": "dfa3219e-6af8-4c53-997a-037534f63a35" } }, { "name": "statusUuids", "in": "query", "required": false, "description": "Comma-separated project-status UUIDs to filter by.", "schema": { "type": "string", "example": "aabbccdd-eeff-4012-8000-001122334455" } } ], "responses": { "200": { "description": "Paginated list of projects.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching projects", "data": { "projects": [ { "id": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign", "description": "Redesign the marketing website for Acme Corporation.", "customId": "PRJ-2026-001", "startDate": "2026-02-01", "endDate": "2026-06-30", "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "projectStatus": { "uuid": "aabbccdd-eeff-4012-8000-001122334455", "name": "In Progress", "color": "#E48642" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalRecords": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "projects_create-project", "summary": "Creates a new project in the workspace.", "tags": [ "Projects" ], "description": "Only `name` is required. `statusUuid` defaults to the workspace default status when omitted. Numeric `customerId`, `statusId`, and `teamId` are stripped — use UUID fields.", "responses": { "201": { "description": "Project created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating project", "data": { "project": { "id": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign", "description": "Redesign the marketing website for Acme Corporation.", "customId": "PRJ-2026-001", "startDate": "2026-02-01", "endDate": "2026-06-30", "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "projectStatus": { "uuid": "aabbccdd-eeff-4012-8000-001122334455", "name": "In Progress", "color": "#E48642" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed — for example missing name." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Customer UUID from the Customers API. Omit or null for no customer." }, "statusUuid": { "type": "string", "format": "uuid", "description": "Project status UUID from List project statuses." }, "description": { "type": "string", "description": "Project description." }, "customId": { "type": "string", "description": "External reference id." }, "startDate": { "type": "string", "format": "date", "description": "Start date (YYYY-MM-DD)." }, "endDate": { "type": "string", "format": "date", "description": "End date (YYYY-MM-DD)." } }, "required": [ "name" ] }, "example": { "name": "Website Redesign", "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "statusUuid": "aabbccdd-eeff-4012-8000-001122334455", "description": "Redesign the marketing website for Acme Corporation.", "startDate": "2026-02-01", "endDate": "2026-06-30" } } } } } }, "/partners/projects/{uuid}/tasks": { "get": { "operationId": "projects_list-project-tasks", "summary": "Returns tasks attached to a project.", "tags": [ "Projects" ], "description": "Returns the same partner-sanitized task envelope as List tasks.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID.", "schema": { "type": "string", "format": "uuid", "example": "11223344-5566-7788-99aa-bbccddeeff00" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match on task name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of tasks for the project.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching project tasks", "data": { "tasks": [ { "id": "22334455-6677-8899-aabb-ccddeeff0011", "name": "Review wireframes", "type": "INTERNAL_TASK", "priority": "medium", "deadline": "2026-04-15", "visibility": "firm-team", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalRecords": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Project not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/projects/{uuid}": { "get": { "operationId": "projects_get-project", "summary": "Retrieves a single project by UUID.", "tags": [ "Projects" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID.", "schema": { "type": "string", "format": "uuid", "example": "11223344-5566-7788-99aa-bbccddeeff00" } } ], "responses": { "200": { "description": "The requested project.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching project", "data": { "project": { "id": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign", "description": "Redesign the marketing website for Acme Corporation.", "customId": "PRJ-2026-001", "startDate": "2026-02-01", "endDate": "2026-06-30", "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "projectStatus": { "uuid": "aabbccdd-eeff-4012-8000-001122334455", "name": "In Progress", "color": "#E48642" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Project not found or soft-deleted." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "projects_update-project", "summary": "Updates an existing project. Only the fields you send are changed.", "tags": [ "Projects" ], "description": "Pass `customerUuid` as a UUID to set the customer, `null` or empty string to clear, or omit to leave unchanged. `statusUuid` sets the status when provided.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID to update.", "schema": { "type": "string", "format": "uuid", "example": "11223344-5566-7788-99aa-bbccddeeff00" } } ], "responses": { "200": { "description": "Project updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating project", "data": { "project": { "id": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign", "description": "Updated scope — includes mobile responsive design.", "customId": "PRJ-2026-001", "startDate": "2026-02-01", "endDate": "2026-06-30", "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "projectStatus": { "uuid": "aabbccdd-eeff-4012-8000-001122334455", "name": "In Progress", "color": "#E48642" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Project not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated project name." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Customer UUID, null to clear, or omit to leave unchanged." }, "statusUuid": { "type": "string", "format": "uuid", "description": "Status UUID from List project statuses." }, "description": { "type": "string", "description": "Updated description." }, "customId": { "type": "string", "description": "Updated external reference id." }, "startDate": { "type": "string", "format": "date", "description": "Updated start date." }, "endDate": { "type": "string", "format": "date", "description": "Updated end date." } } }, "example": { "description": "Updated scope — includes mobile responsive design." } } } } }, "delete": { "operationId": "projects_delete-project", "summary": "Soft-deletes a project.", "tags": [ "Projects" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID to delete.", "schema": { "type": "string", "format": "uuid", "example": "11223344-5566-7788-99aa-bbccddeeff00" } } ], "responses": { "200": { "description": "Project deleted successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on deleting project", "data": { "result": { "deleted": true } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Project not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/tasks": { "get": { "operationId": "tasks_list-tasks", "summary": "Returns a paginated list of tasks.", "tags": [ "Tasks" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Partial, case-insensitive match on task name.", "schema": { "type": "string" } }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "orderDirection", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "visibility", "in": "query", "required": false, "description": "Comma-separated visibility values. Defaults to firm-team and team-only when omitted.", "schema": { "type": "string", "example": "firm-team,team-only" } }, { "name": "priority", "in": "query", "required": false, "description": "Filter by priority.", "schema": { "type": "string" } }, { "name": "statusId", "in": "query", "required": false, "description": "Comma-separated status UUIDs or workspace-scoped numeric ids.", "schema": { "type": "string" } }, { "name": "assigneeId", "in": "query", "required": false, "description": "Comma-separated assignee UUIDs or workspace-scoped numeric ids.", "schema": { "type": "string" } }, { "name": "projects", "in": "query", "required": false, "description": "Comma-separated project UUIDs or workspace-scoped numeric ids.", "schema": { "type": "string" } }, { "name": "overduesOnly", "in": "query", "required": false, "description": "When true, returns only overdue tasks.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of tasks.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching tasks", "data": { "tasks": [ { "id": "22334455-6677-8899-aabb-ccddeeff0011", "name": "Review wireframes", "type": "INTERNAL_TASK", "description": "Review and approve wireframes before development.", "priority": "medium", "deadline": "2026-04-15", "customId": "TASK-1042", "visibility": "firm-team", "assignee": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "tags": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalRecords": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "tasks_create-task", "summary": "Creates a new task.", "tags": [ "Tasks" ], "description": "Required body field: `type`. If `assigneeId` is omitted, the partner-acting user is assigned. JSON only — no file attachments.", "responses": { "201": { "description": "Task created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating task", "data": { "task": { "id": "22334455-6677-8899-aabb-ccddeeff0011", "name": "Review wireframes", "type": "INTERNAL_TASK", "description": "Review and approve wireframes before development.", "priority": "medium", "deadline": "2026-04-15", "customId": "TASK-1042", "visibility": "firm-team", "assignee": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "tags": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed — for example missing type or mixed tag id kinds." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Task type identifier." }, "name": { "type": "string", "description": "Task title." }, "description": { "type": "string", "description": "Task details." }, "priority": { "type": "string", "description": "Priority level." }, "deadline": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)." }, "customId": { "type": "string", "description": "External reference id." }, "visibility": { "type": "string", "enum": [ "firm-team", "team-only", "firm-only" ], "description": "Visibility scope. INTERNAL_TASK is always created as firm-only." }, "assigneeId": { "type": "string", "format": "uuid", "description": "Assignee UUID or workspace-scoped numeric id." }, "statusId": { "type": "string", "format": "uuid", "description": "Task status UUID or workspace-scoped numeric id." }, "projectId": { "type": "string", "format": "uuid", "description": "Project UUID or workspace-scoped numeric id." }, "tags": { "type": "array", "items": {}, "description": "Array of tag UUIDs or numeric ids (homogeneous)." } }, "required": [ "type" ] }, "example": { "type": "INTERNAL_TASK", "name": "Review wireframes", "description": "Review and approve wireframes before development.", "priority": "medium", "deadline": "2026-04-15", "assigneeId": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "projectId": "11223344-5566-7788-99aa-bbccddeeff00" } } } } } }, "/partners/tasks/{uuid}": { "get": { "operationId": "tasks_get-task", "summary": "Retrieves a single task by UUID.", "tags": [ "Tasks" ], "description": "Firm-only tasks (including INTERNAL_TASK) return 404 unless you pass `visibility=firm-only` in the query string.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID.", "schema": { "type": "string", "format": "uuid", "example": "22334455-6677-8899-aabb-ccddeeff0011" } }, { "name": "visibility", "in": "query", "required": false, "description": "Include firm-only tasks when set to firm-only.", "schema": { "type": "string", "example": "firm-only" } } ], "responses": { "200": { "description": "The requested task.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching task", "data": { "task": { "id": "22334455-6677-8899-aabb-ccddeeff0011", "name": "Review wireframes", "type": "INTERNAL_TASK", "description": "Review and approve wireframes before development.", "priority": "medium", "deadline": "2026-04-15", "customId": "TASK-1042", "visibility": "firm-team", "assignee": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "tags": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Task not found or not visible with default visibility." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "tasks_update-task", "summary": "Updates an existing task. Only the fields you send are changed.", "tags": [ "Tasks" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID to update.", "schema": { "type": "string", "format": "uuid", "example": "22334455-6677-8899-aabb-ccddeeff0011" } } ], "responses": { "200": { "description": "Task updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating task", "data": { "task": { "id": "22334455-6677-8899-aabb-ccddeeff0011", "name": "Review wireframes", "type": "INTERNAL_TASK", "description": "Review and approve wireframes before development.", "priority": "high", "deadline": "2026-04-01", "customId": "TASK-1042", "visibility": "firm-team", "assignee": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "tags": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Task not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated task title." }, "description": { "type": "string", "description": "Updated details." }, "priority": { "type": "string", "description": "Updated priority." }, "deadline": { "type": "string", "format": "date", "description": "Updated due date." }, "assigneeId": { "type": "string", "format": "uuid", "description": "Assignee UUID or workspace-scoped numeric id." }, "statusId": { "type": "string", "format": "uuid", "description": "Status UUID or workspace-scoped numeric id." }, "projectId": { "type": "string", "format": "uuid", "description": "Project UUID or workspace-scoped numeric id." }, "tags": { "type": "array", "items": {}, "description": "Replacement tag list (array or JSON-encoded string)." } } }, "example": { "priority": "high", "deadline": "2026-04-01" } } } } }, "delete": { "operationId": "tasks_delete-task", "summary": "Deletes a task by UUID.", "tags": [ "Tasks" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID to delete.", "schema": { "type": "string", "format": "uuid", "example": "22334455-6677-8899-aabb-ccddeeff0011" } } ], "responses": { "200": { "description": "Task deleted successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on deleting task", "data": { "result": { "deleted": true } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Task not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/time-entries": { "get": { "operationId": "time-entries_list-time-entries", "summary": "Returns a paginated list of time entries.", "tags": [ "Time Entries" ], "description": "Soft-deleted entries are excluded. Default limit is 50.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } }, { "name": "peopleUuids", "in": "query", "required": false, "description": "Comma-separated person UUIDs.", "schema": { "type": "string", "example": "f1a2b3c4-d5e6-4789-a012-3456789abcde" } }, { "name": "projectUuids", "in": "query", "required": false, "description": "Comma-separated project UUIDs.", "schema": { "type": "string", "example": "11223344-5566-7788-99aa-bbccddeeff00" } }, { "name": "customerUuids", "in": "query", "required": false, "description": "Comma-separated customer UUIDs.", "schema": { "type": "string", "example": "dfa3219e-6af8-4c53-997a-037534f63a35" } }, { "name": "productServiceUuids", "in": "query", "required": false, "description": "Comma-separated product or service UUIDs.", "schema": { "type": "string", "example": "aa11bb22-cc33-dd44-ee55-ff6677889900" } }, { "name": "startDate", "in": "query", "required": false, "description": "Range start (YYYY-MM-DD). Must be paired with endDate.", "schema": { "type": "string", "format": "date", "example": "2026-03-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Range end (YYYY-MM-DD). Must be paired with startDate.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } } ], "responses": { "200": { "description": "Paginated list of time entries.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching time entries", "data": { "timeEntries": [ { "id": "33445566-7788-99aa-bbcc-ddeeff001122", "date": "2026-03-15", "minutes": 120, "description": "Wireframe review session", "billable": true, "wage": 45, "people": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "productService": { "uuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 50, "totalRecords": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "time-entries_create-time-entry", "summary": "Creates one or more time entry rows for a person.", "tags": [ "Time Entries" ], "description": "Required: `peopleUuid` and `timeEntries` array. Each row needs `date` (YYYY-MM-DD) and `minutes`. Setting `projectUuid` may auto-fill the matching customer.", "responses": { "201": { "description": "Time entries created successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Time entry created successfully", "data": { "timeEntry": { "id": "33445566-7788-99aa-bbcc-ddeeff001122", "date": "2026-03-15", "minutes": 120, "description": "Wireframe review session", "billable": true, "wage": 45, "people": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "productService": { "uuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed — for example daily minutes cap exceeded or missing peopleUuid." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peopleUuid": { "type": "string", "format": "uuid", "description": "Person UUID from the People API." }, "timeEntries": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Entry date (YYYY-MM-DD)." }, "minutes": { "type": "integer", "description": "Minutes logged." }, "description": { "type": "string", "description": "Optional notes." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Project UUID for this row." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Customer UUID for this row." }, "productServiceUuid": { "type": "string", "format": "uuid", "description": "Product or service UUID." }, "billable": { "type": "boolean", "description": "Whether the time is billable." }, "wage": { "type": "number", "description": "Wage rate for the row." } } }, "description": "Array of row objects to create." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Default project UUID applied to rows when not set per row." } }, "required": [ "peopleUuid", "timeEntries" ] }, "example": { "peopleUuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "projectUuid": "11223344-5566-7788-99aa-bbccddeeff00", "timeEntries": [ { "date": "2026-03-15", "minutes": 120, "description": "Wireframe review session", "billable": true } ] } } } } } }, "/partners/time-entries/{uuid}": { "get": { "operationId": "time-entries_get-time-entry", "summary": "Retrieves a single time entry by UUID.", "tags": [ "Time Entries" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Time entry UUID.", "schema": { "type": "string", "format": "uuid", "example": "33445566-7788-99aa-bbcc-ddeeff001122" } } ], "responses": { "200": { "description": "The requested time entry.", "content": { "application/json": { "example": { "status": "success", "message": "Time entry found successfully", "data": { "timeEntry": { "id": "33445566-7788-99aa-bbcc-ddeeff001122", "date": "2026-03-15", "minutes": 120, "description": "Wireframe review session", "billable": true, "wage": 45, "people": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "productService": { "uuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Time entry not found or soft-deleted." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "patch": { "operationId": "time-entries_update-time-entry", "summary": "Updates an existing time entry. Only the fields you send are changed.", "tags": [ "Time Entries" ], "description": "Entries in processed pay periods return 400. `projectUuid`, `customerUuid`, and `productServiceUuid` accept a UUID to set or null to clear.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Time entry UUID to update.", "schema": { "type": "string", "format": "uuid", "example": "33445566-7788-99aa-bbcc-ddeeff001122" } } ], "responses": { "200": { "description": "Time entry updated successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Time entry updated successfully", "data": { "timeEntry": { "id": "33445566-7788-99aa-bbcc-ddeeff001122", "date": "2026-03-15", "minutes": 90, "description": "Wireframe review session", "billable": true, "wage": 45, "people": { "uuid": "f1a2b3c4-d5e6-4789-a012-3456789abcde", "firstName": "Jane", "lastName": "Smith" }, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "productService": { "uuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "description": "Consulting services" }, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Entry is in a processed pay period or validation failed." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Time entry not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minutes": { "type": "integer", "description": "Updated minutes." }, "description": { "type": "string", "description": "Updated notes." }, "date": { "type": "string", "format": "date", "description": "Updated date (YYYY-MM-DD)." }, "billable": { "type": "boolean", "description": "Updated billable flag." }, "wage": { "type": "number", "description": "Updated wage rate." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Project UUID, or null to clear." }, "customerUuid": { "type": "string", "format": "uuid", "description": "Customer UUID, or null to clear." }, "productServiceUuid": { "type": "string", "format": "uuid", "description": "Product or service UUID, or null to clear." } } }, "example": { "minutes": 90, "description": "Extended review session" } } } } }, "delete": { "operationId": "time-entries_delete-time-entry", "summary": "Soft-deletes a time entry.", "tags": [ "Time Entries" ], "description": "Entries in processed pay periods cannot be deleted and return 400.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Time entry UUID to delete.", "schema": { "type": "string", "format": "uuid", "example": "33445566-7788-99aa-bbcc-ddeeff001122" } } ], "responses": { "200": { "description": "Time entry deleted successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Time entry deleted successfully", "data": { "result": { "deleted": true } } } } } }, "400": { "description": "Entry is in a processed pay period." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Time entry not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/expense-receipts": { "get": { "operationId": "expense-receipts_list-expense-receipts", "summary": "Returns a paginated list of expense receipts.", "tags": [ "Expense Receipts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Paginated list of expense receipts.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching pending receipts", "data": { "pendingReceipts": [ { "id": "44556677-8899-aabb-ccdd-eeff00112233", "amount": 45.99, "currency": "USD", "date": "2026-03-01", "description": "Team lunch", "matched": false, "receiptSplited": false, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking" }, "categoryAccount": { "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Meals & Entertainment" }, "vendor": null, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "tags": [], "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalRecords": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "expense-receipts_create-expense-receipt", "summary": "Creates an expense receipt, optionally with a receipt image.", "tags": [ "Expense Receipts" ], "description": "Send multipart/form-data with optional `receipt` file field plus text fields for metadata. UUID fields: accountUuid, categoryAccountUuid, expenseReportTypeUuid, vendorUuid, projectUuid, tagUuids (comma-separated), taxUuids (comma-separated).", "responses": { "201": { "description": "Expense receipt created.", "content": { "application/json": { "example": { "status": "success", "message": "Success on creating pending receipt", "data": { "pendingReceipt": { "id": "44556677-8899-aabb-ccdd-eeff00112233", "amount": 45.99, "currency": "USD", "date": "2026-03-01", "description": "Team lunch", "matched": false, "receiptSplited": false, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking" }, "categoryAccount": { "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Meals & Entertainment" }, "vendor": null, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "tags": [], "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Validation failed or split amounts do not balance." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt": { "type": "string", "description": "Receipt image file (multipart field, max 10 MB)." }, "amount": { "type": "number", "description": "Receipt amount." }, "date": { "type": "string", "format": "date", "description": "Receipt date (YYYY-MM-DD)." }, "description": { "type": "string", "description": "Notes or memo." }, "accountUuid": { "type": "string", "format": "uuid", "description": "Reimbursement account UUID." }, "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Expense category account UUID." }, "expenseReportTypeUuid": { "type": "string", "format": "uuid", "description": "Expense report type UUID." }, "vendorUuid": { "type": "string", "format": "uuid", "description": "Vendor UUID." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Project UUID." }, "tagUuids": { "type": "string", "description": "Comma-separated tag UUIDs." }, "taxUuids": { "type": "string", "description": "Comma-separated tax UUIDs." }, "receiptSplited": { "type": "boolean", "description": "Whether to split across categories." }, "splits": { "type": "array", "items": {}, "description": "Split rows when receiptSplited is true." } } }, "example": { "amount": 45.99, "date": "2026-03-01", "description": "Team lunch", "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "projectUuid": "11223344-5566-7788-99aa-bbccddeeff00" } } } } } }, "/partners/expense-receipts/unmatched": { "get": { "operationId": "expense-receipts_list-unmatched-expense-receipts", "summary": "Returns expense receipts that are not yet matched to a transaction.", "tags": [ "Expense Receipts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. The first page is 1.", "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records to return per page.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Paginated list of unmatched receipts.", "content": { "application/json": { "example": { "status": "success", "message": "Success on fetching unmatched receipts", "data": { "pendingReceipts": [ { "id": "44556677-8899-aabb-ccdd-eeff00112233", "amount": 45.99, "currency": "USD", "date": "2026-03-01", "description": "Team lunch", "matched": false, "receiptSplited": false, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking" }, "categoryAccount": { "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Meals & Entertainment" }, "vendor": null, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "tags": [], "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } ], "page": 1, "limit": 20, "totalRecords": 1 } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/expense-receipts/{uuid}": { "patch": { "operationId": "expense-receipts_update-expense-receipt", "summary": "Updates an unmatched expense receipt.", "tags": [ "Expense Receipts" ], "description": "Accepts multipart/form-data. Pass a new `receipt` file to replace the image. Returns 400 when the receipt is already matched.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Expense receipt UUID.", "schema": { "type": "string", "format": "uuid", "example": "44556677-8899-aabb-ccdd-eeff00112233" } } ], "responses": { "200": { "description": "Expense receipt updated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on updating pending receipt", "data": { "pendingReceipt": { "id": "44556677-8899-aabb-ccdd-eeff00112233", "amount": 52.5, "currency": "USD", "date": "2026-03-01", "description": "Team lunch", "matched": false, "receiptSplited": false, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking" }, "categoryAccount": { "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Meals & Entertainment" }, "vendor": null, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "tags": [], "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Receipt is already matched." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Expense receipt not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt": { "type": "string", "description": "Replacement receipt image (multipart field)." }, "amount": { "type": "number", "description": "Updated amount." }, "description": { "type": "string", "description": "Updated notes." }, "categoryAccountUuid": { "type": "string", "format": "uuid", "description": "Updated category account UUID." }, "vendorUuid": { "type": "string", "format": "uuid", "description": "Updated vendor UUID." }, "projectUuid": { "type": "string", "format": "uuid", "description": "Updated project UUID." } } }, "example": { "amount": 52.5, "description": "Team lunch (updated total)" } } } } }, "delete": { "operationId": "expense-receipts_delete-expense-receipt", "summary": "Deletes an unmatched expense receipt.", "tags": [ "Expense Receipts" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Expense receipt UUID to delete.", "schema": { "type": "string", "format": "uuid", "example": "44556677-8899-aabb-ccdd-eeff00112233" } } ], "responses": { "200": { "description": "Expense receipt deleted.", "content": { "application/json": { "example": { "status": "success", "message": "Success on deleting pending receipt", "data": { "result": { "deleted": true } } } } } }, "400": { "description": "Receipt is already matched." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Expense receipt not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/expense-receipts/{uuid}/match-manually": { "post": { "operationId": "expense-receipts_match-expense-receipt-manually", "summary": "Links an expense receipt to an expense transaction.", "tags": [ "Expense Receipts" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Expense receipt UUID to match.", "schema": { "type": "string", "format": "uuid", "example": "44556677-8899-aabb-ccdd-eeff00112233" } } ], "responses": { "200": { "description": "Receipt matched to transaction.", "content": { "application/json": { "example": { "status": "success", "message": "Success on matching receipt", "data": { "pendingReceipt": { "id": "44556677-8899-aabb-ccdd-eeff00112233", "amount": 45.99, "currency": "USD", "date": "2026-03-01", "description": "Team lunch", "matched": true, "receiptSplited": false, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking" }, "categoryAccount": { "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Meals & Entertainment" }, "vendor": null, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "tags": [], "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Receipt already matched or amounts do not align." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Receipt or transaction not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionUuid": { "type": "string", "format": "uuid", "description": "Transaction UUID from the Transactions API." } }, "required": [ "transactionUuid" ] }, "example": { "transactionUuid": "b7c8d9e0-f1a2-3456-bcde-678901234567" } } } } } }, "/partners/expense-receipts/{uuid}/unmatch": { "delete": { "operationId": "expense-receipts_unmatch-expense-receipt", "summary": "Removes the link between an expense receipt and its transaction.", "tags": [ "Expense Receipts" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Expense receipt UUID to unmatch.", "schema": { "type": "string", "format": "uuid", "example": "44556677-8899-aabb-ccdd-eeff00112233" } } ], "responses": { "200": { "description": "Receipt unmatched successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on unmatching receipt", "data": { "pendingReceipt": { "id": "44556677-8899-aabb-ccdd-eeff00112233", "amount": 45.99, "currency": "USD", "date": "2026-03-01", "description": "Team lunch", "matched": false, "receiptSplited": false, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking" }, "categoryAccount": { "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Meals & Entertainment" }, "vendor": null, "project": { "uuid": "11223344-5566-7788-99aa-bbccddeeff00", "name": "Website Redesign" }, "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "tags": [], "taxes": [], "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z" } } } } } }, "400": { "description": "Receipt is not matched to a transaction." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Expense receipt not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/connections": { "get": { "operationId": "connections_list-connections", "summary": "Lists every bank-feed connection for the workspace.", "tags": [ "Connections" ], "responses": { "200": { "description": "Connections retrieved.", "content": { "application/json": { "example": { "status": "success", "data": { "connections": [ { "id": "66778899-aabb-ccdd-eeff-001122334455", "provider": "plaid", "institutionName": "Chase", "status": "active", "lastSyncAt": "2026-01-28T14:22:30.000Z", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z", "accounts": [ { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking", "mask": "1234", "type": "depository" } ] } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/connections/connect-link": { "post": { "operationId": "connections_create-connect-link", "summary": "Mints a Plaid Hosted Link URL for connecting a new bank account.", "tags": [ "Connections" ], "description": "Hand `hostedLinkUrl` to a human to open in a browser. After they finish, call complete-connect-link with the same `linkToken`.", "responses": { "200": { "description": "Hosted Link session created.", "content": { "application/json": { "example": { "status": "success", "data": { "linkToken": "link-sandbox-xxxxxxxx", "hostedLinkUrl": "https://cdn.plaid.com/link/v2/stable/link.html?isWebview=true&token=…" } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/connections/connect-link/complete": { "post": { "operationId": "connections_complete-connect-link", "summary": "Polls whether the human finished Hosted Link and creates the connection when ready.", "tags": [ "Connections" ], "responses": { "200": { "description": "Poll result. status is pending, exited, or completed.", "content": { "application/json": { "example": { "status": "success", "data": { "status": "completed", "connection": { "id": "66778899-aabb-ccdd-eeff-001122334455", "provider": "plaid", "institutionName": "Chase", "status": "active", "lastSyncAt": "2026-01-28T14:22:30.000Z", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z", "accounts": [ { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking", "mask": "1234", "type": "depository" } ] } } } } } }, "400": { "description": "`linkToken` missing or invalid." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linkToken": { "type": "string", "description": "The same `linkToken` returned by create-connect-link." } }, "required": [ "linkToken" ] }, "example": { "linkToken": "link-sandbox-xxxxxxxx" } } } } } }, "/partners/connections/{uuid}": { "get": { "operationId": "connections_get-connection", "summary": "Retrieves a single connection by UUID.", "tags": [ "Connections" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Connection UUID from list connections.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connection retrieved.", "content": { "application/json": { "example": { "status": "success", "data": { "connection": { "id": "66778899-aabb-ccdd-eeff-001122334455", "provider": "plaid", "institutionName": "Chase", "status": "active", "lastSyncAt": "2026-01-28T14:22:30.000Z", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-28T14:22:30.000Z", "accounts": [ { "id": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Business Checking", "mask": "1234", "type": "depository" } ] } } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Connection not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/connections/{uuid}/revoke": { "patch": { "operationId": "connections_revoke-connection", "summary": "Revokes the provider access token so the connection stops syncing.", "tags": [ "Connections" ], "description": "Does not delete historical accounts or transactions.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Connection UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connection revoked.", "content": { "application/json": { "example": { "status": "success", "message": "Connection revoked successfully." } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Connection not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/connections/{uuid}/reconnect-link": { "post": { "operationId": "connections_create-reconnect-link", "summary": "Mints a Plaid Hosted Link URL in update mode for an existing connection.", "tags": [ "Connections" ], "description": "Plaid-connected accounts only. Re-authenticates the same connection instead of creating a duplicate.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Connection UUID to re-authenticate.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Update-mode Hosted Link session created.", "content": { "application/json": { "example": { "status": "success", "data": { "linkToken": "link-sandbox-yyyyyyyy", "hostedLinkUrl": "https://cdn.plaid.com/link/v2/stable/link.html?isWebview=true&token=…" } } } } }, "400": { "description": "Reconnect links are only supported for Plaid connections." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Connection not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reconciliations": { "post": { "operationId": "reconciliations_create-reconciliation", "summary": "Creates a draft reconciliation for an account statement period.", "tags": [ "Reconciliations" ], "responses": { "201": { "description": "Draft reconciliation created.", "content": { "application/json": { "example": { "status": "success", "message": "Reconciliation draft created successfully.", "data": { "reconciliation": { "id": "778899aa-bbcc-ddee-ff00-112233445566", "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "endingBalanceDate": "2026-03-31", "endingBalanceAmount": 12500.45, "status": "draft" } } } } } }, "400": { "description": "Validation failed or date-order conflict." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Account not found." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountUuid": { "type": "string", "format": "uuid", "description": "Bank/cash account UUID from list accounts." }, "endingBalanceDate": { "type": "string", "format": "date", "description": "Statement ending date (YYYY-MM-DD)." }, "endingBalanceAmount": { "type": "number", "description": "Statement ending balance." } }, "required": [ "accountUuid", "endingBalanceDate", "endingBalanceAmount" ] }, "example": { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "endingBalanceDate": "2026-03-31", "endingBalanceAmount": 12500.45 } } } } } }, "/partners/reconciliations/{uuid}/complete": { "patch": { "operationId": "reconciliations_complete-reconciliation", "summary": "Locks a draft reconciliation and marks reviewed journal entries reconciled.", "tags": [ "Reconciliations" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Reconciliation UUID from create.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reconciliation completed.", "content": { "application/json": { "example": { "status": "success", "message": "Reconciliation completed successfully.", "data": { "reconciliation": { "id": "778899aa-bbcc-ddee-ff00-112233445566", "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "endingBalanceDate": "2026-03-31", "endingBalanceAmount": 12500.45, "status": "completed" } } } } } }, "400": { "description": "Closed period or date-order violation." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "404": { "description": "Reconciliation not found or not a pending draft." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autoReconcile": { "type": "boolean", "description": "When true, also reviews and reconciles unreviewed entries in the period. Defaults to false." } } }, "example": { "autoReconcile": false } } } } } }, "/partners/opening-balance": { "get": { "operationId": "opening-balance_get-opening-balance", "summary": "Returns the current opening balance status, cutover date, and rows.", "tags": [ "Opening Balance" ], "responses": { "200": { "description": "Opening balance state retrieved.", "content": { "application/json": { "example": { "status": "success", "data": { "status": "published", "cutoverDate": "2026-03-01", "rows": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "accountName": "Business Checking", "accountType": "Assets", "debit": "12500.00", "credit": "0.00" }, { "accountUuid": "d4e5f6a7-b8c9-0123-defa-234567890123", "accountName": "Opening Balance Equity", "accountType": "Equity", "debit": "0.00", "credit": "12500.00" } ] } } } } }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] }, "post": { "operationId": "opening-balance_set-opening-balance", "summary": "Drafts and publishes the opening balance in one call.", "tags": [ "Opening Balance" ], "responses": { "200": { "description": "Opening balance published.", "content": { "application/json": { "example": { "status": "success", "message": "Opening balance published successfully." } } } }, "400": { "description": "Validation failed, unbalanced rows, or workspace is no longer onboarding." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "409": { "description": "An opening balance already exists and replaceExisting was not true." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "accountUuid": { "type": "string", "format": "uuid", "description": "Account UUID from the chart of accounts." }, "debit": { "type": "number", "description": "Debit amount (max 2 decimal places)." }, "credit": { "type": "number", "description": "Credit amount (max 2 decimal places)." } } }, "description": "Non-empty array of `{ accountUuid, debit, credit }`. Debits must equal credits." }, "replaceExisting": { "type": "boolean", "description": "When true, replaces an existing draft or published opening balance. Required to overwrite." } }, "required": [ "rows" ] }, "example": { "replaceExisting": true, "rows": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "debit": 12500, "credit": 0 }, { "accountUuid": "d4e5f6a7-b8c9-0123-defa-234567890123", "debit": 0, "credit": 12500 } ] } } } } } }, "/partners/workspace": { "patch": { "operationId": "workspace_update-workspace", "summary": "Updates workspace settings. Currently `cutoverDate` only.", "tags": [ "Workspace" ], "responses": { "200": { "description": "Workspace updated.", "content": { "application/json": { "example": { "status": "success", "message": "Workspace cutover date updated successfully.", "data": { "workspace": { "cutoverDate": "2026-03-01" } } } } } }, "400": { "description": "Missing/invalid cutoverDate, or cutover move rejected by guards." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cutoverDate": { "type": "string", "format": "date", "description": "YYYY-MM-DD cutover date." } }, "required": [ "cutoverDate" ] }, "example": { "cutoverDate": "2026-03-01" } } } } } }, "/partners/reports/trial-balance": { "post": { "operationId": "reports_generate-trial-balance", "summary": "Generates a trial balance as of a date.", "tags": [ "Reports" ], "description": "Filters are query parameters only. Required: endDate (YYYY-MM-DD).", "parameters": [ { "name": "endDate", "in": "query", "required": true, "description": "As-of date for the trial balance.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "startDate", "in": "query", "required": false, "description": "Period start. Defaults to fiscal-year start when omitted.", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "transactionStatus", "in": "query", "required": false, "description": "Filter transactions by review/reconciliation state.", "schema": { "type": "string", "enum": [ "all", "reviewed", "unreviewed", "reconciled", "unreconciled" ] } }, { "name": "accountUuids", "in": "query", "required": false, "description": "Comma-separated account UUIDs to include.", "schema": { "type": "string" } }, { "name": "tagUuids", "in": "query", "required": false, "description": "Comma-separated tag UUIDs to filter by.", "schema": { "type": "string" } }, { "name": "noTags", "in": "query", "required": false, "description": "Set to true to include only entries with no tags.", "schema": { "type": "string", "example": "true" } }, { "name": "accountType", "in": "query", "required": false, "description": "Restrict to a single account type.", "schema": { "type": "string", "enum": [ "Assets", "Liabilities", "Equity", "Income", "Expenses" ] } } ], "responses": { "200": { "description": "Trial balance report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating trial balance report", "data": { "report": { "endDate": "2026-03-31", "currency": "USD", "rows": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "accountName": "Business Checking", "accountType": "Assets", "debit": 12500, "credit": 0, "balance": 12500 } ] } } } } } }, "400": { "description": "Missing or invalid query parameters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/pnl": { "post": { "operationId": "reports_generate-profit-and-loss", "summary": "Generates a profit and loss (income statement) for a date range.", "tags": [ "Reports" ], "description": "Filters are query parameters only. Required: startDate and endDate (YYYY-MM-DD).", "parameters": [ { "name": "startDate", "in": "query", "required": true, "description": "Report period start.", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": true, "description": "Report period end.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "transactionStatus", "in": "query", "required": false, "description": "Filter transactions by review/reconciliation state.", "schema": { "type": "string", "enum": [ "all", "reviewed", "unreviewed", "reconciled", "unreconciled" ] } }, { "name": "categoryAccountUuids", "in": "query", "required": false, "description": "Comma-separated income/expense account UUIDs to filter categories.", "schema": { "type": "string" } }, { "name": "customerUuids", "in": "query", "required": false, "description": "Comma-separated customer UUIDs.", "schema": { "type": "string", "example": "dfa3219e-6af8-4c53-997a-037534f63a35" } }, { "name": "projectUuids", "in": "query", "required": false, "description": "Comma-separated project UUIDs.", "schema": { "type": "string", "example": "11223344-5566-7788-99aa-bbccddeeff00" } }, { "name": "isPnLByTag", "in": "query", "required": false, "description": "Set to true for a column-per-tag breakdown.", "schema": { "type": "string", "example": "true" } }, { "name": "reportYear", "in": "query", "required": false, "description": "Year basis for the report.", "schema": { "type": "string", "enum": [ "financial", "calendar" ] } } ], "responses": { "200": { "description": "Profit and loss report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating P&L report", "data": { "report": { "startDate": "2026-01-01", "endDate": "2026-03-31", "currency": "USD", "netProfit": 12000, "rows": [ { "accountUuid": "d4e5f6a7-b8c9-0123-defa-234567890123", "accountName": "Consulting Revenue", "accountType": "Income", "amount": 45000 } ] } } } } } }, "400": { "description": "Missing startDate/endDate or invalid filters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/balance-sheet": { "post": { "operationId": "reports_generate-balance-sheet", "summary": "Generates a balance sheet as of a date.", "tags": [ "Reports" ], "description": "Filters are query parameters only. Required: endDate (YYYY-MM-DD).", "parameters": [ { "name": "endDate", "in": "query", "required": true, "description": "As-of date for the balance sheet.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "startDate", "in": "query", "required": false, "description": "Prior-period comparison anchor when provided.", "schema": { "type": "string", "format": "date", "example": "2025-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "transactionStatus", "in": "query", "required": false, "description": "Filter transactions by review/reconciliation state.", "schema": { "type": "string", "enum": [ "all", "reviewed", "unreviewed", "reconciled", "unreconciled" ] } }, { "name": "accountUuids", "in": "query", "required": false, "description": "Comma-separated account UUIDs to include.", "schema": { "type": "string" } }, { "name": "tagUuids", "in": "query", "required": false, "description": "Comma-separated tag UUIDs to filter by.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance sheet report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating balance sheet report", "data": { "report": { "endDate": "2026-03-31", "currency": "USD", "sections": [ { "name": "Assets", "total": 85000, "accounts": [ { "accountUuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "accountName": "Business Checking", "balance": 12500 } ] } ] } } } } } }, "400": { "description": "Missing endDate or invalid filters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/aged-receivables": { "post": { "operationId": "reports_generate-aged-receivables", "summary": "Generates an AR aging report as of a date.", "tags": [ "Reports" ], "description": "Computes open invoice and credit-memo balances off the Accounts Receivable control account. Returns detail rows, customer summaries, bucket totals, and reconciliation against the control account GL balance. Filters are query parameters only.", "parameters": [ { "name": "asOfDate", "in": "query", "required": false, "description": "As-of date for aging (YYYY-MM-DD). Alias for endDate — supply one.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "endDate", "in": "query", "required": false, "description": "Alias for asOfDate.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "agingBasis", "in": "query", "required": false, "description": "Age documents off due date (default) or posted/document date.", "schema": { "type": "string", "enum": [ "dueDate", "postedDate", "documentDate" ] } }, { "name": "tagUuids", "in": "query", "required": false, "description": "Comma-separated tag UUIDs to filter by.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aged receivables report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating aged receivables report", "data": { "currency": "USD", "asOfDate": "2026-03-31", "rows": [ { "documentUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "documentNumber": "INV-1042", "counterpartyUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "counterpartyName": "Acme Corporation", "dueDate": "2026-03-31", "ageDays": 12, "bucket": "notYetOverdue", "amountDue": 2500 } ], "customers": [ { "counterpartyUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "counterpartyName": "Acme Corporation", "totals": { "notYetOverdue": 2500 } } ], "totals": { "notYetOverdue": 2500 }, "reconciliation": { "controlAccountBalance": 2500, "reportTotal": 2500 } } } } } }, "400": { "description": "Missing or invalid query parameters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/aged-payables": { "post": { "operationId": "reports_generate-aged-payables", "summary": "Generates an AP aging report as of a date.", "tags": [ "Reports" ], "description": "Payables mirror of aged receivables: open bills and vendor memos aged off the Accounts Payable control account. Query filters match aged receivables.", "parameters": [ { "name": "asOfDate", "in": "query", "required": false, "description": "As-of date for aging (YYYY-MM-DD). Alias for endDate — supply one.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "endDate", "in": "query", "required": false, "description": "Alias for asOfDate.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "agingBasis", "in": "query", "required": false, "description": "Age documents off due date (default) or posted/document date.", "schema": { "type": "string", "enum": [ "dueDate", "postedDate", "documentDate" ] } }, { "name": "tagUuids", "in": "query", "required": false, "description": "Comma-separated tag UUIDs to filter by.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aged payables report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating aged payables report", "data": { "currency": "USD", "asOfDate": "2026-03-31", "rows": [ { "documentUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "documentNumber": "BILL-2042", "counterpartyUuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "counterpartyName": "Acme Corporation", "dueDate": "2026-03-31", "ageDays": 12, "bucket": "notYetOverdue", "amountDue": 2500 } ], "vendors": [ { "counterpartyUuid": "aa11bb22-cc33-dd44-ee55-ff6677889901", "counterpartyName": "Office Supplies Co", "totals": { "between31And60": 900 } } ], "totals": { "between31And60": 900 }, "reconciliation": { "controlAccountBalance": 900, "reportTotal": 900 } } } } } }, "400": { "description": "Missing or invalid query parameters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/sales-by-product-service": { "post": { "operationId": "reports_generate-sales-by-product-service", "summary": "Summarizes invoice line revenue and quantity by product or service.", "tags": [ "Reports" ], "description": "Filters are query parameters only. Optional startDate and endDate bound the period.", "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Report period start.", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Report period end.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "transactionStatus", "in": "query", "required": false, "description": "Filter transactions by review/reconciliation state.", "schema": { "type": "string", "enum": [ "all", "reviewed", "unreviewed", "reconciled", "unreconciled" ] } }, { "name": "productUuids", "in": "query", "required": false, "description": "Comma-separated product/service UUIDs.", "schema": { "type": "string", "example": "aa11bb22-cc33-dd44-ee55-ff6677889900" } }, { "name": "reportType", "in": "query", "required": false, "description": "Accounting basis for the report.", "schema": { "type": "string", "enum": [ "accrual", "cash" ] } } ], "responses": { "200": { "description": "Sales by product/service report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating sales by product/service report", "data": { "productsSales": [ { "uuid": "aa11bb22-cc33-dd44-ee55-ff6677889900", "name": "Consulting services", "totalSales": 18000, "totalQuantity": 40 } ], "totals": { "totalSales": 18000, "totalQuantity": 40 } } } } } }, "400": { "description": "Invalid filters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/sales-by-customer": { "post": { "operationId": "reports_generate-sales-by-customer", "summary": "Summarizes invoice line revenue and quantity by customer.", "tags": [ "Reports" ], "description": "Sales-only aggregation of invoice line items over a date range. Distinct from customer activity, which nets all journal entries per customer.", "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Report period start.", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Report period end.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "transactionStatus", "in": "query", "required": false, "description": "Filter transactions by review/reconciliation state.", "schema": { "type": "string", "enum": [ "all", "reviewed", "unreviewed", "reconciled", "unreconciled" ] } }, { "name": "customerUuids", "in": "query", "required": false, "description": "Comma-separated customer UUIDs.", "schema": { "type": "string", "example": "dfa3219e-6af8-4c53-997a-037534f63a35" } }, { "name": "reportType", "in": "query", "required": false, "description": "Accounting basis for the report.", "schema": { "type": "string", "enum": [ "accrual", "cash" ] } } ], "responses": { "200": { "description": "Sales by customer report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating sales by customer report", "data": { "customersSales": [ { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "name": "Acme Corporation", "totalSales": 45000, "totalQuantity": 120 } ], "totals": { "totalSales": 45000, "totalQuantity": 120 } } } } } }, "400": { "description": "Invalid filters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/reports/customer-report": { "post": { "operationId": "reports_generate-customer-report", "summary": "Returns per-customer accounting activity with underlying journal entries.", "tags": [ "Reports" ], "description": "Nets every journal entry linked to each customer (invoices, payments, tax, manual journals, customer-linked expenses). Not a sales-only summary.", "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Report period start.", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Report period end.", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "currency", "in": "query", "required": false, "description": "Report currency. Defaults to workspace currency.", "schema": { "type": "string", "example": "USD" } }, { "name": "transactionStatus", "in": "query", "required": false, "description": "Filter transactions by review/reconciliation state.", "schema": { "type": "string", "enum": [ "all", "reviewed", "unreviewed", "reconciled", "unreconciled" ] } }, { "name": "customerUuids", "in": "query", "required": false, "description": "Comma-separated customer UUIDs to restrict the report.", "schema": { "type": "string", "example": "dfa3219e-6af8-4c53-997a-037534f63a35" } }, { "name": "projectUuids", "in": "query", "required": false, "description": "Comma-separated project UUIDs.", "schema": { "type": "string", "example": "11223344-5566-7788-99aa-bbccddeeff00" } }, { "name": "reportType", "in": "query", "required": false, "description": "Accounting basis for the report.", "schema": { "type": "string", "enum": [ "accrual", "cash" ] } } ], "responses": { "200": { "description": "Customer activity report generated.", "content": { "application/json": { "example": { "status": "success", "message": "Success on generating customer report", "data": { "categorized": [ { "customer": { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "customer": "Acme Corporation" }, "total": 2500, "openingBalance": 0, "endingBalance": 2500, "balanceChange": 2500, "debitTotal": 0, "creditTotal": 2500, "entries": [ { "entryUuid": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "invoiceUuid": "f6a7b8c9-d0e1-2345-fabc-456789012345", "transactionUuid": null, "billUuid": null, "date": "2026-03-01", "descriptionEntry": "Invoice payment applied", "entryType": "credit", "amountCredit": 2500, "amountDebit": 0, "amount": 2500, "balance": 2500, "account": { "uuid": "c8d9e0f1-a2b3-4567-cdef-789012345678", "name": "Accounts Receivable", "type": "Assets", "accountNumber": "1200", "code": "1200" } } ] } ], "filters": { "startDate": "2026-01-01", "endDate": "2026-03-31" } } } } } }, "400": { "description": "Invalid filters." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } }, "/partners/workspace-stats": { "get": { "operationId": "workspace-stats_get-workspace-stats", "summary": "Returns an aggregated business snapshot for the workspace.", "tags": [ "Workspace Stats" ], "description": "Computes cash, profitability, receivables, payables, tax obligations, and connection health. Omit include to return all blocks.", "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Comma-separated blocks to compute: workspace, cash, profitability, receivables, payables, taxObligations, connections. Omit for all blocks.", "schema": { "type": "string", "example": "cash,profitability,receivables" } } ], "responses": { "200": { "description": "Workspace stats retrieved successfully.", "content": { "application/json": { "example": { "status": "success", "message": "Success on retrieving workspace stats", "data": { "workspaceStats": { "workspace": { "uuid": "ws-uuid-example-0000-4000-8000-000000000001", "name": "Acme Workspace", "currency": "USD", "country": "US", "industry": "Professional Services", "fiscalYearMonth": 1, "dateFormat": "MM/dd/yyyy", "cutoverDate": "2025-01-01", "reportType": "accrual", "bookClosedThroughDate": null }, "cash": { "currentCash": 42500.75, "currentCashAsOf": "2026-06-21T08:00:00.000Z", "bankAndCashAssetsTotal": 45000, "creditCardLiabilitiesTotal": 2499.25, "accountSourceCounts": { "provider": 2, "reconciliation": 1, "book": 0, "missing": 0 }, "staleProviderBalanceAccountCount": 0 }, "profitability": { "currentMonth": { "startDate": "2026-06-01", "endDate": "2026-06-21", "revenue": 18500, "expenses": 11200, "netProfit": 7300 }, "rollingThreeMonths": { "averageMonthlyRevenue": 16000, "averageMonthlyExpenses": 10500, "averageMonthlyNetProfit": 5500, "netBurn": 5500, "runwayMonths": 7.7 } }, "receivables": { "totalOutstanding": 1085, "currentDueTotal": 1085, "overdueTotal": 0, "overdueCount": 0, "agingBuckets": { "notYetOverdue": 1085, "lessThanOrEqualTo30": 0, "between31And60": 0, "between61And90": 0, "moreThan90": 0 }, "topCustomersOutstanding": [ { "uuid": "dfa3219e-6af8-4c53-997a-037534f63a35", "name": "Acme Corporation", "outstanding": 1085 } ], "daysSalesOutstanding": 12 }, "payables": { "totalOutstanding": 3200, "outstandingBills": 3200, "dueInNext7Days": 800, "dueInNext30Days": 2400, "daysPayableOutstanding": 18 }, "taxObligations": { "isTaxRegistered": false, "taxRegime": null, "totalObligation": 0, "hasOverdueOrUpcomingFiling": false, "obligations": [], "lastFiledPeriodEnd": null }, "connections": { "totalCount": 2, "activeCount": 2, "disconnectedCount": 0, "revokedCount": 0, "accountsAwaitingReauthCount": 0, "staleConnectionCount24h": 0, "oldestLastSyncAt": "2026-06-21T06:30:00.000Z", "byProvider": { "plaid": 1, "akahu": 1 } }, "asOf": { "computedAt": "2026-06-21T12:00:00.000Z", "cacheTtlSeconds": 300, "cashAsOf": "2026-06-21T08:00:00.000Z", "currency": "USD", "fromCache": false } } } } } } }, "400": { "description": "Workspace context missing or invalid." }, "401": { "description": "Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token." }, "403": { "description": "The credential does not have access to this workspace or resource." }, "429": { "description": "Rate limit exceeded (100 requests per minute per clientId). Retry after the Retry-After header." } }, "security": [ { "hmacClientId": [], "hmacSignature": [], "hmacTimestamp": [], "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "hmacClientId": { "type": "apiKey", "in": "header", "name": "x-client-id" }, "hmacSignature": { "type": "apiKey", "in": "header", "name": "x-signature" }, "hmacTimestamp": { "type": "apiKey", "in": "header", "name": "x-timestamp" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }