# API reference > Every endpoint of the Prosaic REST API, with its parameters, request and response fields, and the matching Node SDK call. The Prosaic API is a REST API over HTTPS. It takes and returns JSON, and every path sits under one base URL: ```text https://app.prosaic.works/api/public/v1 ``` Each operation on these pages shows its HTTP route and the `prosaic-node` method that calls it. The method names are the operation IDs in the [OpenAPI document](/openapi.json), so code, docs and AI tools all use the same names. ## Authentication Send an API key or an OAuth access token as a bearer token on every request: ```bash curl https://app.prosaic.works/api/public/v1/me \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` API keys start with `prsk_` and act as the user who created them. Use an [OAuth app](/docs/apps/oauth-apps) when your product acts for other people's workspaces. [Authentication](/docs/getting-started/authentication) covers both, and how to choose a workspace with the `x-workspace-id` header when a user belongs to more than one. With the Node SDK, create one client and reuse it: ```ts import Prosaic from 'prosaic-node'; const prosaic = new Prosaic(process.env.PROSAIC_API_KEY!); ``` ## Requests - **Dates** are calendar dates in `YYYY-MM-DD` form, such as `2026-04-01`. Regional formats such as `01-04-2026` are rejected with a `400`. - **Amounts** are accepted as strings or numbers. Send decimal strings, such as `"1150.00"`, so nothing is lost to floating-point rounding. - **IDs** in paths, such as `entityId`, come from the list endpoints: `GET /entities` for entities and their tax rates, and `GET /entities/{entityId}/charts` for account codes. ## Responses Most endpoints wrap their result in `data`, with a `meta.count` where a count helps: ```json { "data": { "id": "…" } } ``` Paginated lists add a `pagination` object instead: ```json { "data": [], "pagination": { "currentPage": 1, "pageSize": 20, "totalCount": 0, "totalPages": 0, "hasNextPage": false, "hasPreviousPage": false } } ``` Ask for a page with the `page` (from 1) and `pageSize` query parameters. The SDK's list methods can page for you; see [pagination in the Node SDK](/docs/sdk/node#pagination). Creating a journal, running a report and uploading a file return the object itself, with no `data` wrapper. ## Errors Errors use standard HTTP status codes, with a JSON body that says what went wrong: ```json { "error": "Access denied to the specified entity" } ``` | Status | Meaning | | ------ | ---------------------------------------------------------------------------------------- | | `400` | The request is invalid: a missing field, a bad date, or a journal that does not balance. | | `401` | The API key or access token is missing, expired or revoked. | | `403` | The user cannot reach that workspace or entity. | | `404` | The record does not exist, or is not visible to this user. | | `500` | Something went wrong on Prosaic's side. Retry later, and tell us if it persists. | The Node SDK turns each status into an error class, such as `ValidationError` and `NotFoundError`; see [errors in the Node SDK](/docs/sdk/node#errors). ## For AI tools Every page of this reference is also published as Markdown: add `.md` to its URL. [`/docs/api/llms-full.txt`](/docs/api/llms-full.txt) holds the whole reference in one file, and the [developer MCP server](/docs/ai/build-with-ai) looks operations up by name, method or path. ## Chart reporting assignments Discover workspace choices with `GET /api/public/v1/report-categories`, or entity choices with `GET /api/public/v1/entities/{entityId}/report-categories`. The saved reporting group/category pair is authoritative in activated workspaces. Stored `subtype` remains compatibility data, not a promise that reports derive from it. Trial-balance `groupBy=subtype` remains available pending its separate retirement. See [Chart of accounts](/docs/ledger/chart-of-accounts) for required write choices, permissions and conflict recovery. ## Resources - [User](https://developer.prosaic.works/docs/api/user.md): The user an API key or access token acts as, and the workspaces they belong to. - Get current user information: `GET /api/public/v1/me`, `prosaic.me.retrieve()` - [Entities](https://developer.prosaic.works/docs/api/entities.md): The businesses whose books you keep. Each entity carries its own tax rates and bank accounts. - List entities: `GET /api/public/v1/entities`, `prosaic.entities.list(params)` - Create an entity: `POST /api/public/v1/entities`, `prosaic.entities.create(params)` - [Chart of accounts](https://developer.prosaic.works/docs/api/chart-of-accounts.md): Chart of accounts templates, each entity's own accounts, and the global account library templates are built from. - List all chart of accounts templates: `GET /api/public/v1/charts`, `prosaic.charts.list()` - Get chart of accounts template accounts: `GET /api/public/v1/charts/{chartId}`, `prosaic.charts.listAccounts(chartId, params)` - List approved Xero report-code mappings: `GET /api/public/v1/xero-report-mappings`, `prosaic.charts.listXeroReportMappings()` - Create a chart of accounts template: `POST /api/public/v1/charts`, `prosaic.charts.create(params)` - Add a single account to a chart of accounts template: `POST /api/public/v1/charts/{chartId}/accounts`, `prosaic.charts.createAccount(chartId, params)` - Update a chart of accounts template: `POST /api/public/v1/charts/{chartId}/update`, `prosaic.charts.update(chartId, params)` - Update a single account in a chart of accounts template: `POST /api/public/v1/charts/{chartId}/accounts/{accountId}/update`, `prosaic.charts.updateAccount(chartId, accountId, params)` - Delete a chart of accounts template: `POST /api/public/v1/charts/{chartId}/delete`, `prosaic.charts.del(chartId)` - Delete a single account from a chart of accounts template: `POST /api/public/v1/charts/{chartId}/accounts/{accountId}/delete`, `prosaic.charts.deleteAccount(chartId, accountId, params)` - List chart of accounts for an entity: `GET /api/public/v1/entities/{entityId}/charts`, `prosaic.entityAccounts.list(entityId, params)` - Create a child account in the chart of accounts: `POST /api/public/v1/entities/{entityId}/charts`, `prosaic.entityAccounts.create(entityId, params)` - Update an entity account: `POST /api/public/v1/entities/{entityId}/charts/{accountId}/update`, `prosaic.entityAccounts.update(entityId, accountId, params)` - Restore a hidden/excluded template account: `POST /api/public/v1/entities/{entityId}/charts/excluded/{templateAccountId}/restore`, `prosaic.entityAccounts.restore(entityId, templateAccountId)` - Reset an entity account to template defaults: `POST /api/public/v1/entities/{entityId}/charts/{accountId}/reset`, `prosaic.entityAccounts.reset(entityId, accountId)` - Delete or hide an entity account: `POST /api/public/v1/entities/{entityId}/charts/{accountId}/delete`, `prosaic.entityAccounts.del(entityId, accountId)` - List report groups and categories for the authorised workspace: `GET /api/public/v1/report-categories`, `prosaic.reportCategories.listForWorkspace()` - List report groups and categories for an entity: `GET /api/public/v1/entities/{entityId}/report-categories`, `prosaic.reportCategories.list(entityId)` - List all global accounts: `GET /api/public/v1/global-accounts`, `prosaic.globalAccounts.list()` - [Journals](https://developer.prosaic.works/docs/api/journals.md): Manual journals: post or draft them, list them, attach files and void them. - List manual journals: `GET /api/public/v1/entities/{entityId}/journals`, `prosaic.journals.list(entityId, params)` - Create a manual journal: `POST /api/public/v1/entities/{entityId}/journals`, `prosaic.journals.create(entityId, params)` - Create several manual journals at once: `POST /api/public/v1/entities/{entityId}/journals/bulk`, `prosaic.journals.createBulk(entityId, params)` - Attach files to an existing journal: `POST /api/public/v1/entities/{entityId}/journals/{journalId}/attachments`, `prosaic.journals.attachFiles(entityId, journalId, params)` - Void a journal: `PATCH /api/public/v1/entities/{entityId}/journals/{journalId}/void`, `prosaic.journals.void(entityId, journalId)` - [Transactions](https://developer.prosaic.works/docs/api/transactions.md): Bank transactions: list them, reconcile them one at a time or in bulk, and reverse a reconciliation. - List bank transactions: `GET /api/public/v1/entities/{entityId}/transactions`, `prosaic.transactions.list(entityId, params)` - Reconcile bank transactions (bulk or single): `POST /api/public/v1/transactions/reconcile`, `prosaic.transactions.reconcileBulk(params)` - Reconcile a bank transaction: `POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reconcile`, `prosaic.transactions.reconcile(entityId, transactionId, params)` - Reverse a bank transaction reconciliation: `POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reverse`, `prosaic.transactions.reverse(entityId, transactionId, params)` - [Bank accounts](https://developer.prosaic.works/docs/api/bank-accounts.md): Link a client's bank accounts to an entity, or create CSV accounts and fill them with transactions from your own systems. - Create a CSV bank account and import transactions into it: `POST /api/public/v1/entities/{entityId}/bank-accounts/import`, `prosaic.bankAccounts.createWithTransactions(entityId, params)` - Link bank accounts to an entity: `POST /api/public/v1/entities/{entityId}/bank-accounts`, `prosaic.bankAccounts.link(entityId, params)` - Import transactions into a CSV bank account: `POST /api/public/v1/entities/{entityId}/bank-accounts/{bankAccountId}/import`, `prosaic.bankAccounts.importTransactions(entityId, bankAccountId, params)` - [Reports](https://developer.prosaic.works/docs/api/reports.md): Trial balance, profit and loss, balance sheet, current accounts, depreciation schedule and the general ledger. - Get general ledger grouped by account: `GET /api/public/v1/entities/{entityId}/general-ledger/account`, `prosaic.generalLedger.byAccount(entityId, params)` - Get general ledger as flat entry list: `GET /api/public/v1/entities/{entityId}/general-ledger/transaction`, `prosaic.generalLedger.byTransaction(entityId, params)` - Get ledger entries: `GET /api/public/v1/entities/{entityId}/ledger`, `prosaic.ledger.list(entityId, params)` - Get trial balance report: `GET /api/public/v1/entities/{entityId}/trial-balance`, `prosaic.reports.trialBalance(entityId, params)` - Get profit & loss report: `GET /api/public/v1/entities/{entityId}/reports/profit-loss`, `prosaic.reports.profitLoss(entityId, params)` - Get balance sheet report: `GET /api/public/v1/entities/{entityId}/reports/balance-sheet`, `prosaic.reports.balanceSheet(entityId, params)` - Get current accounts report: `GET /api/public/v1/entities/{entityId}/reports/current-accounts`, `prosaic.reports.currentAccounts(entityId, params)` - Get depreciation schedule report: `GET /api/public/v1/entities/{entityId}/reports/depreciation-schedule`, `prosaic.reports.depreciationSchedule(entityId, params)` - [GST returns](https://developer.prosaic.works/docs/api/gst-returns.md): GST returns and their IRD box amounts, for one entity or across the workspace. - List GST returns across the workspace: `GET /api/public/v1/gst-returns`, `prosaic.gstReturns.list(params)` - List GST returns for an entity: `GET /api/public/v1/entities/{entityId}/gst-returns`, `prosaic.gstReturns.listForEntity(entityId, params)` - Get a single GST return with its IRD box amounts: `GET /api/public/v1/entities/{entityId}/gst-returns/{gstReturnId}`, `prosaic.gstReturns.retrieve(entityId, gstReturnId)` - [Contacts](https://developer.prosaic.works/docs/api/contacts.md): Customers and suppliers: create, update, archive, restore and delete them. - List contacts: `GET /api/public/v1/contacts`, `prosaic.contacts.list(params)` - Get a contact: `GET /api/public/v1/entities/{entityId}/contacts/{contactId}`, `prosaic.contacts.retrieve(entityId, contactId)` - Create a contact: `POST /api/public/v1/entities/{entityId}/contacts`, `prosaic.contacts.create(entityId, params)` - Update a contact: `PATCH /api/public/v1/entities/{entityId}/contacts/{contactId}`, `prosaic.contacts.update(entityId, contactId, params)` - Restore a contact: `POST /api/public/v1/entities/{entityId}/contacts/{contactId}/restore`, `prosaic.contacts.restore(entityId, contactId, params)` - Delete a contact: `DELETE /api/public/v1/entities/{entityId}/contacts/{contactId}`, `prosaic.contacts.del(entityId, contactId)` - Archive a contact: `POST /api/public/v1/entities/{entityId}/contacts/{contactId}/archive`, `prosaic.contacts.archive(entityId, contactId, params)` - [Invoices](https://developer.prosaic.works/docs/api/invoices.md): Finalised invoices: create, read and list them. - List invoices: `GET /api/public/v1/invoices`, `prosaic.invoices.list(params)` - Get an invoice by ID for an entity: `GET /api/public/v1/entities/{entityId}/invoices/{invoiceId}`, `prosaic.invoices.retrieve(entityId, invoiceId)` - Create a finalised invoice: `POST /api/public/v1/entities/{entityId}/invoices`, `prosaic.invoices.create(entityId, params)` - [Fixed assets](https://developer.prosaic.works/docs/api/fixed-assets.md): Fixed assets and their types, for depreciation. - List fixed asset types (categories) for an entity: `GET /api/public/v1/entities/{entityId}/fixed-asset-types`, `prosaic.fixedAssetTypes.list(entityId)` - Create a new fixed asset type (category): `POST /api/public/v1/entities/{entityId}/fixed-asset-types`, `prosaic.fixedAssetTypes.create(entityId, params)` - List fixed assets for an entity: `GET /api/public/v1/entities/{entityId}/fixed-assets`, `prosaic.fixedAssets.list(entityId, params)` - Get a single fixed asset by ID: `GET /api/public/v1/entities/{entityId}/fixed-assets/{assetId}`, `prosaic.fixedAssets.retrieve(entityId, assetId)` - Create a new fixed asset: `POST /api/public/v1/entities/{entityId}/fixed-assets`, `prosaic.fixedAssets.create(entityId, params)` - Update a draft fixed asset: `PATCH /api/public/v1/entities/{entityId}/fixed-assets/{assetId}`, `prosaic.fixedAssets.update(entityId, assetId, params)` - [Files](https://developer.prosaic.works/docs/api/files.md): Upload files and list them, to attach to journals. - List files: `GET /api/public/v1/entities/{entityId}/files`, `prosaic.files.list(entityId, params)` - Upload a file: `POST /api/public/v1/entities/{entityId}/files/upload`, `prosaic.files.upload(entityId, file)` - [Dimensions](https://developer.prosaic.works/docs/api/dimensions.md): Tracking categories, such as Property or Department, whose options tag journal lines. - List dimensions: `GET /api/public/v1/entities/{entityId}/dimensions`, `prosaic.dimensions.list(entityId)` - [Clients](https://developer.prosaic.works/docs/api/clients.md): An accounting practice's clients, their bank accounts and transactions, and onboarding links. - List clients: `GET /api/public/v1/clients`, `prosaic.clients.list(params)` - List client's bank transactions: `GET /api/public/v1/clients/{clientId}/transactions`, `prosaic.clients.listTransactions(clientId, params)` - List client's bank accounts: `GET /api/public/v1/clients/{clientId}/bank-accounts`, `prosaic.clients.listBankAccounts(clientId)` - Create a client: `POST /api/public/v1/clients`, `prosaic.clients.create(params)` - Create onboarding link: `POST /api/public/v1/clients/{clientId}/onboarding`, `prosaic.clients.createOnboardingLink(clientId, params)` - [Rules](https://developer.prosaic.works/docs/api/rules.md): Rules that act on bank transactions when their conditions match. - List rules: `GET /api/public/v1/rules`, `prosaic.rules.list(params)` - Get a rule by ID: `GET /api/public/v1/rules/{ruleId}`, `prosaic.rules.retrieve(ruleId)` - Create a rule: `POST /api/public/v1/rules`, `prosaic.rules.create(params)` - Update a rule: `PATCH /api/public/v1/rules/{ruleId}`, `prosaic.rules.update(ruleId, params)` - Soft-delete a rule: `DELETE /api/public/v1/rules/{ruleId}`, `prosaic.rules.del(ruleId)` - [Scheduled tasks](https://developer.prosaic.works/docs/api/scheduled-tasks.md): Prosaic AI tasks that run a prompt unattended on a schedule, and running one now. - List scheduled tasks: `GET /api/public/v1/scheduled-tasks`, `prosaic.scheduledTasks.list()` - Get a scheduled task: `GET /api/public/v1/scheduled-tasks/{id}`, `prosaic.scheduledTasks.retrieve(id)` - Create a scheduled task: `POST /api/public/v1/scheduled-tasks`, `prosaic.scheduledTasks.create(params)` - Update a scheduled task: `PATCH /api/public/v1/scheduled-tasks/{id}`, `prosaic.scheduledTasks.update(id, params)` - Run a scheduled task now: `POST /api/public/v1/scheduled-tasks/{id}/run`, `prosaic.scheduledTasks.run(id)` - Delete a scheduled task: `DELETE /api/public/v1/scheduled-tasks/{id}`, `prosaic.scheduledTasks.del(id)` - [Extensions](https://developer.prosaic.works/docs/api/extensions.md): Outbound requests made through an extension's connections, with the credential attached server-side. - Make an outbound request through an extension connection: `POST /api/public/v1/extensions/{extensionId}/http`, `prosaic.extensions.request(extensionId, params)` - [Change sets](https://developer.prosaic.works/docs/api/change-sets.md): Proposed journals and reconciliations that an admin approves before they reach the ledger. - Submit a change-set (proposed financial writes) for an entity: `POST /api/public/v1/entities/{entityId}/change-sets`, `prosaic.changeSets.create(entityId, params)` - [Version](https://developer.prosaic.works/docs/api/version.md): The API version. - API version information: `GET /api/public/v1`, `prosaic.version.retrieve()` --- # User > The user an API key or access token acts as, and the workspaces they belong to. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## Get current user information `GET /api/public/v1/me` SDK: `prosaic.me.retrieve()` Returns the authenticated user's information including their workspaces and whether they have connected bank accounts. This endpoint is intended for the Expenses app to determine: - User type (accountant vs individual) based on workspace roles - Whether to prompt for bank account connection - Which workspaces/clients the user has access to ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `workspaces` (array of objects, required) - `id` (string, required) - `name` (string, required) - `role` (string, required): One of: `client`, `standard_user`, `admin`, `accountant`, `advisor`, `workspace_owner`. - `subscriptionState` (string, required) - `hasConnectedBankAccounts` (boolean, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - Invalid or missing API key/token - `error` (string) - `404`: User not found - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.me.retrieve(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/me \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Entities > The businesses whose books you keep. Each entity carries its own tax rates and bank accounts. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List entities `GET /api/public/v1/entities` SDK: `prosaic.entities.list(params)` Returns all entities that the authenticated user has access to within their workspace. Optionally filter by entity ID or client ID. **Important**: This endpoint is the primary source for entity-level reference data including: - `taxRates[]` — Available tax rates (GST codes) for each entity. Use `taxRates[].code` when reconciling transactions or creating chart accounts. - `bankAccounts[]` — Linked bank accounts for each entity. Each bank account includes its linked GL account at `bankAccounts[].entityAccount` (use `entityAccount.id` when posting journals or reconciling against the bank). - `clients[]` — Client users associated with each entity. **Chart of accounts**: The `currentTemplateId` field references the *template* the entity was provisioned from — it is **not** the entity's actual chart of accounts. To fetch the entity's GL accounts (including bank-account-linked accounts and any custom accounts), call `GET /api/public/v1/entities/{entityId}/charts`. ### Query parameters - `entityId` (string): Filter entities by specific entity ID. - `clientId` (string): Filter entities by client user ID (returns entities where the user is a member) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `type` (string, required) - `currentTemplateId` (string, nullable, required) - `defaultTaxAccountId` (string, nullable, required) - `createdAt` (string, date-time, required) - `isGstRegistered` (boolean, nullable, required) - `gstPeriodMonths` (number, nullable, required) - `gstBasis` (string, nullable, required) - `financialYearStartMonth` (number, required) - `currency` (string, required) - `bankAccounts` (array of objects, required) - `id` (string, required) - `entityId` (string, nullable, required) - `externalId` (string, required) - `name` (string, required) - `alias` (string, nullable, required) - `institution` (string, nullable, required) - `accountNumber` (string, nullable, required) - `logoUrl` (string, nullable, required) - `type` (string, required) - `sourceType` (string, nullable, required) - `entityAccount` (object, nullable, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `clients` (array of objects, required) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `taxRates` (array of objects, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `meta` (object) - `count` (number, required) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.entities.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create an entity `POST /api/public/v1/entities` SDK: `prosaic.entities.create(params)` Creates a new entity in the workspace associated with the API key. Supports full entity configuration including GST settings, client assignment, and bank account linking. ### Request body Content type: `application/json` - `accountTemplateId` (string, required) - `type` (string, required): One of: `individual`, `company`, `trust`, `partnership`, `rental`, `other`. - `name` (string, required) - `workspaceDimensionIds` (array of strings) - `isGstRegistered` (boolean) - `areGstReportsAutomated` (boolean) - `gstNumber` (string) - `irdNumber` (string) - `gstPeriod` (string): One of: `2`, `1`, `3`, `6`, `12`. - `gstFilingStartDate` (string) - `nzbn` (string) - `industryCode` (string) - `conversionDate` (string, nullable) - `clientIds` (array of strings) - `bankAccountIds` (array of strings) - `isDemo` (boolean) - `demoType` (string) - `parties` (array of objects) - `name` (string, required) - `roles` (array of strings, required) - `id` (string) - `isOrganisation` (boolean) - `nzbn` (string) - `shares` (number) - `source` (string): One of: `manual`, `nzbn`. - `sourceReferences` (array of objects) - `source` (string, required): One of: `nzbn-role`. - `sourceEntityNzbn` (string, required) - `uniqueIdentifier` (string, required) - `registeredAddress` (string) - `postalAddress` (string) - `email` (string) - `phone` (string) - `website` (string) - `tradingNames` (array of strings) - `registrationDate` (string) - `entityStatus` (string) - `entityTypeDescription` (string) - `companyNumber` (string) ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `type` (string, required) - `currentTemplateId` (string, nullable, required) - `defaultTaxAccountId` (string, nullable, required) - `createdAt` (string, date-time, required) - `isGstRegistered` (boolean, nullable, required) - `gstPeriodMonths` (number, nullable, required) - `gstBasis` (string, nullable, required) - `financialYearStartMonth` (number, required) - `currency` (string, required) - `bankAccounts` (array of objects, required) - `id` (string, required) - `entityId` (string, nullable, required) - `externalId` (string, required) - `name` (string, required) - `alias` (string, nullable, required) - `institution` (string, nullable, required) - `accountNumber` (string, nullable, required) - `logoUrl` (string, nullable, required) - `type` (string, required) - `sourceType` (string, nullable, required) - `entityAccount` (object, nullable, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `clients` (array of objects, required) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `taxRates` (array of objects, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `meta` (object) - `count` (number, required) - `400`: Validation failed, or system account setup is missing or invalid (SYSTEM_ACCOUNT_VALIDATION). - `error` (string) - `code` (string) - `details` (array of objects) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden. Either the token is scoped to a single entity (`TOKEN_ENTITY_SCOPE`), or the token's workspace role is not a firm staff role — advisor, admin or workspace owner (`INSUFFICIENT_ROLE`). - `error` (string) - `code` (string) - `404`: Workspace not found or access denied - `error` (string) - `code` (string) - `409`: One or more of the supplied `bankAccountIds` is already linked to a different entity (`BANK_ACCOUNT_ASSIGNED_TO_DIFFERENT_ENTITY`). Bank accounts may only be linked while unassigned. - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.entities.create({ accountTemplateId: 'ACCOUNT_TEMPLATE_ID', type: 'individual', name: 'Example Ltd', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "accountTemplateId": "ACCOUNT_TEMPLATE_ID", "type": "individual", "name": "Example Ltd" }' ``` --- # Chart of accounts > Chart of accounts templates, each entity's own accounts, and the global account library templates are built from. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List all chart of accounts templates `GET /api/public/v1/charts` SDK: `prosaic.charts.list()` Returns all chart of accounts templates in the workspace. Requires API key authentication. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `accountCount` (number, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - Invalid or missing API key ### Example (Node SDK) ```ts const { data } = await prosaic.charts.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/charts \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get chart of accounts template accounts `GET /api/public/v1/charts/{chartId}` SDK: `prosaic.charts.listAccounts(chartId, params)` Returns paginated accounts from a chart-of-accounts **template** (the read-only blueprint entities are provisioned from). When `includeHidden=true`, also returns global accounts not in the template with `isIncluded=false`. Requires API key authentication. Each included account also exposes its nullable confirmed systemRole and saved reportGroup/reportCategory summaries. subtype remains the legacy compatibility value, independent of report placement. Hidden global suggestions have systemRole=null and no saved report assignment. **Important**: The `id` values returned by this endpoint are *template account* IDs (`TemplateAccount.id`). They are **not** the IDs of an entity's actual GL accounts — do not use them to post journals or look up reconciliation activity. To fetch the chart of accounts for a specific entity (including bank-account-linked accounts and any custom accounts), use `GET /api/public/v1/entities/{entityId}/charts`. The bank-account-to-GL linkage is also embedded on each entity's bank account at `bankAccounts[].entityAccount` in the `GET /api/public/v1/entities` response. **Tax codes**: The `taxCode` field is returned as the human-readable tax *name* (e.g. `"15% GST on Income"`, or `"No GST"` when unset), not the machine code. When creating or updating a template you must pass the machine *code* instead (`NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`), so convert the name back to its code before writing. ### Path parameters - `chartId` (string, required) ### Query parameters - `includeHidden` (boolean): When true, includes global accounts not in the template (with isIncluded=false). Disables pagination. Default: `false`. - `page` (integer): Page number (starts at 1). Ignored when includeHidden=true. Default: `1`. - `pageSize` (integer): Number of items per page. Ignored when includeHidden=true. Default: `20`. ### Responses - `200`: Successful response - `templateUpdatedAt` (string, required) - `data` (array of objects, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Bad request - missing or invalid parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified chart - `404`: Chart not found ### Example (Node SDK) ```ts const page = await prosaic.charts.listAccounts(chartId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/charts/$CHART_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List approved Xero report-code mappings `GET /api/public/v1/xero-report-mappings` SDK: `prosaic.charts.listXeroReportMappings()` Look up Xero Report Code values in the authorised workspace's country. Each entry gives the Prosaic report group and optional category. Only approved NZ placements that are valid in the current taxonomy are returned. Other countries return an empty lookup. Missing codes require review. ### Responses - `200`: Successful response - `data` (object, required) - `country` (string, required) - `mappings` (object, required) - `meta` (object) - `count` (number, required) - `401`: Missing or invalid bearer authentication - `403`: Workspace or API access denied - `404`: Authorised workspace unavailable - `500`: Unexpected failure loading mappings ### Example (Node SDK) ```ts const { data } = await prosaic.charts.listXeroReportMappings(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/xero-report-mappings \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a chart of accounts template `POST /api/public/v1/charts` SDK: `prosaic.charts.create(params)` Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape. In nonactivated workspaces, creates a chart from global definitions. Every system global account (see `GET /api/public/v1/global-accounts`, `isSystem: true`) must be present in `accounts` with `isIncluded: true` — otherwise the request fails with `SYSTEM_ACCOUNT_VALIDATION` listing all missing accounts. Set `includeSystemAccounts: true` to have any omitted system accounts added automatically from their global definitions. Requires API key authentication. **Tax codes**: The `taxCode` field expects the machine code, not the human-readable tax name. Passing a name (e.g. `"15% GST on Income"`) is stored verbatim and resolves to null wherever the code is looked up. Valid codes are `NZ_GST_15_INC` (15% GST on Income), `NZ_GST_15_EXP` (15% GST on Expenses), `NZ_GST_0_NONE` (No GST), and `NZ_GST_0_ZERO` (Zero-rated GST). Omit `taxCode` or set it to null to default to `NZ_GST_0_NONE` (No GST). **Description defaults**: `description` is optional per account; omitting it (or null) leaves the account description empty. ### Request body Content type: `application/json` - `name` (string, required) - `accounts` (array of objects, required) - `code` (string, required) - `name` (string, required) - `isIncluded` (boolean, required) - `type` (string) - `subtype` (string, nullable) - `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`. - `description` (string, nullable) - `mappedCode` (string, nullable) - `parentCode` (string, nullable) - `id` (string) - `clientKey` (string) - `groupKey` (string) - `categoryKey` (string, nullable) - `systemRole` (string, nullable) - `expectedUpdatedAt` (string) - `description` (string) - `includeSystemAccounts` (boolean) ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `meta` (object) - `count` (number, required) - `400`: Validation error. `SYSTEM_ACCOUNT_VALIDATION` includes `details.missingAccounts` listing every required system account absent from the payload. - `error` (string, required) - `code` (string, required) - `details` (object) - `missingAccounts` (array of objects) - `code` (string) - `name` (string) - `401`: Unauthorized ### Example (Node SDK) ```ts const { data } = await prosaic.charts.create({ name: 'Example Ltd', accounts: [ { code: '200', name: 'Example Ltd', isIncluded: true, }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/charts \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "accounts": [ { "code": "200", "name": "Example Ltd", "isIncluded": true } ] }' ``` ## Add a single account to a chart of accounts template `POST /api/public/v1/charts/{chartId}/accounts` SDK: `prosaic.charts.createAccount(chartId, params)` Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape. Adds one account to a chart of accounts template without resending the full account list. To add a legacy top-level account in a nonactivated workspace, provide its global account `code`; to add a legacy child account, provide `code`, `name`, and `parentCode` (the child code must be `{parentCode}.{digits}`). Activated rows use the explicit fields above and remain subject to review before reporting propagation. Requires bearer authentication. ### Path parameters - `chartId` (string, required) ### Request body Content type: `application/json` - `code` (string, required) - `name` (string, nullable) - `parentCode` (string, nullable) - `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`. - `description` (string, nullable) - `mappedCode` (string, nullable) - `id` (string) - `clientKey` (string) - `groupKey` (string) - `categoryKey` (string, nullable) - `systemRole` (string, nullable) - `expectedUpdatedAt` (string) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, nullable, required) - `code` (string, required) - `entitiesUpdated` (number, required) - `meta` (object) - `count` (number, required) - `400`: Validation error or business rule violation - `401`: Unauthorized - `404`: Chart not found - `409`: An account with this code already exists, or the code conflicts with a custom entity account ### Example (Node SDK) ```ts const { data } = await prosaic.charts.createAccount(chartId, { code: '200', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/accounts \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "200" }' ``` ## Update a chart of accounts template `POST /api/public/v1/charts/{chartId}/update` SDK: `prosaic.charts.update(chartId, params)` Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape. Updates a chart of accounts template. When `accounts` is provided it fully replaces the template's account list (delegates to updateAccountTemplateAccounts and propagates to all entities). When `accounts` is omitted, only the provided template metadata (`name`, `description`) is updated and accounts are left untouched. Omit a metadata field to preserve its existing value, or send `description: null` to clear the description. A full replacement list in a nonactivated workspace must still contain every system account (`GET /api/public/v1/global-accounts`, `isSystem: true`) with `isIncluded: true` — otherwise the request fails with `SYSTEM_ACCOUNT_VALIDATION` listing all missing accounts. Set `includeSystemAccounts: true` to carry over any omitted system accounts automatically. For surgical single-account changes use the `/charts/{chartId}/accounts` endpoints instead. Requires API key authentication. **Tax codes**: The `taxCode` field expects the machine code, not the human-readable tax name. Passing a name (e.g. `"15% GST on Income"`) is stored verbatim and resolves to null wherever the code is looked up. Valid codes are `NZ_GST_15_INC` (15% GST on Income), `NZ_GST_15_EXP` (15% GST on Expenses), `NZ_GST_0_NONE` (No GST), and `NZ_GST_0_ZERO` (Zero-rated GST). Note that `GET /api/public/v1/charts/{chartId}` returns the human-readable name on read — convert it back to the machine code before writing. **Field preserve/clear semantics**: For each account, omitting a field (`description`, `taxCode`, `mappedCode`) preserves its existing value, while an explicit null clears it (taxCode clears to `NZ_GST_0_NONE`). ### Path parameters - `chartId` (string, required) ### Request body Content type: `application/json` - `name` (string) - `description` (string, nullable) - `includeSystemAccounts` (boolean) - `expectedUpdatedAt` (string) - `accounts` (array of objects) - `code` (string, required) - `isIncluded` (boolean, required) - `name` (string) - `description` (string, nullable) - `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`. - `mappedCode` (string, nullable) - `parentCode` (string, nullable) - `id` (string) - `clientKey` (string) - `groupKey` (string) - `categoryKey` (string, nullable) - `systemRole` (string, nullable) - `expectedUpdatedAt` (string) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `entitiesUpdated` (number, required) - `meta` (object) - `count` (number, required) - `400`: Validation error or business rule violation. `SYSTEM_ACCOUNT_VALIDATION` includes `details.missingAccounts` listing every required system account absent from the payload. - `401`: Unauthorized - `404`: Chart not found - `409`: Account code conflict - new template account codes conflict with custom accounts in entities using this template - `error` (string, required) - `code` (string, required): One of: `ACCOUNT_CODE_CONFLICT`. - `details` (object) - `accountCode` (string): (deprecated) Use accountCodes[0] for backward compatibility. - `accountCodes` (array of strings): All new account codes that conflict with entity custom accounts. - `conflictingEntityIds` (array of strings): Entity IDs that have conflicting custom accounts. - `conflictingEntities` (array of objects) - `entityId` (string, uuid) - `entityName` (string) - `conflictingAccountCodes` (array of strings): Account codes in this entity that conflict. ### Example (Node SDK) ```ts const { data } = await prosaic.charts.update(chartId, { name: 'Example Ltd', description: 'Office supplies', includeSystemAccounts: true, expectedUpdatedAt: '2026-04-01', accounts: [ { code: '200', isIncluded: true, }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/update \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "description": "Office supplies", "includeSystemAccounts": true, "expectedUpdatedAt": "2026-04-01", "accounts": [ { "code": "200", "isIncluded": true } ] }' ``` ## Update a single account in a chart of accounts template `POST /api/public/v1/charts/{chartId}/accounts/{accountId}/update` SDK: `prosaic.charts.updateAccount(chartId, accountId, params)` Discover the current workspace contract at GET /api/public/v1/report-categories before writing. In activated workspaces, included accounts need groupKey and an explicit categoryKey (null is valid for eligible group-only accounts); type derives from the group. Parent-only and mixed classification writes are rejected. Nonactivated workspaces retain parent inputs and reject reporting inputs. Metadata-only updates preserve saved reporting. API writes do not confirm template review or approve propagation. Reporting edits require saved template and row versions; reload after 409, and never retry using an alternate request shape. Updates one account in a chart of accounts template without resending the full account list. Supports `name`, `description`, `taxCode`, `mappedCode` and `code` (rename, kept under the same parent). A code rename cascades non-destructively to every entity account derived from this template account (balances and customizations are preserved). Metadata changes follow existing propagation policy for entities using the template. Omitted fields preserve their existing values; send `description: null` to clear the description. `accountId` is the TemplateAccount ID from `GET /charts/{chartId}`. Reporting changes remain subject to human review before propagation. Requires bearer authentication. ### Path parameters - `chartId` (string, required) - `accountId` (string, required) ### Request body Content type: `application/json` - `expectedTemplateUpdatedAt` (string) - `name` (string) - `description` (string, nullable) - `taxCode` (string, nullable): One of: `NZ_GST_15_INC`, `NZ_GST_15_EXP`, `NZ_GST_0_NONE`, `NZ_GST_0_ZERO`, `AU_GST_10_INC`, `AU_GST_10_EXP`, `AU_GST_0_NONE`, `AU_GST_0_INPUT`, `AU_GST_0_EXPORT`. - `mappedCode` (string, nullable) - `code` (string) - `id` (string) - `clientKey` (string) - `groupKey` (string) - `categoryKey` (string, nullable) - `systemRole` (string, nullable) - `expectedUpdatedAt` (string) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `entitiesUpdated` (number, required) - `meta` (object) - `count` (number, required) - `400`: Validation error or business rule violation - `401`: Unauthorized - `404`: Chart or account not found - `409`: The new code conflicts with an existing template or entity account ### Example (Node SDK) ```ts const { data } = await prosaic.charts.updateAccount(chartId, accountId, { expectedTemplateUpdatedAt: '2026-04-01', name: 'Example Ltd', description: 'Office supplies', taxCode: 'NZ_GST_15_INC', mappedCode: 'MAPPED_CODE', code: '200', id: 'ID', clientKey: 'string', groupKey: 'string', categoryKey: 'string', systemRole: 'string', expectedUpdatedAt: '2026-04-01', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/accounts/$ACCOUNT_ID/update \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expectedTemplateUpdatedAt": "2026-04-01", "name": "Example Ltd", "description": "Office supplies", "taxCode": "NZ_GST_15_INC", "mappedCode": "MAPPED_CODE", "code": "200", "id": "ID", "clientKey": "string", "groupKey": "string", "categoryKey": "string", "systemRole": "string", "expectedUpdatedAt": "2026-04-01" }' ``` ## Delete a chart of accounts template `POST /api/public/v1/charts/{chartId}/delete` SDK: `prosaic.charts.del(chartId)` Deletes a chart of accounts template. Cannot delete templates with assigned entities. Requires API key authentication. ### Path parameters - `chartId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `success` (boolean, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - `404`: Chart not found - `409`: Cannot delete template with assigned entities ### Example (Node SDK) ```ts const { data } = await prosaic.charts.del(chartId); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/delete \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Delete a single account from a chart of accounts template `POST /api/public/v1/charts/{chartId}/accounts/{accountId}/delete` SDK: `prosaic.charts.deleteAccount(chartId, accountId, params)` Removes one account from a chart of accounts template without resending the full account list. The removal propagates to every entity using the template. Accounts that have journal entries, child accounts, or are system accounts cannot be removed. `accountId` is the TemplateAccount ID from `GET /charts/{chartId}`. Requires API key authentication. ### Path parameters - `chartId` (string, required) - `accountId` (string, required) ### Request body Content type: `application/json` - `expectedUpdatedAt` (string) ### Responses - `200`: Successful response - `data` (object, required) - `success` (boolean, required) - `entitiesUpdated` (number, required) - `meta` (object) - `count` (number, required) - `400`: Account has journal entries, has children, or is a system account - `401`: Unauthorized - `404`: Chart or account not found ### Example (Node SDK) ```ts const { data } = await prosaic.charts.deleteAccount(chartId, accountId, { expectedUpdatedAt: '2026-04-01', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/charts/$CHART_ID/accounts/$ACCOUNT_ID/delete \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expectedUpdatedAt": "2026-04-01" }' ``` ## List chart of accounts for an entity `GET /api/public/v1/entities/{entityId}/charts` SDK: `prosaic.entityAccounts.list(entityId, params)` Returns chart account codes configured for the specified entity. Supports filtering by system accounts and excluded accounts. Requires API key authentication and entity access. reportGroup and reportCategory expose the saved reporting classification; subtype remains the legacy compatibility value and may differ from current report placement. Null category with a saved group is valid. ### Path parameters - `entityId` (string, required) ### Query parameters - `includeSystem` (string): Include system-generated accounts (GST, Rounding, Retained Earnings, etc.) in the response. Defaults to true so all account codes are available for mapping (e.g. importing a trial balance or journals). Pass includeSystem=false to exclude system accounts. - `includeExcluded` (string): Include accounts that have been excluded from the entity's chart. When true, excluded accounts are returned with isExcluded=true flag, and their data comes from the template account. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `meta` (object) - `count` (number, required) - `400`: Bad request - missing or invalid parameters - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.entityAccounts.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a child account in the chart of accounts `POST /api/public/v1/entities/{entityId}/charts` SDK: `prosaic.entityAccounts.create(entityId, params)` Discover GET /api/public/v1/entities/{entityId}/report-categories before a write. In activated scope, create with reporting.groupKey and explicit reporting.categoryKey (null for eligible group-only accounts); omit legacy parent references. Metadata-only patches preserve reporting. Reporting updates require reporting.expected with the saved pair (or null for an unassigned account). All active workspaces must allow the write. Type derives from group. A contract mismatch or stale pair returns 409; reload and rediscover without automatically retrying a mutation. Stored subtype output remains a compatibility value. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `code` (string, required) - `name` (string, required) - `taxCode` (string, required) - `reporting` (object) - `groupKey` (string, required) - `categoryKey` (string, nullable, required) - `parentAccountId` (string) - `parentAccountCode` (string) - `parentMappedCode` (string) - `description` (string, nullable) - `mappedCode` (string, nullable) ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `meta` (object) - `count` (number, required) - `400`: Bad request - validation error or business rule violation - `error` (string): Error message. - `code` (string): Error code. - `details` (object): Additional error details (for template conflicts) - `templateAccountId` (string) - `isExcluded` (boolean) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `404`: Parent account not found - `error` (string) - `code` (string) - `409`: Conflict - account code already exists - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.entityAccounts.create(entityId, { code: '4030.1', name: 'Software subscriptions', taxCode: 'NZ_GST_15_EXP', reporting: { groupKey: 'exp.operating', categoryKey: null, }, }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "4030.1", "name": "Software subscriptions", "taxCode": "NZ_GST_15_EXP", "reporting": { "groupKey": "exp.operating", "categoryKey": null } }' ``` ## Update an entity account `POST /api/public/v1/entities/{entityId}/charts/{accountId}/update` SDK: `prosaic.entityAccounts.update(entityId, accountId, params)` Discover GET /api/public/v1/entities/{entityId}/report-categories before a write. In activated scope, create with reporting.groupKey and explicit reporting.categoryKey (null for eligible group-only accounts); omit legacy parent references. Metadata-only patches preserve reporting. Reporting updates require reporting.expected with the saved pair (or null for an unassigned account). All active workspaces must allow the write. Type derives from group. A contract mismatch or stale pair returns 409; reload and rediscover without automatically retrying a mutation. Stored subtype output remains a compatibility value. ### Path parameters - `entityId` (string, required) - `accountId` (string, required) ### Request body Content type: `application/json` - `reporting` (object) - `groupKey` (string, required) - `categoryKey` (string, nullable, required) - `expected` (object, nullable, required) - `groupKey` (string, required) - `categoryKey` (string, nullable, required) - `name` (string) - `description` (string, nullable) - `taxCode` (string) - `mappedCode` (string, nullable) - `code` (string) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `meta` (object) - `count` (number, required) - `400`: Validation error or business rule violation - `404`: Account not found ### Example (Node SDK) ```ts const { data } = await prosaic.entityAccounts.update(entityId, accountId, { reporting: { groupKey: 'exp.operating', categoryKey: null, expected: { groupKey: 'exp.operating', categoryKey: 'CATEGORY_KEY_FROM_LATEST_READ', }, }, }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/$ACCOUNT_ID/update \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reporting": { "groupKey": "exp.operating", "categoryKey": null, "expected": { "groupKey": "exp.operating", "categoryKey": "CATEGORY_KEY_FROM_LATEST_READ" } } }' ``` ## Restore a hidden/excluded template account `POST /api/public/v1/entities/{entityId}/charts/excluded/{templateAccountId}/restore` SDK: `prosaic.entityAccounts.restore(entityId, templateAccountId)` Restores an excluded template account by removing the exclusion and recreating the entity account from the template. No request body required. ### Path parameters - `entityId` (string, required) - `templateAccountId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `success` (boolean, required) - `meta` (object) - `count` (number, required) - `400`: Parent account must be restored first, or restoring would conflict with an assigned system role (SYSTEM_ACCOUNT_CONFLICT). - `404`: Template account no longer exists (chart template may have been updated) - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.entityAccounts.restore(entityId, templateAccountId); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/excluded/$TEMPLATE_ACCOUNT_ID/restore \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Reset an entity account to template defaults `POST /api/public/v1/entities/{entityId}/charts/{accountId}/reset` SDK: `prosaic.entityAccounts.reset(entityId, accountId)` Resets all customized fields on a template-based entity account back to the template values and clears customization flags. No request body required. ### Path parameters - `entityId` (string, required) - `accountId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `success` (boolean, required) - `meta` (object) - `count` (number, required) - `404`: Account not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.entityAccounts.reset(entityId, accountId); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/$ACCOUNT_ID/reset \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Delete or hide an entity account `POST /api/public/v1/entities/{entityId}/charts/{accountId}/delete` SDK: `prosaic.entityAccounts.del(entityId, accountId)` Deletes a custom child account or hides a template-based child account by creating an exclusion. Parent accounts cannot be deleted. Accounts assigned a system role or linked to bank accounts, fixed assets or inter-entity transfers cannot be deleted. ### Path parameters - `entityId` (string, required) - `accountId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `success` (boolean, required) - `meta` (object) - `count` (number, required) - `400`: The account is a parent, has children or journal entries, or has an operational link that prevents deletion (DELETE_RESTRICTED). - `404`: Account not found ### Example (Node SDK) ```ts const { data } = await prosaic.entityAccounts.del(entityId, accountId); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/charts/$ACCOUNT_ID/delete \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List report groups and categories for the authorised workspace `GET /api/public/v1/report-categories` SDK: `prosaic.reportCategories.listForWorkspace()` Returns the complete stored taxonomy for the authorised workspace's country. Parent IDs and sort order describe the group tree. Headings are structure only; isAssignable=false prevents their selection. An ordinary group may allow a null category, but bank and asset-account functions can still require one. Category placements are exact, not inherited. Examples: Operating expenses (exp.operating) is assignable with no category; Retained earnings (equ.retainedearnings) also permits a null category. Expenses (exp) is a heading and cannot be assigned. This endpoint does not change accounts. No country parameter or pagination is required. ### Responses - `200`: Successful response - `data` (object, required) - `country` (string, required) - `legacyDefaults` (array of objects) - `globalAccountId` (string, required) - `code` (string, required) - `groupKey` (string, required) - `categoryKey` (string, nullable, required) - `groups` (array of objects, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `description` (string, nullable, required) - `parentId` (string, nullable, required) - `sortOrder` (number, required) - `isHeading` (boolean, required) - `isAssignable` (boolean, required) - `allowGroupOnly` (boolean, required) - `categories` (array of objects, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `description` (string, required) - `codingGuidance` (string, nullable, required) - `defaultGroupId` (string, required) - `allowedGroupIds` (array of strings, required) - `workspaceId` (string, required) - `reportingInputsEnabled` (boolean, required) - `meta` (object) - `count` (number, required) - `400`: Invalid entity ID - `401`: Missing or invalid bearer authentication - `403`: Bearer token is pinned to another entity - `404`: Entity not found or access denied - `500`: Unexpected failure loading the taxonomy - `503`: Permission service temporarily unavailable ### Example (Node SDK) ```ts const { data } = await prosaic.reportCategories.listForWorkspace(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/report-categories \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List report groups and categories for an entity `GET /api/public/v1/entities/{entityId}/report-categories` SDK: `prosaic.reportCategories.list(entityId)` Returns the complete stored taxonomy for the authorised entity's country. Parent IDs and sort order describe the group tree. Headings are structure only; isAssignable=false prevents their selection. An ordinary group may allow a null category, but bank and asset-account functions can still require one. Category placements are exact, not inherited. Examples: Operating expenses (exp.operating) is assignable with no category; Retained earnings (equ.retainedearnings) also permits a null category. Expenses (exp) is a heading and cannot be assigned. This endpoint does not change accounts. No country parameter or pagination is required. ### Path parameters - `entityId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `country` (string, required) - `legacyDefaults` (array of objects) - `globalAccountId` (string, required) - `code` (string, required) - `groupKey` (string, required) - `categoryKey` (string, nullable, required) - `groups` (array of objects, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `description` (string, nullable, required) - `parentId` (string, nullable, required) - `sortOrder` (number, required) - `isHeading` (boolean, required) - `isAssignable` (boolean, required) - `allowGroupOnly` (boolean, required) - `categories` (array of objects, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `description` (string, required) - `codingGuidance` (string, nullable, required) - `defaultGroupId` (string, required) - `allowedGroupIds` (array of strings, required) - `reportingInputsEnabled` (boolean, required) - `meta` (object) - `count` (number, required) - `400`: Invalid entity ID - `401`: Missing or invalid bearer authentication - `403`: Bearer token is pinned to another entity - `404`: Entity not found or access denied - `500`: Unexpected failure loading the taxonomy - `503`: Permission service temporarily unavailable ### Example (Node SDK) ```ts const { data } = await prosaic.reportCategories.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/report-categories \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List all global accounts `GET /api/public/v1/global-accounts` SDK: `prosaic.globalAccounts.list()` Returns the full system account library (global accounts). These are the master accounts from which templates are built. Requires API key authentication. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `type` (string, required) - `subtype` (string, required) - `isSystem` (boolean, required) - `taxCode` (string, nullable, required) - `metadata` (any, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - Invalid or missing API key ### Example (Node SDK) ```ts const { data } = await prosaic.globalAccounts.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/global-accounts \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Journals > Manual journals: post or draft them, list them, attach files and void them. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List manual journals `GET /api/public/v1/entities/{entityId}/journals` SDK: `prosaic.journals.list(entityId, params)` Returns paginated manual journals for the specified entity with optional date range filtering. Requires API key authentication and entity access. Only returns journals of type MANUAL (excludes automatic and reversal journals). ### Path parameters - `entityId` (string, required) ### Query parameters - `page` (integer): Page number (starts at 1) Default: `1`. - `pageSize` (integer): Number of items per page. Default: `20`. - `dateFrom` (string, date): Start date for filtering journals (ISO 8601 format) - `dateTo` (string, date): End date for filtering journals (ISO 8601 format) ### Responses - `200`: Successful response - `data` (array of objects, required) - `logicalJournalId` (string, nullable, required) - `postedAt` (string, date-time, nullable, required) - `postedBy` (string, nullable, required) - `poster` (object, nullable) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `lines` (array of objects, required) - `id` (string, required) - `journalId` (string, required) - `parentId` (string, nullable, required) - `entityAccountId` (string, required) - `lineNumber` (number, required) - `type` (string, required) - `description` (string, nullable, required) - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `taxRateId` (string, nullable, required) - `entityAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `taxRate` (object, nullable, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `id` (string, required) - `narration` (string, required) - `date` (string, date-time, required) - `status` (string, required) - `type` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `reconciliations` (array of objects) - `bankTransaction` (object, required) - `id` (string, required) - `description` (string, required) - `merchant` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Bad request - missing or invalid parameters - `error` (string) - `code` (string) - `field` (string) - `value` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const page = await prosaic.journals.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a manual journal `POST /api/public/v1/entities/{entityId}/journals` SDK: `prosaic.journals.create(entityId, params)` Creates a new manual journal in either draft or posted status. By default, journals are automatically posted (status=POSTED). Set `autoPost: false` to create in draft status (status=DRAFT), which allows for review before posting. The journal must have balanced debits and credits. Lines are validated against the entity's chart of accounts and tax rates. Requires API key authentication and entity access. #### Prerequisites — Finding Tax Codes and Account Codes Before creating a journal, you need two pieces of information: - **Account codes**: Retrieve the entity's chart of accounts via `GET /api/public/v1/entities/{entityId}/charts`. Use the account `code` field (e.g., "2030") as the `entityAccountCode` in journal lines. - **Tax rate IDs**: Retrieve the entity's tax rates via `GET /api/public/v1/entities` (filter by `entityId`). Use the `taxRates[].id` field as the `taxRateId` in journal lines. Common tax codes include GST15, EXEMPT, and ZERO. #### Dimensions (optional) Lines can be tagged with dimensions (tracking categories such as Property or Department) by passing `dimensionOptionIds` on each line — an array of dimension option UUIDs, at most one option per dimension. Retrieve the entity's dimensions and option ids via `GET /api/public/v1/entities/{entityId}/dimensions`. Options must belong to the entity; unknown option ids or two options from the same dimension are rejected with a 400. Tagged lines drive the dimension filter and "Segment by" columns on financial reports. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `narration` (string, required) - `date` (string, required) - `lines` (array of objects, required) - `entityAccountCode` (string) - `entityAccountName` (string) - `taxRateName` (string) - `description` (string) - `credit` (string | number) - `debit` (string | number) - `taxRateId` (string) - `dimensionOptionIds` (array of strings) - `editReason` (string) - `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`. - `fileIds` (array of strings) - `autoPost` (boolean) ### Responses - `200`: Successful response - `logicalJournalId` (string, nullable, required) - `postedAt` (string, date-time, nullable, required) - `postedBy` (string, nullable, required) - `poster` (object, nullable) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `lines` (array of objects, required) - `id` (string, required) - `journalId` (string, required) - `parentId` (string, nullable, required) - `entityAccountId` (string, required) - `lineNumber` (number, required) - `type` (string, required) - `description` (string, nullable, required) - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `taxRateId` (string, nullable, required) - `entityAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `taxRate` (object, nullable, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `id` (string, required) - `narration` (string, required) - `date` (string, date-time, required) - `status` (string, required) - `type` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `reconciliations` (array of objects) - `bankTransaction` (object, required) - `id` (string, required) - `description` (string, required) - `merchant` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `400`: Bad request - validation failed, invalid account codes, an unbalanced journal, or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION). - `error` (string) - `code` (string) - `details` (array of objects) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `404`: Not found - Entity not found - `error` (string) - `500`: Internal server error - `error` (string) ### Example (Node SDK) ```ts const result = await prosaic.journals.create(entityId, { date: '2026-04-01', narration: 'Daily POS takings', taxMode: 'TAX_INCLUSIVE', lines: [ { entityAccountCode: 'BANK_ACCOUNT_CODE', taxRateId: 'NO_GST_TAX_RATE_ID', debit: '1150.00', }, { entityAccountCode: 'SALES_ACCOUNT_CODE', taxRateId: 'GST_15_TAX_RATE_ID', credit: '1150.00', }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "date": "2026-04-01", "narration": "Daily POS takings", "taxMode": "TAX_INCLUSIVE", "lines": [ { "entityAccountCode": "BANK_ACCOUNT_CODE", "taxRateId": "NO_GST_TAX_RATE_ID", "debit": "1150.00" }, { "entityAccountCode": "SALES_ACCOUNT_CODE", "taxRateId": "GST_15_TAX_RATE_ID", "credit": "1150.00" } ] }' ``` ## Create several manual journals at once `POST /api/public/v1/entities/{entityId}/journals/bulk` SDK: `prosaic.journals.createBulk(entityId, params)` Creates up to 100 manual journals, with at most 1,000 lines between them, in one transaction: either every journal is recorded or none is. Each journal takes the same fields as `POST /api/public/v1/entities/{entityId}/journals`, including dimensions and `fileIds`. `autoPost` is required and applies to the whole set. `true` posts every journal to the ledger, and `false` saves every journal as a draft. #### Retrying safely Send an `idempotencyKey` to make a retry safe. A repeat of the same request with the same key returns the journals it created, with `replayed: true` and status 200, and records nothing new. A replay shows each journal's current status, which may have changed since it was created. The same key with different journals is refused with a 409. Without a key, a retry after a timeout can record the whole set twice. #### Fixing a rejected set A 422 lists problems by each journal's position in `journals`, counting from 0. Nothing was recorded, so fix them and send the whole set again. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `autoPost` (boolean, required) - `journals` (array of objects, required) - `date` (string, required) - `narration` (string, required) - `lines` (array of objects, required) - `entityAccountCode` (string) - `entityAccountName` (string) - `taxRateName` (string) - `description` (string) - `credit` (string | number) - `debit` (string | number) - `taxRateId` (string) - `dimensionOptionIds` (array of strings) - `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`. - `fileIds` (array of strings) - `idempotencyKey` (string) ### Responses - `200`: Successful response - `replayed` (boolean, required) - `data` (array of objects, required) - `id` (string, required) - `logicalJournalId` (string, nullable, required) - `narration` (string, nullable, required) - `date` (string, date-time, required) - `status` (string, required) - `meta` (object) - `count` (number, required) - `201`: Successful response - `replayed` (boolean, required) - `data` (array of objects, required) - `id` (string, required) - `logicalJournalId` (string, nullable, required) - `narration` (string, nullable, required) - `date` (string, date-time, required) - `status` (string, required) - `meta` (object) - `count` (number, required) - `400`: The request is malformed, or a taxed journal needs a GST account the entity lacks (SYSTEM_ACCOUNT_VALIDATION). Nothing was recorded. - `401`: Unauthorized - Invalid or missing API key - `404`: Not found - Entity not found or access denied - `409`: This idempotency key was already used for different journals (IDEMPOTENCY_KEY_REUSED) - `422`: One or more journals can't be recorded (JOURNALS_REJECTED); `details.problems` lists each with its index. Nothing was recorded. - `error` (string) - `code` (string) - `details` (object) - `problems` (array of objects) - `index` (integer) - `message` (string) - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.journals.createBulk(entityId, { autoPost: true, journals: [ { date: '2026-04-01', narration: 'Office supplies', lines: [ {}, ], }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/bulk \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "autoPost": true, "journals": [ { "date": "2026-04-01", "narration": "Office supplies", "lines": [ {} ] } ] }' ``` ## Attach files to an existing journal `POST /api/public/v1/entities/{entityId}/journals/{journalId}/attachments` SDK: `prosaic.journals.attachFiles(entityId, journalId, params)` Attaches one or more previously uploaded files to a journal. Files must already be uploaded to the entity via the file upload endpoint. Requires API key authentication and entity access. ### Path parameters - `entityId` (string, required) - `journalId` (string, required) ### Request body Content type: `application/json` - `fileIds` (array of strings, required) ### Responses - `200`: Successful response - `success` (boolean, required): One of: `true`. - `attachments` (array of objects, required) - `id` (string, required) - `fileId` (string, required) - `createdAt` (string, date-time, required) - `400`: Bad request - validation failed or files not found - `error` (string) - `details` (array of objects) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `404`: Not found - Journal not found - `error` (string) - `500`: Internal server error - `error` (string) ### Example (Node SDK) ```ts const result = await prosaic.journals.attachFiles(entityId, journalId, { fileIds: ['FILE_ID'], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/$JOURNAL_ID/attachments \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "fileIds": [ "FILE_ID" ] }' ``` ## Void a journal `PATCH /api/public/v1/entities/{entityId}/journals/{journalId}/void` SDK: `prosaic.journals.void(entityId, journalId)` Voids a posted journal for the specified entity. Only posted journals can be voided. Requires API key authentication and entity access. ### Path parameters - `entityId` (string, required) - `journalId` (string, required) ### Responses - `200`: Successful response - `originalJournal` (object, required) - `id` (string, required) - `status` (string, required) - `voidedAt` (string, date-time, nullable, required) - `voidedBy` (string, nullable, required) - `reversalJournal` (object, required) - `id` (string, required) - `status` (string, required) - `postedAt` (string, date-time, required) - `postedBy` (string, required) - `voidedJournalId` (string, required) - `voidedAt` (string, date-time, required) - `400`: Journal is not in a voidable state - `404`: Journal not found - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.journals.void(entityId, journalId); ``` ### Example (curl) ```bash curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/journals/$JOURNAL_ID/void \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Transactions > Bank transactions: list them, reconcile them one at a time or in bulk, and reverse a reconciliation. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List bank transactions `GET /api/public/v1/entities/{entityId}/transactions` SDK: `prosaic.transactions.list(entityId, params)` Returns paginated bank transactions for the specified entity with optional date range filtering. By default, transactions dated before the entity's conversion date are hidden, matching the app, and a dateFrom earlier than the conversion date is moved up to it. Pass `includePreConversion=true` to see them. Requires API key authentication and entity access. ### Path parameters - `entityId` (string, required) ### Query parameters - `page` (integer): Page number (starts at 1) Default: `1`. - `pageSize` (integer): Number of items per page. Default: `20`. - `dateFrom` (string, date): Start date for filtering transactions (ISO 8601 format) - `dateTo` (string, date): End date for filtering transactions (ISO 8601 format) - `includePreConversion` (string): Include transactions dated before the entity's conversion date (default false) One of: `true`, `false`. - `journalId` (string, uuid): Filter by journal ID to get transactions reconciled to a specific journal. - `reconciliationStatus` (string): Filter by reconciliation status. One of: `reconciled`, `unreconciled`. - `view` (string): `full` (default) returns each transaction with its bank account, linked GL account, user, merchant, category and suggestions in full. `compact` returns what coding needs: the transaction's own fields, the bank account's id and name, merchant and category names, the reconciliation status, and each suggestion's source, confidence, rule name and lines as account code, account name, tax code, proportion, debit and credit. . One of: `full`, `compact`. Default: `"full"`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Bad request - missing or invalid parameters - `error` (string) - `code` (string) - `field` (string) - `value` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const page = await prosaic.transactions.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Reconcile bank transactions (bulk or single) `POST /api/public/v1/transactions/reconcile` SDK: `prosaic.transactions.reconcileBulk(params)` Reconciles one or more bank transactions by creating journal entries with automatic tax calculations. All requests are processed asynchronously via background jobs. #### Processing - All transactions are queued for background processing - Returns `requestId` for tracking - Transactions are grouped by entity automatically - Separate jobs created per entity for parallel processing #### Entity Determination Unlike other endpoints, this endpoint does **not** require an `entityId` in the path. Instead, entities are determined from the transactions themselves: - Each transaction is associated with a bank account - Each bank account belongs to an entity - Transactions can span multiple entities (separate jobs per entity) #### Tax Handling The system supports three tax modes: #### NO_TAX - No tax calculations are performed - Assignment amounts are used as-is in journal entries - Use for transfers between accounts or tax-exempt transactions #### TAX_INCLUSIVE (Default for NZ) - Assignment amounts **include** tax - System automatically splits the amount into base and tax components - **Formula**: `baseAmount = amount / (1 + rate)`, `taxAmount = amount - baseAmount` - **Example**: $115 with GST 15% → $100 base + $15 GST - Common for expenses where you know the total paid (including GST) #### TAX_EXCLUSIVE - Assignment amounts **exclude** tax - System adds tax on top of the specified amount - **Formula**: `taxAmount = amount × rate`, `totalAmount = amount + taxAmount` - **Example**: $1000 with GST 15% → $1000 base + $150 GST = $1150 total - Common for income where you invoice a base amount plus GST #### Important Notes - Maximum 500 transactions per request - Each transaction amount must equal the sum of its assignment debits/credits - Each assignment line requires a valid `taxCode` from the entity's tax rates - Generated tax lines are automatically created and linked to parent lines - Transactions already being processed will return a 409 conflict error ### Request body Content type: `application/json` - `updates` (array of objects, required) - `id` (string, required) - `invoiceId` (string) - `invoiceAllocations` (array of objects) - `invoiceId` (string, required) - `amount` (number, required) - `billAllocations` (array of objects) - `billId` (string, required) - `amount` (number, required) - `refundCredit` (object) - `contactId` (string, required) - `creditHolding` (object) - `accountCode` (string, required) - `taxCode` (string, required) - `fixedAssetDisposal` (object) - `fixedAssetId` (string, required) - `reverseLaterDepreciation` (boolean) - `saleTaxCode` (string) - `accountCodes` (object) - `loss` (string) - `gain` (string) - `private_loss` (string) - `private_gain` (string) - `depreciation_recovery` (string) - `capital_gain` (string) - `fixedAssetPurchase` (object) - `name` (string, required) - `entityFixedAssetTypeId` (string, required) - `startDate` (string, required) - `depreciationMethod` (string, required) - `assetNumber` (string) - `businessUsePercentage` (number) - `taxCode` (string) - `depreciationRate` (number) - `usefulLifeYears` (number) - `narration` (string) - `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`. - `fileIds` (array of strings) - `destinationEntityId` (string) - `assignment` (array of objects) - `code` (string, required) - `name` (string, required) - `taxCode` (string, required) - `credit` (number) - `debit` (number) - `description` (string) - `destinationEntityId` (string) - `dimensionOptionIds` (array of strings) ### Responses - `200`: Successful response - `success` (boolean, required): One of: `true`. - `data` (object, required) - `requestId` (string, required) - `transactionIds` (array of strings, required) - `status` (string, required) - `entityJobs` (array of objects, required) - `entityId` (string, required) - `jobId` (string, required) - `transactionCount` (number, required) - `message` (string, required) - `400`: Bad request - validation error - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `404`: Transaction(s) not found, already reconciled, or access denied - `error` (string) - `code` (string) - `409`: Conflict - transactions already being processed - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.transactions.reconcileBulk({ updates: [ { id: 'ID', }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/transactions/reconcile \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updates": [ { "id": "ID" } ] }' ``` ## Reconcile a bank transaction `POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reconcile` SDK: `prosaic.transactions.reconcile(entityId, transactionId, params)` Reconciles a single bank transaction by creating journal entries with automatic tax calculations. #### Tax Handling The system supports three tax modes: #### NO_TAX - No tax calculations are performed - Assignment amounts are used as-is in journal entries - Use for transfers between accounts or tax-exempt transactions #### TAX_INCLUSIVE (Default for NZ) - Assignment amounts **include** tax - System automatically splits the amount into base and tax components - **Formula**: `baseAmount = amount / (1 + rate)`, `taxAmount = amount - baseAmount` - **Example**: $115 with GST 15% → $100 base + $15 GST - Common for expenses where you know the total paid (including GST) #### TAX_EXCLUSIVE - Assignment amounts **exclude** tax - System adds tax on top of the specified amount - **Formula**: `taxAmount = amount × rate`, `totalAmount = amount + taxAmount` - **Example**: $1000 with GST 15% → $1000 base + $150 GST = $1150 total - Common for income where you invoice a base amount plus GST #### Prerequisites — Finding Tax Codes and Account Codes Before reconciling, you need two pieces of information: - **Account codes**: Retrieve the entity's chart of accounts via `GET /api/public/v1/entities/{entityId}/charts`. Use the `code` field (e.g., "2030") in the assignment `code` field below. - **Tax codes**: Retrieve the entity's tax rates via `GET /api/public/v1/entities` (filter by `entityId`). The `taxRates[].code` field (e.g., "GST15", "EXEMPT", "ZERO") is used in the assignment `taxCode` field below. #### Integration Flow 1. **GET `/entities`** - Retrieve entity with available `taxRates[]` 2. **GET `/entities/{entityId}/transactions`** - List unreconciled transactions 3. **POST `/entities/{entityId}/transactions/{transactionId}/reconcile`** - Reconcile with: - Select appropriate account (from entity's chart of accounts) - Select tax rate using `taxCode` from step 1 - Specify `taxMode` based on whether your amounts include/exclude tax 4. System validates and creates journal entries with tax lines automatically #### Important Notes - The transaction amount must equal the sum of assignment debits/credits - Each assignment line requires a valid `taxCode` from the entity's tax rates - Generated tax lines are automatically created and linked to parent lines - Use the entity's `defaultTaxAccountId` (GST account) for tax collection/payment ### Path parameters - `entityId` (string, required) - `transactionId` (string, required) ### Request body Content type: `application/json` - `assignment` (array of objects, required) - `code` (string, required) - `name` (string, required) - `taxCode` (string, required) - `credit` (number) - `debit` (number) - `description` (string) - `dimensionOptionIds` (array of strings) - `narration` (string) - `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`. - `fileIds` (array of strings) ### Responses - `200`: Successful response - `success` (boolean, required): One of: `true`. - `data` (object, required) - `transactionId` (string, required) - `journalId` (string, required) - `logicalJournalId` (string, required) - `400`: Bad request - validation error or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION). - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `404`: Transaction not found or already reconciled - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.transactions.reconcile(entityId, transactionId, { assignment: [ { code: '200', name: 'Example Ltd', taxCode: 'TAX_CODE', }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions/$TRANSACTION_ID/reconcile \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "assignment": [ { "code": "200", "name": "Example Ltd", "taxCode": "TAX_CODE" } ] }' ``` ## Reverse a bank transaction reconciliation `POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reverse` SDK: `prosaic.transactions.reverse(entityId, transactionId, params)` Reverses a previously reconciled bank transaction, making it available for reconciliation again. #### Business Rules - Only reconciled transactions can be reversed - Only bank reconciliation journals (AUTOMATIC type) can be reversed - The journal must be in POSTED status - The transaction must belong to the specified entity #### What Happens During Reversal 1. Creates a reversal journal entry that negates the original reconciliation 2. Updates the reconciliation status to REVERSED 3. Makes the bank transaction available for reconciliation again 4. Maintains full audit trail of the reversal #### Integration Flow 1. **GET `/entities/{entityId}/transactions`** - Find reconciled transactions to reverse 2. **POST `/entities/{entityId}/transactions/{transactionId}/reverse`** - Reverse the reconciliation 3. The transaction becomes available for new reconciliation via the reconcile endpoint ### Path parameters - `entityId` (string, required) - `transactionId` (string, required) ### Request body Content type: `application/json` - `reverseReason` (string) ### Responses - `200`: Successful response - `success` (boolean, required): One of: `true`. - `data` (object, required) - `transactionId` (string, required) - `logicalJournalId` (string, required) - `reversalJournalId` (string, required) - `reversedAt` (string, date-time, required) - `reverseReason` (string, required) - `400`: Bad request - validation error or transaction cannot be reversed - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `404`: Transaction not found or access denied - `error` (string) - `code` (string) - `409`: The receipt can't be unmatched because some of its credit was refunded (`PAYMENT_REFUNDED`). Unmatch the refund first. - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.transactions.reverse(entityId, transactionId, { reverseReason: 'string', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions/$TRANSACTION_ID/reverse \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reverseReason": "string" }' ``` --- # Bank accounts > Link a client's bank accounts to an entity, or create CSV accounts and fill them with transactions from your own systems. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## Create a CSV bank account and import transactions into it `POST /api/public/v1/entities/{entityId}/bank-accounts/import` SDK: `prosaic.bankAccounts.createWithTransactions(entityId, params)` Creates a CSV bank account for the entity — one fed by imported files — with its account in the entity's chart so its lines can be reconciled, then imports the transactions into it. All or nothing. Use this when the entity has no account for the statement, or when its matching account is a bank feed, which can't take imported transactions. The new account sits beside the feed account, so both will need reconciling; prefer importing into an existing CSV account with `POST /entities/{entityId}/bank-accounts/{bankAccountId}/import`. The account belongs to the caller. Amounts are from the account holder's side: money in positive, money out negative; never 0. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `filename` (string, required) - `transactions` (array of objects, required) - `date` (string, required) - `description` (string, required) - `amount` (number, required) - `transactionType` (string) - `payee` (string) - `code` (string) - `reference` (string) - `particulars` (string) - `bankTransactionId` (string) - `name` (string, required) - `institution` (string, required) - `accountNumber` (string) ### Responses - `201`: Successful response - `data` (object, required) - `bankAccountId` (string, required) - `bankAccountName` (string, required) - `institution` (string, nullable, required) - `accountNumber` (string, nullable, required) - `importId` (string, nullable, required) - `transactionsImported` (number, required) - `message` (string, required) - `meta` (object) - `count` (number, required) - `400`: Invalid body (`VALIDATION_ERROR`, `INVALID_ROW_DATE`, `ZERO_AMOUNT_TRANSACTION`) - `401`: Invalid or missing API key or token - `404`: Entity not found or not accessible - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.bankAccounts.createWithTransactions(entityId, { filename: 'Example Ltd', transactions: [ { date: '2026-04-01', description: 'Office supplies', amount: 100, }, ], name: 'Example Ltd', institution: 'string', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/bank-accounts/import \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filename": "Example Ltd", "transactions": [ { "date": "2026-04-01", "description": "Office supplies", "amount": 100 } ], "name": "Example Ltd", "institution": "string" }' ``` ## Link bank accounts to an entity `POST /api/public/v1/entities/{entityId}/bank-accounts` SDK: `prosaic.bankAccounts.link(entityId, params)` Links existing bank accounts to the entity, creating each one's general ledger account in the entity's chart of accounts. Linking only ever adds: accounts already on the entity are left as they are, and no account is unlinked. Each account must belong to a client of the entity — find them with `GET /api/public/v1/clients/{clientId}/bank-accounts` — and must not be linked to a different entity. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `bankAccountIds` (array of strings, required) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `entityId` (string, nullable, required) - `externalId` (string, required) - `name` (string, required) - `alias` (string, nullable, required) - `institution` (string, nullable, required) - `accountNumber` (string, nullable, required) - `logoUrl` (string, nullable, required) - `type` (string, required) - `sourceType` (string, nullable, required) - `entityAccount` (object, nullable, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `meta` (object) - `count` (number, required) - `400`: Validation failed (`VALIDATION_ERROR`), an ID does not exist (`INVALID_BANK_ACCOUNT_IDS`), or an account does not belong to a client of the entity (`BANK_ACCOUNTS_CLIENT_MISMATCH`) - `401`: Unauthorized - Invalid or missing API key/token - `404`: Entity not found or not accessible - `409`: An account is already linked to a different entity (`BANK_ACCOUNT_ASSIGNED_TO_DIFFERENT_ENTITY`) - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.bankAccounts.link(entityId, { bankAccountIds: ['BANK_ACCOUNT_ID'], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/bank-accounts \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "bankAccountIds": [ "BANK_ACCOUNT_ID" ] }' ``` ## Import transactions into a CSV bank account `POST /api/public/v1/entities/{entityId}/bank-accounts/{bankAccountId}/import` SDK: `prosaic.bankAccounts.importTransactions(entityId, bankAccountId, params)` Adds transactions to one of the entity's CSV bank accounts — the kind fed by imported files (`sourceType: csv` on the bank account). Bank feeds (`akahu`, `siss`) can't take imported transactions; create a separate CSV account with `POST /entities/{entityId}/bank-accounts/import` instead. Rows the account already holds (same date, amount and description) are skipped, so importing an overlapping statement is safe. Amounts are from the account holder's side: money in positive, money out negative. Zero amounts are rejected. ### Path parameters - `entityId` (string, required) - `bankAccountId` (string, required) ### Request body Content type: `application/json` - `filename` (string, required) - `transactions` (array of objects, required) - `date` (string, required) - `description` (string, required) - `amount` (number, required) - `transactionType` (string) - `payee` (string) - `code` (string) - `reference` (string) - `particulars` (string) - `bankTransactionId` (string) ### Responses - `200`: Successful response - `data` (object, required) - `bankAccountId` (string, required) - `bankAccountName` (string, required) - `importId` (string, nullable, required) - `transactionsImported` (number, required) - `transactionsSkipped` (number, required) - `message` (string, required) - `meta` (object) - `count` (number, required) - `400`: Invalid body (`VALIDATION_ERROR`, `INVALID_ROW_DATE`, `ZERO_AMOUNT_TRANSACTION`), a bank feed account (`BANK_ACCOUNT_NOT_CSV`), or an account missing its owner or bank (`BANK_ACCOUNT_NOT_IMPORTABLE`) - `401`: Invalid or missing API key or token - `404`: The entity or bank account wasn't found, or isn't accessible (`BANK_ACCOUNT_NOT_FOUND`) - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.bankAccounts.importTransactions(entityId, bankAccountId, { filename: 'Example Ltd', transactions: [ { date: '2026-04-01', description: 'Office supplies', amount: 100, }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/bank-accounts/$BANK_ACCOUNT_ID/import \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filename": "Example Ltd", "transactions": [ { "date": "2026-04-01", "description": "Office supplies", "amount": 100 } ] }' ``` --- # Reports > Trial balance, profit and loss, balance sheet, current accounts, depreciation schedule and the general ledger. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## Get general ledger grouped by account `GET /api/public/v1/entities/{entityId}/general-ledger/account` SDK: `prosaic.generalLedger.byAccount(entityId, params)` Returns journal entries grouped by account with running balances and period totals. Supports various period presets and custom date ranges. ### Path parameters - `entityId` (string, required) ### Query parameters - `periodType` (string): Period preset for date range filtering. One of: `custom`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-financial-year`, `last-financial-year`, `month-to-date`, `quarter-to-date`, `year-to-date`. - `startDate` (string): Start date. Required when periodType is `custom`. - `endDate` (string): End date. Required when periodType is `custom`. - `accountIds` (array of strings): Comma-separated list of entity account IDs to filter by. - `includeVoided` (boolean): Include voided journals (default false) Default: `false`. ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `periodDescription` (string, required) - `startDate` (string, required) - `endDate` (string, required) - `generatedAt` (string, required) - `currency` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountMappedCode` (string, nullable, required) - `accountName` (string, required) - `accountType` (string, required) - `accountSubtype` (string, required) - `beginningBalance` (string, required) - `endingBalance` (string, required) - `totalDebits` (string, required) - `totalCredits` (string, required) - `netMovement` (string, required) - `entries` (array of objects, required) - `id` (string, required) - `journalId` (string, required) - `logicalJournalId` (string, required) - `date` (string, required) - `narration` (string, required) - `description` (string, required) - `lineType` (string, required) - `parentId` (string, nullable, required) - `source` (string, required) - `journalStatus` (string, required) - `debit` (string, required) - `credit` (string, required) - `net` (string, required) - `gross` (string, required) - `runningBalance` (string, required) - `gstAmount` (string, required) - `taxRate` (object) - `id` (string, required) - `name` (string, required) - `rate` (string, required) - `bankTransaction` (object) - `id` (string, required) - `date` (string, required) - `amount` (string, required) - `type` (string, required) - `description` (string, required) - `particulars` (string) - `code` (string) - `merchant` (object) - `id` (string, required) - `name` (string, required) - `provider` (string) - `identifier` (string) - `category` (object) - `id` (string, required) - `name` (string, required) - `groupName` (string) - `provider` (string) - `bankAccount` (object, required) - `name` (string, required) - `accountNumber` (string) - `institution` (string) - `totals` (object, required) - `totalDebits` (string, required) - `totalCredits` (string, required) - `netMovement` (string, required) - `400`: Bad request - invalid parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.generalLedger.byAccount(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/general-ledger/account \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get general ledger as flat entry list `GET /api/public/v1/entities/{entityId}/general-ledger/transaction` SDK: `prosaic.generalLedger.byTransaction(entityId, params)` Returns a flat list of journal entries with embedded account metadata. Entries are ordered by date, createdAt, and id for deterministic results. ### Path parameters - `entityId` (string, required) ### Query parameters - `periodType` (string): Period preset for date range filtering. One of: `custom`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-financial-year`, `last-financial-year`, `month-to-date`, `quarter-to-date`, `year-to-date`. - `startDate` (string): Start date. Required when periodType is `custom`. - `endDate` (string): End date. Required when periodType is `custom`. - `accountIds` (array of strings): Comma-separated list of entity account IDs to filter by. - `includeVoided` (boolean): Include voided journals (default false) Default: `false`. ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `periodDescription` (string, required) - `startDate` (string, required) - `endDate` (string, required) - `generatedAt` (string, required) - `currency` (string, required) - `entries` (array of objects, required) - `account` (object, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountMappedCode` (string, nullable, required) - `accountName` (string, required) - `accountType` (string, required) - `accountSubtype` (string, required) - `id` (string, required) - `journalId` (string, required) - `logicalJournalId` (string, required) - `date` (string, required) - `narration` (string, required) - `description` (string, required) - `lineType` (string, required) - `parentId` (string, nullable, required) - `source` (string, required) - `journalStatus` (string, required) - `debit` (string, required) - `credit` (string, required) - `net` (string, required) - `gross` (string, required) - `runningBalance` (string, required) - `gstAmount` (string, required) - `taxRate` (object) - `id` (string, required) - `name` (string, required) - `rate` (string, required) - `bankTransaction` (object) - `id` (string, required) - `date` (string, required) - `amount` (string, required) - `type` (string, required) - `description` (string, required) - `particulars` (string) - `code` (string) - `merchant` (object) - `id` (string, required) - `name` (string, required) - `provider` (string) - `identifier` (string) - `category` (object) - `id` (string, required) - `name` (string, required) - `groupName` (string) - `provider` (string) - `bankAccount` (object, required) - `name` (string, required) - `accountNumber` (string) - `institution` (string) - `totals` (object, required) - `totalDebits` (string, required) - `totalCredits` (string, required) - `netMovement` (string, required) - `400`: Bad request - invalid parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.generalLedger.byTransaction(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/general-ledger/transaction \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get ledger entries (deprecated) `GET /api/public/v1/entities/{entityId}/ledger` SDK: `prosaic.ledger.list(entityId, params)` **Deprecated.** This was the original general ledger endpoint and has been replaced by the general ledger report endpoints. New integrations should use `GET /api/public/v1/entities/{entityId}/general-ledger/transaction` (flat entry list) or `GET /api/public/v1/entities/{entityId}/general-ledger/account` (grouped by account) instead. Returns paginated journal lines (ledger entries) for an entity with optional date range and account filtering. Only includes posted journals, excluding reversal entries. ### Path parameters - `entityId` (string, required) ### Query parameters - `page` (integer): Page number (starts at 1) Default: `1`. - `pageSize` (integer): Number of items per page. Default: `20`. - `dateFrom` (string, date): Start date for filtering ledger entries (ISO 8601 format YYYY-MM-DD, interpreted in NZ timezone) - `dateTo` (string, date): End date for filtering ledger entries (ISO 8601 format YYYY-MM-DD, interpreted in NZ timezone) - `accountIds` (array of strings): Comma-separated list of entity account IDs to filter by. - `journalId` (string, uuid): Filter by journal ID to get all ledger entries for a specific journal. ### Responses - `200`: Successful response - `data` (array of objects, required) - `narration` (string, required) - `journalType` (string, required) - `bankTransactionId` (string, nullable, required) - `gst` (string, required) - `id` (string, required) - `description` (string, nullable, required) - `updatedAt` (string, date-time, required) - `createdAt` (string, date-time, required) - `parentId` (string, nullable, required) - `journalId` (string, required) - `entityAccountId` (string, required) - `taxRateId` (string, required) - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `entityAccount` (object, required) - `id` (string, required) - `name` (string, required) - `code` (string, required) - `taxRate` (object, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `code` (string, required) - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `accountVersion` (number, nullable, required) - `lineNumber` (number, required) - `sumAccountCredits` (string, nullable, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `sumAccountDebits` (string, nullable, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Bad request - invalid parameters - `error` (string) - `code` (string) - `field` (string) - `value` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const page = await prosaic.ledger.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/ledger \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get trial balance report `GET /api/public/v1/entities/{entityId}/trial-balance` SDK: `prosaic.reports.trialBalance(entityId, params)` Returns a trial balance report for the specified entity. Supports cumulative and movement modes, optional period comparisons, and flexible grouping. **Cumulative mode** (default): Balance sheet accounts show all-time cumulative balances; P&L accounts show current financial year activity. **Movement mode**: Shows only journal activity within a specified date range for all account types. Use `movementStartDate` and `movementEndDate` to specify the range; when omitted the service defaults to the current financial year. ### Path parameters - `entityId` (string, required) ### Query parameters - `asOfDate` (string): As-of date for cumulative mode. Defaults to today. - `reportMode` (string): Report calculation mode. One of: `cumulative`, `movement`. - `movementStartDate` (string): Start date for movement mode. - `movementEndDate` (string): End date for movement mode. - `groupBy` (string): How to group accounts. Use `reportGroup` for saved report groups in the entity's country order. Each group's `type` is its stable key and `name` is its label. Accounts without a saved group appear together under `unassigned`. Use `none` to group rows yourself. **Deprecated.** Use `groupBy=reportGroup` in place of `groupBy=subtype`. . One of: `type`, `subtype`, `reportGroup`, `none`. - `includeZeroBalances` (string): Include accounts with zero balances. One of: `false`, `true`. - `comparison` (string): Whether to include comparison columns. One of: `none`, `periods`. - `comparisonType` (string): Type of comparison period. Used when comparison=periods. One of: `year`, `month`. - `comparisonPeriods` (string): Number of comparison periods (1-12). Used when comparison=periods. - `compareToEndOfMonth` (string): Snap comparison dates to end of month. One of: `false`, `true`. - `compareToEndOfFinancialYear` (string): Snap comparison dates to end of financial year (31 March) One of: `false`, `true`. ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `generatedAt` (string, required) - `currency` (string, required) - `timezone` (string, required) - `reportType` (string, required): One of: `trial-balance`. - `asOfDate` (string, required) - `movementStartDate` (string) - `movementEndDate` (string) - `totals` (object, required) - `totalDebits` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalCredits` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `isBalanced` (boolean, required) - `variance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `accountGroups` (array of objects, required) - `type` (string, required) - `name` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Equity`, `Revenue`, `Expense`, `Asset`, `Liability`. - `accountSubtype` (string, required) - `reportGroupKey` (string, nullable) - `reportGroupName` (string) - `reportCategoryKey` (string, nullable) - `reportGroup` (object, nullable) - `key` (string, required) - `name` (string, required) - `reportCategory` (object, nullable) - `key` (string, required) - `name` (string, required) - `debitBalance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `creditBalance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `netBalance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `isSystemGenerated` (boolean) - `earningsType` (string, nullable): One of: `retained`. - `subtotal` (object, required) - `debits` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `credits` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `net` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object) - `400`: Bad request - invalid query parameters or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION). - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.reports.trialBalance(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/trial-balance \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get profit & loss report `GET /api/public/v1/entities/{entityId}/reports/profit-loss` SDK: `prosaic.reports.profitLoss(entityId, params)` Returns a profit & loss report for the specified entity. ### Path parameters - `entityId` (string, required) ### Query parameters - `periodType` (string): Period type for the report. Matches the presets available in the Prosaic UI. Relative periods (this-month, this-quarter, etc.) are resolved to full NZ calendar periods, so omit startDate/endDate when using them. Use custom to supply explicit startDate and endDate. One of: `custom`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-financial-year`, `last-financial-year`. - `startDate` (string): Start date for custom period. Required when periodType is `custom`. - `endDate` (string): End date for custom period. Required when periodType is `custom`. - `comparison` (string): Whether to include comparison columns. One of: `none`, `periods`. - `comparisonType` (string): Granularity of each comparison period. For UI-consistent results, pair month with this-month/last-month, quarter with this-quarter/last-quarter, and year with the financial-year periods. One of: `custom`, `year`, `month`, `quarter`. - `comparisonPeriods` (string): Number of comparison periods (1-12) - `includeZeroBalances` (string): Include accounts with zero balances. One of: `false`, `true`. ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `generatedAt` (string, required) - `currency` (string, required) - `reportType` (string, required): One of: `profit-loss`. - `startDate` (string, required) - `endDate` (string, required) - `periodDescription` (string, required) - `comparisonPeriods` (array of strings) - `comparisonPeriodRanges` (array of objects) - `label` (string, required) - `startDate` (string, required) - `endDate` (string, required) - `tradingIncome` (object, required) - `header` (string, required) - `totalLabel` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Revenue`, `Expense`. - `accountSubtype` (string, required) - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonPeriods` (object) - `segments` (object) - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object, required) - `segmentTotals` (object) - `costOfSales` (object, required) - `header` (string, required) - `totalLabel` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Revenue`, `Expense`. - `accountSubtype` (string, required) - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonPeriods` (object) - `segments` (object) - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object, required) - `segmentTotals` (object) - `otherIncome` (object, required) - `header` (string, required) - `totalLabel` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Revenue`, `Expense`. - `accountSubtype` (string, required) - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonPeriods` (object) - `segments` (object) - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object, required) - `segmentTotals` (object) - `operatingExpenses` (object, required) - `header` (string, required) - `totalLabel` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Revenue`, `Expense`. - `accountSubtype` (string, required) - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonPeriods` (object) - `segments` (object) - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object, required) - `segmentTotals` (object) - `hasTradingSection` (boolean, required) - `totals` (object, required) - `grossProfit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `grossProfitComparison` (object, required) - `netProfit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `netProfitComparison` (object, required) - `segmentColumns` (array of objects) - `key` (string, required) - `label` (string, required) - `isArchived` (boolean, required) - `dimensionId` (string) - `dimensionName` (string) - `400`: Bad request - invalid query parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.reports.profitLoss(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/reports/profit-loss \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get balance sheet report `GET /api/public/v1/entities/{entityId}/reports/balance-sheet` SDK: `prosaic.reports.balanceSheet(entityId, params)` Returns a balance sheet report for the specified entity. ### Path parameters - `entityId` (string, required) ### Query parameters - `asOfDate` (string): As-of date for the report. Defaults to today. - `includeZeroBalances` (string): Include accounts with zero balances. One of: `false`, `true`. - `comparison` (string): Whether to include comparison columns. One of: `none`, `periods`. - `comparisonType` (string): Type of comparison period. One of: `year`, `month`. - `comparisonPeriods` (string): Number of comparison periods (1-12) ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `generatedAt` (string, required) - `currency` (string, required) - `reportType` (string, required): One of: `balance-sheet`. - `asOfDate` (string, required) - `sections` (object, required) - `assets` (object, required) - `type` (string, required): One of: `Equity`, `Assets`, `Liabilities`. - `name` (string, required) - `groups` (array of objects, required) - `type` (string, required) - `name` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Equity`, `Asset`, `Liability`. - `accountSubtype` (string, required) - `earningsType` (string): One of: `retained`, `current-year`. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `subtotal` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `liabilities` (object, required) - `type` (string, required): One of: `Equity`, `Assets`, `Liabilities`. - `name` (string, required) - `groups` (array of objects, required) - `type` (string, required) - `name` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Equity`, `Asset`, `Liability`. - `accountSubtype` (string, required) - `earningsType` (string): One of: `retained`, `current-year`. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `subtotal` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `equity` (object, required) - `type` (string, required): One of: `Equity`, `Assets`, `Liabilities`. - `name` (string, required) - `groups` (array of objects, required) - `type` (string, required) - `name` (string, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `accountType` (string, required): One of: `Equity`, `Asset`, `Liability`. - `accountSubtype` (string, required) - `earningsType` (string): One of: `retained`, `current-year`. - `balance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalCredit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalDebit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `subtotal` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totals` (object, required) - `totalAssets` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalLiabilities` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `totalEquity` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `netAssets` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `isBalanced` (boolean, required) - `variance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `earningsBreakdown` (object) - `currentYearEarnings` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `retainedEarnings` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object) - `400`: Bad request - invalid query parameters or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION). - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.reports.balanceSheet(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/reports/balance-sheet \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get current accounts report `GET /api/public/v1/entities/{entityId}/reports/current-accounts` SDK: `prosaic.reports.currentAccounts(entityId, params)` Returns a current accounts report for the specified entity. ### Path parameters - `entityId` (string, required) ### Query parameters - `periodType` (string): Period type for the report. Matches the presets available in the Prosaic UI. Relative periods (this-month, this-quarter, etc.) are resolved to full NZ calendar periods, so omit startDate/endDate when using them. Use custom to supply explicit startDate and endDate. One of: `custom`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-financial-year`, `last-financial-year`. - `startDate` (string): Start date for custom period. Required when periodType is `custom`. - `endDate` (string): End date for custom period. Required when periodType is `custom`. - `comparison` (string): Whether to include comparison columns. One of: `none`, `periods`. - `comparisonType` (string): Granularity of each comparison period. For UI-consistent results, pair month with this-month/last-month, quarter with this-quarter/last-quarter, and year with the financial-year periods. One of: `custom`, `year`, `month`, `quarter`. - `comparisonPeriods` (string): Number of comparison periods (1-12) ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `entityType` (string, required) - `generatedAt` (string, required) - `currency` (string, required) - `reportType` (string, required) - `startDate` (string, required) - `endDate` (string, required) - `periodDescription` (string, required) - `reportTitle` (string, required) - `comparisonPeriods` (array of strings) - `comparisonPeriodRanges` (array of objects) - `label` (string, required) - `startDate` (string, required) - `endDate` (string, required) - `openingBalance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `openingBalanceComparison` (object) - `increases` (object, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `amount` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonPeriods` (object) - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object) - `decreases` (object, required) - `accounts` (array of objects, required) - `accountId` (string, required) - `accountCode` (string, required) - `accountName` (string, required) - `amount` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonPeriods` (object) - `total` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `comparisonTotals` (object) - `closingBalance` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `closingBalanceComparison` (object) - `400`: Bad request - invalid query parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.reports.currentAccounts(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/reports/current-accounts \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get depreciation schedule report `GET /api/public/v1/entities/{entityId}/reports/depreciation-schedule` SDK: `prosaic.reports.depreciationSchedule(entityId, params)` Returns a depreciation schedule report for the specified entity. ### Path parameters - `entityId` (string, required) ### Query parameters - `startDate` (string, required): Start date for the schedule. - `endDate` (string, required): End date for the schedule. ### Responses - `200`: Successful response - `metadata` (object, required) - `entityId` (string, required) - `entityName` (string, required) - `currency` (string, required) - `startDate` (string, required) - `endDate` (string, required) - `generatedAt` (string, required) - `periodDescription` (string, required) - `assets` (array of objects, required) - `assetId` (string, required) - `name` (string, required) - `assetTypeName` (string, nullable, required) - `costAccountName` (string, nullable, required) - `expenseAccountName` (string, nullable, required) - `method` (string, required) - `rate` (number, nullable, required) - `privateUsePercentage` (number, required) - `purchaseDate` (string, nullable, required) - `cost` (number, required) - `openingValue` (number, required) - `purchases` (number, required) - `disposals` (number, required) - `depreciation` (number, required) - `investmentBoost` (number) - `accumulatedDepreciation` (number, required) - `closingValue` (number, required) - `privateUseAmount` (number, required) - `totals` (object, required) - `cost` (number, required) - `openingValue` (number, required) - `purchases` (number, required) - `disposals` (number, required) - `depreciation` (number, required) - `investmentBoost` (number) - `accumulatedDepreciation` (number, required) - `closingValue` (number, required) - `privateUseAmount` (number, required) - `400`: Bad request - invalid or missing query parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No access to the specified entity - `500`: Internal server error ### Example (Node SDK) ```ts const result = await prosaic.reports.depreciationSchedule(entityId, { startDate: '2026-04-01', endDate: '2026-04-01', }); ``` ### Example (curl) ```bash curl -G https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/reports/depreciation-schedule \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ --data-urlencode "startDate=2026-04-01" \ --data-urlencode "endDate=2026-04-01" ``` --- # GST returns > GST returns and their IRD box amounts, for one entity or across the workspace. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List GST returns across the workspace `GET /api/public/v1/gst-returns` SDK: `prosaic.gstReturns.list(params)` Returns paginated GST returns for every entity in the workspace the caller can see, newest period first. The entity-scoped endpoint (`/entities/{entityId}/gst-returns`) returns the same rows for one entity; use `entityId` here to narrow without changing endpoint. Each row carries the return's lifecycle status, its period, its filing due date, its net GST position (IRD Box 15) and a count of bank transactions in the period that are not yet reconciled. **Box 15 is only present once the return has been calculated.** A draft that has never been finalised reports `netGstPosition: null`. Use the entity detail endpoint to get live, calculated box amounts for a draft. **Period and due dates are New Zealand calendar days** (`YYYY-MM-DD`), not UTC instants. A GST period runs from the first moment of `dateFrom` to the last moment of `dateTo`, both in NZ time. By default, draft returns whose period has not started yet are hidden, matching what the Prosaic UI shows. Pass `includeFutureDrafts=true` to see them. ### Query parameters - `entityId` (string): Return only GST returns for this entity. - `status` (array of strings): Return only GST returns in these lifecycle statuses. Repeatable, and a comma-separated list means the same thing — `?status=draft&status=filed` and `?status=draft,filed` are equivalent. Omit for every status; nothing is filtered out by default, so completed returns appear alongside outstanding ones. To see only live work, list the seven statuses other than `completed`. . - `dateFrom` (string): Return only GST returns whose period ends on or after this NZ date. - `dateTo` (string): Return only GST returns whose period starts on or before this NZ date. - `dueAfter` (string): Return only GST returns due on or after this NZ date. - `dueBefore` (string): Return only GST returns due on or before this NZ date. - `includeFutureDrafts` (string): Include draft returns whose period has not started yet (default false) One of: `false`, `true`. - `page` (integer): Page number (default 1) - `pageSize` (integer): Items per page (default 100) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `entityId` (string, required) - `name` (string, required) - `description` (string, required) - `status` (string, required): One of: `rejected`, `completed`, `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `awaiting_payment`. - `dateFrom` (string, required) - `dateTo` (string, required) - `dueDate` (string, required) - `isOverdue` (boolean, required) - `netGstPosition` (number, nullable, required) - `unreconciledTransactionCount` (number, required) - `hasAmendment` (boolean, required) - `finalisedAt` (string, nullable, required) - `irdFiledAt` (string, nullable, required) - `updatedAt` (string, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Invalid query parameters - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `401`: Unauthorized - invalid or missing credentials - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `403`: An entity-scoped token asked for an entity it is not pinned to - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `404`: Workspace not found or not accessible with these credentials - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `500`: Internal server error - `error` (string): Error message. - `code` (string): Error code for programmatic handling. ### Example (Node SDK) ```ts const page = await prosaic.gstReturns.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/gst-returns \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List GST returns for an entity `GET /api/public/v1/entities/{entityId}/gst-returns` SDK: `prosaic.gstReturns.listForEntity(entityId, params)` Returns paginated GST returns for the specified entity, newest period first. Each row carries the return's lifecycle status, its period, its filing due date, its net GST position (IRD Box 15) and a count of bank transactions in the period that are not yet reconciled. **Box 15 is only present once the return has been calculated.** A draft that has never been finalised reports `netGstPosition: null`. Use the detail endpoint to get live, calculated box amounts for a draft. **Period and due dates are New Zealand calendar days** (`YYYY-MM-DD`), not UTC instants. A GST period runs from the first moment of `dateFrom` to the last moment of `dateTo`, both in NZ time. By default, draft returns whose period has not started yet are hidden, matching what the Prosaic UI shows. Pass `includeFutureDrafts=true` to see them. ### Path parameters - `entityId` (string, required) ### Query parameters - `status` (array of strings): Return only GST returns in these lifecycle statuses. Repeatable, and a comma-separated list means the same thing — `?status=draft&status=filed` and `?status=draft,filed` are equivalent. Omit for every status; nothing is filtered out by default, so completed returns appear alongside outstanding ones. To see only live work, list the seven statuses other than `completed`. . - `dateFrom` (string): Return only GST returns whose period ends on or after this NZ date. - `dateTo` (string): Return only GST returns whose period starts on or before this NZ date. - `dueAfter` (string): Return only GST returns due on or after this NZ date. - `dueBefore` (string): Return only GST returns due on or before this NZ date. - `includeFutureDrafts` (string): Include draft returns whose period has not started yet (default false) One of: `false`, `true`. - `page` (integer): Page number (default 1) - `pageSize` (integer): Items per page (default 100) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `entityId` (string, required) - `name` (string, required) - `description` (string, required) - `status` (string, required): One of: `rejected`, `completed`, `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `awaiting_payment`. - `dateFrom` (string, required) - `dateTo` (string, required) - `dueDate` (string, required) - `isOverdue` (boolean, required) - `netGstPosition` (number, nullable, required) - `unreconciledTransactionCount` (number, required) - `hasAmendment` (boolean, required) - `finalisedAt` (string, nullable, required) - `irdFiledAt` (string, nullable, required) - `updatedAt` (string, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Invalid query parameters - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `401`: Unauthorized - invalid or missing credentials - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `404`: Entity not found or not accessible with these credentials - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `500`: Internal server error - `error` (string): Error message. - `code` (string): Error code for programmatic handling. ### Example (Node SDK) ```ts const page = await prosaic.gstReturns.listForEntity(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/gst-returns \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get a single GST return with its IRD box amounts `GET /api/public/v1/entities/{entityId}/gst-returns/{gstReturnId}` SDK: `prosaic.gstReturns.retrieve(entityId, gstReturnId)` Returns one GST return, including the IRD return boxes 5 to 15. **Where the numbers come from depends on the return's status**, and `amountsSource` says which. A `draft` return has no persisted totals, so the boxes are calculated live from posted journal lines and will move as coding changes — `amountsSource` is `calculated`. Every other status reads the snapshot taken at finalisation, which is what was, or will be, filed with IRD — `amountsSource` is `finalised`. **Period and due dates are New Zealand calendar days** (`YYYY-MM-DD`), not UTC instants. IRD submission keys, raw IRD response payloads and amendment original values are internal and are never returned. ### Path parameters - `entityId` (string, required) - `gstReturnId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `amountsSource` (string, required): One of: `finalised`, `calculated`. - `totalSalesAndIncome` (number, nullable, required) - `zeroRatedSupplies` (number, nullable, required) - `netGstSalesAndIncome` (number, nullable, required) - `totalGstSalesAndIncome` (number, nullable, required) - `debitAdjustments` (number, nullable, required) - `lateClaimsAmount` (number, nullable, required) - `lateClaimsType` (string, nullable, required): One of: `sales`, `purchases`. - `totalDebitAdjustments` (number, nullable, required) - `totalGstCollected` (number, nullable, required) - `totalPurchasesAndExpenses` (number, nullable, required) - `totalGstCreditsOnPurchasesAndExpenses` (number, nullable, required) - `creditAdjustments` (number, nullable, required) - `totalCreditAdjustments` (number, nullable, required) - `totalGstCredit` (number, nullable, required) - `id` (string, required) - `entityId` (string, required) - `name` (string, required) - `description` (string, required) - `status` (string, required): One of: `rejected`, `completed`, `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `awaiting_payment`. - `dateFrom` (string, required) - `dateTo` (string, required) - `dueDate` (string, required) - `isOverdue` (boolean, required) - `netGstPosition` (number, nullable, required) - `unreconciledTransactionCount` (number, required) - `hasAmendment` (boolean, required) - `finalisedAt` (string, nullable, required) - `irdFiledAt` (string, nullable, required) - `updatedAt` (string, required) - `meta` (object) - `count` (number, required) - `400`: Malformed GST return id - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `401`: Unauthorized - invalid or missing credentials - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `404`: No such GST return for this entity - `error` (string): Error message. - `code` (string): Error code for programmatic handling. - `500`: Internal server error - `error` (string): Error message. - `code` (string): Error code for programmatic handling. ### Example (Node SDK) ```ts const { data } = await prosaic.gstReturns.retrieve(entityId, gstReturnId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/gst-returns/$GST_RETURN_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Contacts > Customers and suppliers: create, update, archive, restore and delete them. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List contacts `GET /api/public/v1/contacts` SDK: `prosaic.contacts.list(params)` Returns non-deleted contacts from entities visible in the active workspace. ### Query parameters - `entityId` (string) - `type` (string): One of: `BUSINESS`, `INDIVIDUAL`. - `status` (string): One of: `active`, `archived`, `all`. - `updatedSince` (string) - `page` (integer): Default: `1`. - `pageSize` (integer): Default: `100`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Invalid query parameters. - `401`: Unauthorized. - `403`: Insufficient role or token scope. - `500`: Internal server error. ### Example (Node SDK) ```ts const page = await prosaic.contacts.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/contacts \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get a contact `GET /api/public/v1/entities/{entityId}/contacts/{contactId}` SDK: `prosaic.contacts.retrieve(entityId, contactId)` Returns one active or archived contact belonging to the path entity. ### Path parameters - `entityId` (string, required) - `contactId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - One of — type: BUSINESS: - `type` (string, required): One of: `BUSINESS`. - `people` (array of objects, required) - `id` (string, required) - `displayName` (string, required) - `receivesInvoices` (boolean, required) - `status` (string, required): One of: `active`, `archived`. - `archivedAt` (string, date-time, nullable, required) - `emails` (array of objects, required) - `id` (string, required) - `email` (string, required) - `label` (string, nullable, required) - `id` (string, required) - `workspaceId` (string, required) - `entityId` (string, required) - `status` (string, required): One of: `active`, `archived`. - `displayName` (string, required) - `legalName` (string, nullable, required) - `identifierScheme` (string, nullable, required) - `identifier` (string, nullable, required) - `gstNumber` (string, nullable, required) - `website` (string, nullable, required) - `notes` (string, nullable, required) - `invoiceNotes` (string, nullable, required) - `organisationId` (string, nullable, required) - `receivesInvoices` (boolean, required) - `addresses` (array of objects, required) - `id` (string, required) - `label` (string) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `attentionTo` (string) - `addressLines` (array of strings, required) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `countryCode` (string, required) - `isInvoiceDefault` (boolean, required) - `phones` (array of objects, required) - `id` (string, required) - `label` (string) - `number` (string, required) - `isPrimary` (boolean, required) - `organisation` (object, nullable, required) - `id` (string, required) - `displayName` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `archivedAt` (string, date-time, nullable, required) - One of — type: INDIVIDUAL: - `type` (string, required): One of: `INDIVIDUAL`. - `emails` (array of objects, required) - `id` (string, required) - `email` (string, required) - `label` (string, nullable, required) - `id` (string, required) - `workspaceId` (string, required) - `entityId` (string, required) - `status` (string, required): One of: `active`, `archived`. - `displayName` (string, required) - `legalName` (string, nullable, required) - `identifierScheme` (string, nullable, required) - `identifier` (string, nullable, required) - `gstNumber` (string, nullable, required) - `website` (string, nullable, required) - `notes` (string, nullable, required) - `invoiceNotes` (string, nullable, required) - `organisationId` (string, nullable, required) - `receivesInvoices` (boolean, required) - `addresses` (array of objects, required) - `id` (string, required) - `label` (string) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `attentionTo` (string) - `addressLines` (array of strings, required) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `countryCode` (string, required) - `isInvoiceDefault` (boolean, required) - `phones` (array of objects, required) - `id` (string, required) - `label` (string) - `number` (string, required) - `isPrimary` (boolean, required) - `organisation` (object, nullable, required) - `id` (string, required) - `displayName` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `archivedAt` (string, date-time, nullable, required) - `400`: Invalid contact ID. - `401`: Unauthorized. - `403`: Insufficient workspace role. - `404`: Contact or entity not found. - `500`: Internal server error. ### Example (Node SDK) ```ts const { data } = await prosaic.contacts.retrieve(entityId, contactId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a contact `POST /api/public/v1/entities/{entityId}/contacts` SDK: `prosaic.contacts.create(entityId, params)` Creates a contact in the path entity and returns its public representation. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - One of — With displayName, type: - `displayName` (string, required) - `type` (string, required): One of: `BUSINESS`, `INDIVIDUAL`. - `email` (object) - `email` (string, required) - `label` (string) - `people` (array of objects) - `receivesInvoices` (boolean) - `id` (string) - `email` (string) - `label` (string) - `displayName` (string) - `phones` (array of objects) - `id` (string, required) - `number` (string, required) - `label` (string) - `isPrimary` (boolean) - `addresses` (array of objects) - `id` (string, required) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `addressLines` (array of strings, required) - `countryCode` (string, required) - `label` (string) - `attentionTo` (string) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `isInvoiceDefault` (boolean) - `linkPastInvoices` (boolean) - `legalName` (string) - `identifierScheme` (string) - `identifier` (string) - `gstNumber` (string) - `website` (string) - `notes` (string) - `invoiceNotes` (string) - One of — With people: - `people` (array of objects, required) - `receivesInvoices` (boolean) - `id` (string) - `email` (string) - `label` (string) - `displayName` (string) ### Responses - `201`: Successful response - `data` (object, required) - One of — type: BUSINESS: - `type` (string, required): One of: `BUSINESS`. - `people` (array of objects, required) - `id` (string, required) - `displayName` (string, required) - `receivesInvoices` (boolean, required) - `status` (string, required): One of: `active`, `archived`. - `archivedAt` (string, date-time, nullable, required) - `emails` (array of objects, required) - `id` (string, required) - `email` (string, required) - `label` (string, nullable, required) - `id` (string, required) - `workspaceId` (string, required) - `entityId` (string, required) - `status` (string, required): One of: `active`, `archived`. - `displayName` (string, required) - `legalName` (string, nullable, required) - `identifierScheme` (string, nullable, required) - `identifier` (string, nullable, required) - `gstNumber` (string, nullable, required) - `website` (string, nullable, required) - `notes` (string, nullable, required) - `invoiceNotes` (string, nullable, required) - `organisationId` (string, nullable, required) - `receivesInvoices` (boolean, required) - `addresses` (array of objects, required) - `id` (string, required) - `label` (string) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `attentionTo` (string) - `addressLines` (array of strings, required) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `countryCode` (string, required) - `isInvoiceDefault` (boolean, required) - `phones` (array of objects, required) - `id` (string, required) - `label` (string) - `number` (string, required) - `isPrimary` (boolean, required) - `organisation` (object, nullable, required) - `id` (string, required) - `displayName` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `archivedAt` (string, date-time, nullable, required) - One of — type: INDIVIDUAL: - `type` (string, required): One of: `INDIVIDUAL`. - `emails` (array of objects, required) - `id` (string, required) - `email` (string, required) - `label` (string, nullable, required) - `id` (string, required) - `workspaceId` (string, required) - `entityId` (string, required) - `status` (string, required): One of: `active`, `archived`. - `displayName` (string, required) - `legalName` (string, nullable, required) - `identifierScheme` (string, nullable, required) - `identifier` (string, nullable, required) - `gstNumber` (string, nullable, required) - `website` (string, nullable, required) - `notes` (string, nullable, required) - `invoiceNotes` (string, nullable, required) - `organisationId` (string, nullable, required) - `receivesInvoices` (boolean, required) - `addresses` (array of objects, required) - `id` (string, required) - `label` (string) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `attentionTo` (string) - `addressLines` (array of strings, required) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `countryCode` (string, required) - `isInvoiceDefault` (boolean, required) - `phones` (array of objects, required) - `id` (string, required) - `label` (string) - `number` (string, required) - `isPrimary` (boolean, required) - `organisation` (object, nullable, required) - `id` (string, required) - `displayName` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `archivedAt` (string, date-time, nullable, required) - `linkedInvoiceCount` (number, required) - `400`: Invalid JSON - `401`: Unauthorized. - `403`: Insufficient workspace role or entity permission. - `404`: Entity not found. - `500`: Internal server error. ### Example (Node SDK) ```ts const { data } = await prosaic.contacts.create(entityId, { displayName: 'Example Ltd', type: 'BUSINESS', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Example Ltd", "type": "BUSINESS" }' ``` ## Update a contact `PATCH /api/public/v1/entities/{entityId}/contacts/{contactId}` SDK: `prosaic.contacts.update(entityId, contactId, params)` Updates only the supplied mutable fields on an active contact. Omitted fields, including nested email labels and person invoice preferences, are unchanged; send null to clear an email label. Type and entity cannot be changed. ### Path parameters - `entityId` (string, required) - `contactId` (string, required) ### Request body Content type: `application/json` - `displayName` (string) - `email` (object, nullable) - `email` (string, required) - `label` (string, nullable) - `people` (array of objects) - `receivesInvoices` (boolean) - `id` (string) - `email` (string) - `label` (string) - `displayName` (string) - `phones` (array of objects) - `id` (string, required) - `number` (string, required) - `label` (string) - `isPrimary` (boolean) - `addresses` (array of objects) - `id` (string, required) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `addressLines` (array of strings, required) - `countryCode` (string, required) - `label` (string) - `attentionTo` (string) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `isInvoiceDefault` (boolean) - `linkPastInvoices` (boolean) - `legalName` (string, nullable) - `identifierScheme` (string, nullable) - `identifier` (string, nullable) - `gstNumber` (string, nullable) - `website` (string, nullable) - `notes` (string, nullable) - `invoiceNotes` (string, nullable) ### Responses - `200`: Successful response - `data` (object, required) - One of — type: BUSINESS: - `type` (string, required): One of: `BUSINESS`. - `people` (array of objects, required) - `id` (string, required) - `displayName` (string, required) - `receivesInvoices` (boolean, required) - `status` (string, required): One of: `active`, `archived`. - `archivedAt` (string, date-time, nullable, required) - `emails` (array of objects, required) - `id` (string, required) - `email` (string, required) - `label` (string, nullable, required) - `id` (string, required) - `workspaceId` (string, required) - `entityId` (string, required) - `status` (string, required): One of: `active`, `archived`. - `displayName` (string, required) - `legalName` (string, nullable, required) - `identifierScheme` (string, nullable, required) - `identifier` (string, nullable, required) - `gstNumber` (string, nullable, required) - `website` (string, nullable, required) - `notes` (string, nullable, required) - `invoiceNotes` (string, nullable, required) - `organisationId` (string, nullable, required) - `receivesInvoices` (boolean, required) - `addresses` (array of objects, required) - `id` (string, required) - `label` (string) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `attentionTo` (string) - `addressLines` (array of strings, required) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `countryCode` (string, required) - `isInvoiceDefault` (boolean, required) - `phones` (array of objects, required) - `id` (string, required) - `label` (string) - `number` (string, required) - `isPrimary` (boolean, required) - `organisation` (object, nullable, required) - `id` (string, required) - `displayName` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `archivedAt` (string, date-time, nullable, required) - One of — type: INDIVIDUAL: - `type` (string, required): One of: `INDIVIDUAL`. - `emails` (array of objects, required) - `id` (string, required) - `email` (string, required) - `label` (string, nullable, required) - `id` (string, required) - `workspaceId` (string, required) - `entityId` (string, required) - `status` (string, required): One of: `active`, `archived`. - `displayName` (string, required) - `legalName` (string, nullable, required) - `identifierScheme` (string, nullable, required) - `identifier` (string, nullable, required) - `gstNumber` (string, nullable, required) - `website` (string, nullable, required) - `notes` (string, nullable, required) - `invoiceNotes` (string, nullable, required) - `organisationId` (string, nullable, required) - `receivesInvoices` (boolean, required) - `addresses` (array of objects, required) - `id` (string, required) - `label` (string) - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`. - `attentionTo` (string) - `addressLines` (array of strings, required) - `sublocality` (string) - `locality` (string) - `administrativeArea` (string) - `postalCode` (string) - `sortingCode` (string) - `countryCode` (string, required) - `isInvoiceDefault` (boolean, required) - `phones` (array of objects, required) - `id` (string, required) - `label` (string) - `number` (string, required) - `isPrimary` (boolean, required) - `organisation` (object, nullable, required) - `id` (string, required) - `displayName` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `archivedAt` (string, date-time, nullable, required) - `linkedInvoiceCount` (number, required) - `400`: Invalid ID - `401`: Unauthorized. - `403`: Insufficient workspace role or entity permission. - `404`: Contact or entity not found. - `500`: Internal server error. ### Example (Node SDK) ```ts const { data } = await prosaic.contacts.update(entityId, contactId, { displayName: 'Example Ltd', email: { email: 'accounts@example.com', }, people: [ { receivesInvoices: true, id: 'ID', email: 'accounts@example.com', label: 'string', displayName: 'Example Ltd', }, ], phones: [ { id: 'ID', number: 'string', }, ], addresses: [ { id: 'ID', type: 'BILLING', addressLines: ['string'], countryCode: 'COUNTRY_CODE', }, ], linkPastInvoices: true, legalName: 'Example Ltd', identifierScheme: 'string', identifier: 'string', gstNumber: 'string', website: 'string', notes: 'string', invoiceNotes: 'string', }); ``` ### Example (curl) ```bash curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Example Ltd", "email": { "email": "accounts@example.com" }, "people": [ { "receivesInvoices": true, "id": "ID", "email": "accounts@example.com", "label": "string", "displayName": "Example Ltd" } ], "phones": [ { "id": "ID", "number": "string" } ], "addresses": [ { "id": "ID", "type": "BILLING", "addressLines": [ "string" ], "countryCode": "COUNTRY_CODE" } ], "linkPastInvoices": true, "legalName": "Example Ltd", "identifierScheme": "string", "identifier": "string", "gstNumber": "string", "website": "string", "notes": "string", "invoiceNotes": "string" }' ``` ## Restore a contact `POST /api/public/v1/entities/{entityId}/contacts/{contactId}/restore` SDK: `prosaic.contacts.restore(entityId, contactId, params)` Restores an archived contact and optionally the people archived with the same business operation. ### Path parameters - `entityId` (string, required) - `contactId` (string, required) ### Request body Content type: `application/json` - `restorePeople` (boolean) ### Responses - `200`: Successful response - `status` (string, required): One of: `restored`. - `400`: Invalid contact ID - `401`: Unauthorized. - `403`: Insufficient workspace role or entity permission. - `404`: Contact or entity not found. - `500`: Internal server error. ### Example (Node SDK) ```ts const result = await prosaic.contacts.restore(entityId, contactId, { restorePeople: true, }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID/restore \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "restorePeople": true }' ``` ## Delete a contact `DELETE /api/public/v1/entities/{entityId}/contacts/{contactId}` SDK: `prosaic.contacts.del(entityId, contactId)` Soft-deletes an active contact that has no invoice history. ### Path parameters - `entityId` (string, required) - `contactId` (string, required) ### Responses - `200`: Successful response - `status` (string, required): One of: `last-person`, `deleted`, `has-history`. - `400`: Invalid contact ID. - `401`: Unauthorized. - `403`: Insufficient workspace role or entity permission. - `404`: Contact or entity not found. - `409`: Contact has invoice history or removal would leave a business without a person to invoice. - `500`: Internal server error. ### Example (Node SDK) ```ts const result = await prosaic.contacts.del(entityId, contactId); ``` ### Example (curl) ```bash curl -X DELETE https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Archive a contact `POST /api/public/v1/entities/{entityId}/contacts/{contactId}/archive` SDK: `prosaic.contacts.archive(entityId, contactId, params)` Archives an active contact, optionally archiving a business's people with it. ### Path parameters - `entityId` (string, required) - `contactId` (string, required) ### Request body Content type: `application/json` - `archivePeople` (boolean) ### Responses - `200`: Successful response - `status` (string, required): One of: `archived`, `last-person`. - `400`: Invalid contact ID - `401`: Unauthorized. - `403`: Insufficient workspace role or entity permission. - `404`: Contact or entity not found. - `409`: Archiving would leave a live business without a person to invoice. - `500`: Internal server error. ### Example (Node SDK) ```ts const result = await prosaic.contacts.archive(entityId, contactId, { archivePeople: true, }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID/archive \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "archivePeople": true }' ``` --- # Invoices > Finalised invoices: create, read and list them. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List invoices `GET /api/public/v1/invoices` SDK: `prosaic.invoices.list(params)` Returns invoices in the active workspace that the authenticated user can access. Results are paginated and can be narrowed by client or entity. When both filters are supplied, an invoice must match both. ### Query parameters - `entityId` (string): Return invoices for one entity. - `clientId` (string): Return invoices whose entity is associated with this client user. - `status` (string): Filter by persisted invoice lifecycle status. One of: `DRAFT`, `FINALISED`, `PAID`, `VOIDED`. - `updatedSince` (string): Return invoices updated on or after this ISO 8601 timestamp. - `page` (integer): Default: `1`. - `pageSize` (integer): Default: `20`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `entityId` (string, required) - `workspaceId` (string, required) - `fileId` (string, nullable, required) - `invoiceNumber` (string, nullable, required) - `status` (string, required) - `taxMode` (string, required) - `issueDate` (string, date-time, required) - `dueDate` (string, date-time, nullable, required) - `sentAt` (string, date-time, nullable, required) - `recipientName` (string, required) - `recipientEmail` (string, nullable, required) - `recipientAddress` (string, nullable, required) - `bankAccountId` (string, nullable, required) - `bankAccountName` (string, nullable, required) - `subtotal` (number, required) - `taxTotal` (number, required) - `total` (number, required) - `amountDue` (number, nullable, required) - `notes` (string, nullable, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `lines` (array of objects, required) - `id` (string, required) - `description` (string, required) - `quantity` (number, required) - `unitPrice` (number, required) - `taxRate` (number, required) - `taxRateCode` (string, nullable, required) - `entityAccountId` (string, nullable, required) - `amount` (number, required) - `taxAmount` (number, required) - `position` (number, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Invalid query parameters. - `401`: Unauthorized. - `403`: Insufficient role. - `404`: Workspace not found. - `500`: Internal server error. ### Example (Node SDK) ```ts const page = await prosaic.invoices.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/invoices \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get an invoice by ID for an entity `GET /api/public/v1/entities/{entityId}/invoices/{invoiceId}` SDK: `prosaic.invoices.retrieve(entityId, invoiceId)` ### Path parameters - `entityId` (string, required) - `invoiceId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `entityId` (string, required) - `workspaceId` (string, required) - `fileId` (string, nullable, required) - `invoiceNumber` (string, nullable, required) - `status` (string, required) - `taxMode` (string, required) - `issueDate` (string, date-time, required) - `dueDate` (string, date-time, nullable, required) - `sentAt` (string, date-time, nullable, required) - `recipientName` (string, required) - `recipientEmail` (string, nullable, required) - `recipientAddress` (string, nullable, required) - `bankAccountId` (string, nullable, required) - `bankAccountName` (string, nullable, required) - `subtotal` (number, required) - `taxTotal` (number, required) - `total` (number, required) - `amountDue` (number, nullable, required) - `notes` (string, nullable, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `lines` (array of objects, required) - `id` (string, required) - `description` (string, required) - `quantity` (number, required) - `unitPrice` (number, required) - `taxRate` (number, required) - `taxRateCode` (string, nullable, required) - `entityAccountId` (string, nullable, required) - `amount` (number, required) - `taxAmount` (number, required) - `position` (number, required) - `400`: Invalid invoice ID. - `401`: Unauthorized. - `404`: Invoice, entity, or workspace not found. - `500`: Internal server error. ### Example (Node SDK) ```ts const { data } = await prosaic.invoices.retrieve(entityId, invoiceId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/invoices/$INVOICE_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a finalised invoice `POST /api/public/v1/entities/{entityId}/invoices` SDK: `prosaic.invoices.create(entityId, params)` Creates a complete, finalised invoice for the specified entity. The entity is taken from the URL; `status` cannot be supplied. Finalised invoices are not automatically delivered to the recipient. Where the workspace records invoices as receivables (accrual accounting), finalising posts the invoice to the ledger, which needs a `contactId`. Without one the request is refused with 409 `INVOICE_NOT_EDITABLE` and nothing is created. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `taxMode` (string, required): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`. - `issueDate` (string, required) - `recipientName` (string, required) - `lines` (array of objects, required) - `description` (string, required) - `quantity` (string, required) - `unitPrice` (string, required) - `taxRateCode` (string, required) - `entityAccountId` (string, required) - `taxRate` (string) - `bankAccountId` (string, nullable) - `notes` (string, nullable) - `contactId` (string, nullable) - `dueDate` (string, nullable) - `bankAccountName` (string, nullable) - `invoiceNumber` (string) - `recipientEmail` (string, nullable) - `recipientAddress` (string, nullable) - `recipientEmails` (array of strings) ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `entityId` (string, required) - `workspaceId` (string, required) - `fileId` (string, nullable, required) - `invoiceNumber` (string, nullable, required) - `status` (string, required) - `taxMode` (string, required) - `issueDate` (string, date-time, required) - `dueDate` (string, date-time, nullable, required) - `sentAt` (string, date-time, nullable, required) - `recipientName` (string, required) - `recipientEmail` (string, nullable, required) - `recipientAddress` (string, nullable, required) - `bankAccountId` (string, nullable, required) - `bankAccountName` (string, nullable, required) - `subtotal` (number, required) - `taxTotal` (number, required) - `total` (number, required) - `amountDue` (number, nullable, required) - `notes` (string, nullable, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `lines` (array of objects, required) - `id` (string, required) - `description` (string, required) - `quantity` (number, required) - `unitPrice` (number, required) - `taxRate` (number, required) - `taxRateCode` (string, nullable, required) - `entityAccountId` (string, nullable, required) - `amount` (number, required) - `taxAmount` (number, required) - `position` (number, required) - `400`: Invalid request or invoice input, or system account setup is missing or invalid (SYSTEM_ACCOUNT_VALIDATION). - `401`: Unauthorized. - `404`: Entity or workspace not found. - `409`: The invoice can't be finalised, for example it has no contact where the workspace uses accrual accounting. - `500`: Invoice creation failed. ### Example (Node SDK) ```ts const { data } = await prosaic.invoices.create(entityId, { taxMode: 'NO_TAX', issueDate: '2026-04-01', recipientName: 'Example Ltd', lines: [ { description: 'Office supplies', quantity: '1', unitPrice: '100.00', taxRateCode: 'TAX_RATE_CODE', entityAccountId: 'ENTITY_ACCOUNT_ID', }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/invoices \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxMode": "NO_TAX", "issueDate": "2026-04-01", "recipientName": "Example Ltd", "lines": [ { "description": "Office supplies", "quantity": "1", "unitPrice": "100.00", "taxRateCode": "TAX_RATE_CODE", "entityAccountId": "ENTITY_ACCOUNT_ID" } ] }' ``` --- # Fixed assets > Fixed assets and their types, for depreciation. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List fixed asset types (categories) for an entity `GET /api/public/v1/entities/{entityId}/fixed-asset-types` SDK: `prosaic.fixedAssetTypes.list(entityId)` Returns all fixed asset types (categories) configured for the specified entity. Asset types define default depreciation settings and account mappings. Includes mappedCode on accounts to support external system integrations (e.g., Xero). ### Path parameters - `entityId` (string, required) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `depreciationMethod` (string, required) - `usefulLifeYears` (number, nullable, required) - `depreciationRate` (number, nullable, required) - `assetAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `accumulatedDepreciationAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `depreciationExpenseAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `privateUseAccount` (object, nullable, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `meta` (object) - `count` (number, required) - `400`: Bad request - missing or invalid parameters - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.fixedAssetTypes.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/fixed-asset-types \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a new fixed asset type (category) `POST /api/public/v1/entities/{entityId}/fixed-asset-types` SDK: `prosaic.fixedAssetTypes.create(entityId, params)` Creates a new fixed asset type for the specified entity. Asset types define default depreciation settings and account mappings for fixed assets. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `name` (string, required) - `depreciationMethod` (string, required) - `assetAccountId` (string, required) - `accumulatedDepreciationAccountId` (string, required) - `depreciationExpenseAccountId` (string, required) - `privateUseAccountId` (string, nullable, required) - `usefulLifeYears` (number, nullable) - `depreciationRate` (number, nullable) ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `depreciationMethod` (string, required) - `usefulLifeYears` (number, nullable, required) - `depreciationRate` (number, nullable, required) - `assetAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `accumulatedDepreciationAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `depreciationExpenseAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `privateUseAccount` (object, nullable, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `mappedCode` (string, nullable, required) - `400`: Bad request - validation failed - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.fixedAssetTypes.create(entityId, { name: 'Example Ltd', depreciationMethod: 'string', assetAccountId: 'ASSET_ACCOUNT_ID', accumulatedDepreciationAccountId: 'ACCUMULATED_DEPRECIATION_ACCOUNT_ID', depreciationExpenseAccountId: 'DEPRECIATION_EXPENSE_ACCOUNT_ID', privateUseAccountId: 'PRIVATE_USE_ACCOUNT_ID', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/fixed-asset-types \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "depreciationMethod": "string", "assetAccountId": "ASSET_ACCOUNT_ID", "accumulatedDepreciationAccountId": "ACCUMULATED_DEPRECIATION_ACCOUNT_ID", "depreciationExpenseAccountId": "DEPRECIATION_EXPENSE_ACCOUNT_ID", "privateUseAccountId": "PRIVATE_USE_ACCOUNT_ID" }' ``` ## List fixed assets for an entity `GET /api/public/v1/entities/{entityId}/fixed-assets` SDK: `prosaic.fixedAssets.list(entityId, params)` Returns paginated fixed assets for the specified entity. Includes asset details, depreciation information, and current book values. ### Path parameters - `entityId` (string, required) ### Query parameters - `page` (integer): Page number (starts at 1) Default: `1`. - `pageSize` (integer): Number of items per page. Default: `20`. - `status` (string): Filter by asset status. One of: `draft`, `active`, `disposed`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `assetNumber` (string, nullable, required) - `description` (string, nullable, required) - `status` (string, required) - `purchaseDate` (string, nullable, required) - `startDate` (string, nullable, required) - `purchasePrice` (number, nullable, required) - `residualValue` (number, nullable, required) - `businessUsePercentage` (number, nullable, required) - `initialAccumulatedDepreciation` (number, nullable, required) - `depreciationMethod` (string, nullable, required) - `usefulLifeYears` (number, nullable, required) - `depreciationRate` (number, nullable, required) - `methodParams` (any, required) - `disposalDate` (string, nullable, required) - `disposalProceeds` (number, nullable, required) - `bookValue` (number, nullable, required) - `assetType` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `mostRecentDepreciationRun` (object, nullable, required) - `year` (number, required) - `month` (number, required) - `accumulatedDepreciation` (number, required) - `createdAt` (string, required) - `updatedAt` (string, nullable, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Bad request - missing or invalid parameters - `error` (string) - `code` (string) - `field` (string) - `value` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const page = await prosaic.fixedAssets.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/fixed-assets \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get a single fixed asset by ID `GET /api/public/v1/entities/{entityId}/fixed-assets/{assetId}` SDK: `prosaic.fixedAssets.retrieve(entityId, assetId)` Returns a single fixed asset by its ID for the specified entity. Includes asset details, depreciation information, and current book value. ### Path parameters - `entityId` (string, required) - `assetId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `assetNumber` (string, nullable, required) - `description` (string, nullable, required) - `status` (string, required) - `purchaseDate` (string, nullable, required) - `startDate` (string, nullable, required) - `purchasePrice` (number, nullable, required) - `residualValue` (number, nullable, required) - `businessUsePercentage` (number, nullable, required) - `initialAccumulatedDepreciation` (number, nullable, required) - `depreciationMethod` (string, nullable, required) - `usefulLifeYears` (number, nullable, required) - `depreciationRate` (number, nullable, required) - `methodParams` (any, required) - `disposalDate` (string, nullable, required) - `disposalProceeds` (number, nullable, required) - `bookValue` (number, nullable, required) - `assetType` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `mostRecentDepreciationRun` (object, nullable, required) - `year` (number, required) - `month` (number, required) - `accumulatedDepreciation` (number, required) - `createdAt` (string, required) - `updatedAt` (string, nullable, required) - `meta` (object) - `count` (number, required) - `400`: Bad request - missing or invalid parameters - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity or asset - `error` (string) - `code` (string) - `404`: Not found - Asset not found - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.fixedAssets.retrieve(entityId, assetId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/fixed-assets/$ASSET_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a new fixed asset `POST /api/public/v1/entities/{entityId}/fixed-assets` SDK: `prosaic.fixedAssets.create(entityId, params)` Creates a new fixed asset for the specified entity. Can create the asset as either a draft or immediately as active. When creating as active, all required fields must be provided and pass validation. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - One of — status: active: - `name` (string, required) - `entityFixedAssetTypeId` (any, required) - `purchaseDate` (string, required) - `startDate` (string, required) - `purchasePrice` (any, required) - `depreciationMethod` (string, required) - `assetNumber` (string) - `description` (string) - `costLimit` (any) - `residualValue` (any) - `businessUsePercentage` (number) - `initialAccumulatedDepreciation` (any) - `usefulLifeYears` (number) - `depreciationRate` (number, nullable) - `immediateExpensePercentage` (number) - `dimensionOptionIds` (array of strings) - `status` (string, required): One of: `active`. - One of — status: draft: - `name` (string, required) - `entityFixedAssetTypeId` (string, nullable) - `assetNumber` (string) - `description` (string) - `purchaseDate` (string) - `startDate` (string) - `purchasePrice` (any) - `costLimit` (any) - `residualValue` (any) - `businessUsePercentage` (number) - `initialAccumulatedDepreciation` (any) - `depreciationMethod` (string, nullable) - `usefulLifeYears` (number) - `depreciationRate` (number, nullable) - `immediateExpensePercentage` (number) - `dimensionOptionIds` (array of strings) - `status` (string): One of: `draft`. ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `assetNumber` (string, nullable, required) - `description` (string, nullable, required) - `status` (string, required) - `purchaseDate` (string, nullable, required) - `startDate` (string, nullable, required) - `purchasePrice` (number, nullable, required) - `residualValue` (number, nullable, required) - `businessUsePercentage` (number, nullable, required) - `initialAccumulatedDepreciation` (number, nullable, required) - `depreciationMethod` (string, nullable, required) - `usefulLifeYears` (number, nullable, required) - `depreciationRate` (number, nullable, required) - `methodParams` (any, required) - `disposalDate` (string, nullable, required) - `disposalProceeds` (number, nullable, required) - `bookValue` (number, nullable, required) - `assetType` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `mostRecentDepreciationRun` (object, nullable, required) - `year` (number, required) - `month` (number, required) - `accumulatedDepreciation` (number, required) - `createdAt` (string, required) - `updatedAt` (string, nullable, required) - `400`: Bad request - validation failed - `error` (string) - `code` (string) - `errors` (array of objects) - `field` (string) - `message` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `404`: Asset type not found - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.fixedAssets.create(entityId, { name: 'Example Ltd', entityFixedAssetTypeId: 'ENTITY_FIXED_ASSET_TYPE_ID', purchaseDate: '2026-04-01', startDate: '2026-04-01', purchasePrice: '100.00', depreciationMethod: 'string', status: 'active', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/fixed-assets \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "entityFixedAssetTypeId": "ENTITY_FIXED_ASSET_TYPE_ID", "purchaseDate": "2026-04-01", "startDate": "2026-04-01", "purchasePrice": "100.00", "depreciationMethod": "string", "status": "active" }' ``` ## Update a draft fixed asset `PATCH /api/public/v1/entities/{entityId}/fixed-assets/{assetId}` SDK: `prosaic.fixedAssets.update(entityId, assetId, params)` Updates only the supplied fields on a draft fixed asset. Omitted fields keep their stored values; send null to clear a nullable field. The asset's own depreciation method, rate and useful life override its asset type's defaults. Rate and useful life are exclusive: setting one clears the other, and method "none" clears both. Active and disposed assets cannot be edited here. ### Path parameters - `entityId` (string, required) - `assetId` (string, required) ### Request body Content type: `application/json` - `name` (string) - `dimensionOptionIds` (array of strings) - `depreciationRate` (number, nullable) - `purchaseDate` (string) - `startDate` (string) - `purchasePrice` (any) - `residualValue` (any) - `initialAccumulatedDepreciation` (any) - `entityFixedAssetTypeId` (string, nullable) - `assetNumber` (string, nullable) - `description` (string, nullable) - `businessUsePercentage` (number, nullable) - `depreciationMethod` (string, nullable): One of: `none`, `straight_line`, `diminishing_value`. - `usefulLifeYears` (number, nullable) - `immediateExpensePercentage` (number) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `assetNumber` (string, nullable, required) - `description` (string, nullable, required) - `status` (string, required) - `purchaseDate` (string, nullable, required) - `startDate` (string, nullable, required) - `purchasePrice` (number, nullable, required) - `residualValue` (number, nullable, required) - `businessUsePercentage` (number, nullable, required) - `initialAccumulatedDepreciation` (number, nullable, required) - `depreciationMethod` (string, nullable, required) - `usefulLifeYears` (number, nullable, required) - `depreciationRate` (number, nullable, required) - `methodParams` (any, required) - `disposalDate` (string, nullable, required) - `disposalProceeds` (number, nullable, required) - `bookValue` (number, nullable, required) - `assetType` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `mostRecentDepreciationRun` (object, nullable, required) - `year` (number, required) - `month` (number, required) - `accumulatedDepreciation` (number, required) - `createdAt` (string, required) - `updatedAt` (string, nullable, required) - `meta` (object) - `count` (number, required) - `400`: Invalid body, or depreciation, business use, asset number or dimension rules failed - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - No edit access to the specified entity - `404`: Fixed asset or asset type not found - `409`: The asset is not a draft - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.fixedAssets.update(entityId, assetId, { name: 'Example Ltd', dimensionOptionIds: ['DIMENSION_OPTION_ID'], depreciationRate: 1, purchaseDate: '2026-04-01', startDate: '2026-04-01', purchasePrice: '100.00', residualValue: 'string', initialAccumulatedDepreciation: 'string', entityFixedAssetTypeId: 'ENTITY_FIXED_ASSET_TYPE_ID', assetNumber: 'string', description: 'Office supplies', businessUsePercentage: 1, depreciationMethod: 'none', usefulLifeYears: 1, immediateExpensePercentage: 1, }); ``` ### Example (curl) ```bash curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/fixed-assets/$ASSET_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "dimensionOptionIds": [ "DIMENSION_OPTION_ID" ], "depreciationRate": 1, "purchaseDate": "2026-04-01", "startDate": "2026-04-01", "purchasePrice": "100.00", "residualValue": "string", "initialAccumulatedDepreciation": "string", "entityFixedAssetTypeId": "ENTITY_FIXED_ASSET_TYPE_ID", "assetNumber": "string", "description": "Office supplies", "businessUsePercentage": 1, "depreciationMethod": "none", "usefulLifeYears": 1, "immediateExpensePercentage": 1 }' ``` --- # Files > Upload files and list them, to attach to journals. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List files `GET /api/public/v1/entities/{entityId}/files` SDK: `prosaic.files.list(entityId, params)` Returns the entity's files, newest first: those filed under it or attached to it, excluding deleted files. Use a file's `id` in `fileIds` when creating a journal (`POST /api/public/v1/entities/{entityId}/journals`) or attaching files to one. Requires API key authentication and entity access. ### Path parameters - `entityId` (string, required) ### Query parameters - `search` (string): Part of the file name, matched in any case. - `limit` (integer): Most files to return. Default: `20`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `contentType` (string, required) - `size` (number, required) - `createdAt` (string, required) - `meta` (object) - `count` (number, required) - `400`: Invalid query parameters - `401`: Invalid or missing API key - `404`: Entity not found or not accessible ### Example (Node SDK) ```ts const { data } = await prosaic.files.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/files \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Upload a file `POST /api/public/v1/entities/{entityId}/files/upload` SDK: `prosaic.files.upload(entityId, file)` Uploads a file for an entity. Files must be validated against size (20MB) and type restrictions. Returns a fileId that can be used when creating or attaching to journals. Requires API key authentication and entity access. ### Path parameters - `entityId` (string, required) ### Request body Content type: `multipart/form-data` - `file` (string, binary, required): The file to upload (max 20MB). Accepted types — PDF, JPEG, PNG, GIF, WebP, CSV, plain text, Excel (XLS/XLSX), Word (DOC/DOCX), Outlook MSG. ### Responses - `201`: Successful response - `success` (boolean, required) - `file` (object, required) - `id` (string, required) - `filename` (string, required) - `name` (string, required) - `contentType` (string, required) - `size` (number, required) - `createdAt` (string, required) - `400`: Bad request - validation failed - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `403`: Forbidden - No access to the specified entity - `error` (string) - `code` (string) - `500`: Internal server error - Upload failed - `error` (string) ### Example (Node SDK) ```ts const result = await prosaic.files.upload(entityId, file); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/files/upload \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -F "file=@receipt.pdf" ``` --- # Dimensions > Tracking categories, such as Property or Department, whose options tag journal lines. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List dimensions `GET /api/public/v1/entities/{entityId}/dimensions` SDK: `prosaic.dimensions.list(entityId)` Returns the entity's active dimensions (tracking categories such as Property or Department) with their active options. Use each option's `id` as a value in `dimensionOptionIds` when creating journals (`POST /api/public/v1/entities/{entityId}/journals`) or reconciling transactions (`POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reconcile`). Archived dimensions and archived options are excluded. Requires API key authentication and entity access. ### Path parameters - `entityId` (string, required) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `typeKey` (string, required) - `enforcement` (string, required) - `options` (array of objects, required) - `id` (string, required) - `name` (string, required) - `code` (string, nullable, required) - `meta` (object) - `count` (number, required) - `401`: Invalid or missing API key - `403`: API key does not have access to this entity ### Example (Node SDK) ```ts const { data } = await prosaic.dimensions.list(entityId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/dimensions \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Clients > An accounting practice's clients, their bank accounts and transactions, and onboarding links. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List clients `GET /api/public/v1/clients` SDK: `prosaic.clients.list(params)` Returns client users (`client` and `standard_user` roles) in the workspace tied to the token. Callers authenticated as client or standard_user only ever receive their own client record, even within a shared workspace. Accountant-style roles receive the full list (subject to filters). ### Query parameters - `clientId` (string): Filter by specific client ID. - `email` (string): Filter by client email address. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `bankAccounts` (array of objects, required) - `id` (string, required) - `name` (string, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `404`: Workspace not found or access denied - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.clients.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/clients \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List client's bank transactions `GET /api/public/v1/clients/{clientId}/transactions` SDK: `prosaic.clients.listTransactions(clientId, params)` Returns paginated bank transactions for the specified client. Access control: - Authenticated user must be the client themselves, OR - Authenticated user must be in the same workspace as the client (accountant/advisor) Supports filtering by: - Bank account IDs (comma-separated) - Date range (dateFrom, dateTo) - Reconciliation status (reconciled | unreconciled) ### Path parameters - `clientId` (string, required) ### Query parameters - `bankAccountIds` (array of strings): Comma-separated list of bank account IDs to filter by. - `dateFrom` (string, date): Start date for filtering transactions (ISO 8601 format) - `dateTo` (string, date): End date for filtering transactions (ISO 8601 format) - `reconciliationStatus` (string): Filter by reconciliation status. One of: `reconciled`, `unreconciled`. - `page` (integer): Page number (starts at 1) Default: `1`. - `pageSize` (integer): Number of items per page. Default: `20`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `entityId` (string, nullable, required) - `reconciliationStatus` (string, required): One of: `reconciled`, `unreconciled`. - `journalId` (string, nullable, required) - `bankAccount` (object, required) - `id` (string, required) - `entityId` (string, nullable, required) - `externalId` (string, required) - `name` (string, required) - `alias` (string, nullable, required) - `institution` (string, nullable, required) - `accountNumber` (string, nullable, required) - `logoUrl` (string, nullable, required) - `type` (string, required) - `sourceType` (string, nullable, required) - `entityAccount` (object, nullable, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `merchant` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `provider` (string, nullable, required) - `identifier` (string, required) - `category` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `identifier` (string, required) - `user` (object, required) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `suggestions` (array of objects) - `id` (string, required) - `sourceType` (string, required) - `confidence` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `status` (string, required) - `ruleId` (string, nullable, required) - `ruleName` (string, nullable, required) - `lines` (array of objects, required) - `id` (string, required) - `proportion` (string, nullable, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `credit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `debit` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `entityAccountId` (string, required) - `entityAccount` (object, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `taxRateId` (string, nullable, required) - `taxRate` (object, nullable, required) - `id` (string, required) - `code` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `rate` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `id` (string, required) - `date` (string, date-time, required) - `amount` (string, required): Exact decimal serialized as a string. Use Decimal.js for arithmetic. - `description` (string, required) - `type` (string, required) - `particulars` (string, nullable, required) - `code` (string, nullable, required) - `reference` (string, nullable, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Bad request - invalid parameters - `error` (string) - `code` (string) - `401`: Unauthorized - Invalid or missing API key/token - `error` (string) - `403`: Forbidden - User does not have access to this client - `error` (string) - `404`: Client not found - `error` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const page = await prosaic.clients.listTransactions(clientId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/clients/$CLIENT_ID/transactions \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## List client's bank accounts `GET /api/public/v1/clients/{clientId}/bank-accounts` SDK: `prosaic.clients.listBankAccounts(clientId)` Returns all bank accounts belonging to the specified client. Access control: - Authenticated user must be the client themselves, OR - Authenticated user must be in the same workspace as the client (accountant/advisor) ### Path parameters - `clientId` (string, required) ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `entityId` (string, nullable, required) - `externalId` (string, required) - `name` (string, required) - `alias` (string, nullable, required) - `institution` (string, nullable, required) - `accountNumber` (string, nullable, required) - `logoUrl` (string, nullable, required) - `type` (string, required) - `sourceType` (string, nullable, required) - `entityAccount` (object, nullable, required) - `id` (string, required) - `updatedAt` (string) - `reportCategoryReviewedAt` (string, nullable) - `reportCategoryReviewVersion` (number) - `code` (string, required) - `name` (string, required) - `type` (string, required) - `subtype` (string, required) - `reportGroup` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `accountType` (string, required) - `reportCategory` (object, nullable, required) - `id` (string, required) - `key` (string, required) - `name` (string, required) - `status` (string, required) - `taxCode` (string, required) - `description` (string, nullable, required) - `mappedCode` (string, nullable, required) - `isSystem` (boolean, required) - `systemRole` (string, nullable) - `parentId` (string, nullable) - `isExcluded` (boolean) - `isIncluded` (boolean) - `source` (string): One of: `template`, `overridden`, `custom`. - `meta` (object) - `count` (number, required) - `401`: Unauthorized - Invalid or missing API key/token - `error` (string) - `403`: Forbidden - User does not have access to this client - `error` (string) - `404`: Client not found - `error` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.clients.listBankAccounts(clientId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/clients/$CLIENT_ID/bank-accounts \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a client `POST /api/public/v1/clients` SDK: `prosaic.clients.create(params)` Creates a new client in the workspace associated with the API key. If a client with the same email already exists, returns the existing client. ### Request body Content type: `application/json` - `name` (string, required) - `email` (string, required) - `tradingName` (string) - `sendInvite` (boolean) - `message` (string) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `email` (string, required) - `name` (string, nullable, required) - `tradingName` (string, nullable, required) - `createdAt` (string, date-time, required) - `bankAccounts` (array of objects, required) - `id` (string, required) - `name` (string, required) - `meta` (object) - `count` (number, required) - `400`: Validation failed - `error` (string) - `code` (string) - `details` (array of objects) - `401`: Unauthorized - Invalid or missing API key - `error` (string) - `404`: Workspace not found or access denied - `error` (string) - `code` (string) - `429`: Invitation email rate limit exceeded - `error` (string) - `code` (string) - `500`: Internal server error - `error` (string) - `code` (string) ### Example (Node SDK) ```ts const { data } = await prosaic.clients.create({ name: 'Example Ltd', email: 'accounts@example.com', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/clients \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "email": "accounts@example.com" }' ``` ## Create onboarding link `POST /api/public/v1/clients/{clientId}/onboarding` SDK: `prosaic.clients.createOnboardingLink(clientId, params)` ### Path parameters - `clientId` (string, required) ### Request body Content type: `application/json` - `integrationId` (string) - `callbackURL` (string) - `state` (string) ### Responses - `200`: Successful response - `data` (object, required) - `magicLink` (string, required) - `meta` (object) - `count` (number, required) ### Example (Node SDK) ```ts const { data } = await prosaic.clients.createOnboardingLink(clientId, { integrationId: 'INTEGRATION_ID', callbackURL: 'https://example.com/callback', state: 'string', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/clients/$CLIENT_ID/onboarding \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "integrationId": "INTEGRATION_ID", "callbackURL": "https://example.com/callback", "state": "string" }' ``` --- # Rules > Rules that act on bank transactions when their conditions match. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List rules `GET /api/public/v1/rules` SDK: `prosaic.rules.list(params)` Returns rules in the workspace associated with the API key. By default returns only active rules. ### Query parameters - `isActive` (string): Filter rules by active status. `true` (default) returns only active rules, `false` returns only inactive rules, `all` returns both. . One of: `all`, `false`, `true`. - `entityId` (string): Only rules whose scope reaches this entity: workspace-wide rules, rules on the entity's chart template, rules on the entity itself, and rules on any of its bank accounts. . - `page` (integer): Default: `1`. - `pageSize` (integer): Default: `50`. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `isActive` (boolean, required) - `targetType` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `conditions` (array of objects, required) - `id` (string, required) - `field` (string, required) - `operator` (string, required) - `value` (string, required) - `secondValue` (string, nullable, required) - `actions` (array of objects, required) - `id` (string, required) - `actionType` (string, required) - `payload` (any, required) - `scopes` (array of objects, required) - `id` (string, required) - `scopeType` (string, required) - `entity` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `bankAccount` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `accountTemplate` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `pagination` (object, required) - `currentPage` (number, required) - `pageSize` (number, required) - `totalCount` (number, required) - `totalPages` (number, required) - `hasNextPage` (boolean, required) - `hasPreviousPage` (boolean, required) - `400`: Validation failed - `401`: Unauthorized - `403`: Insufficient role - `404`: Workspace not found, or entityId is not in the workspace - `500`: Internal server error ### Example (Node SDK) ```ts const page = await prosaic.rules.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/rules \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get a rule by ID `GET /api/public/v1/rules/{ruleId}` SDK: `prosaic.rules.retrieve(ruleId)` ### Path parameters - `ruleId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `isActive` (boolean, required) - `targetType` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `conditions` (array of objects, required) - `id` (string, required) - `field` (string, required) - `operator` (string, required) - `value` (string, required) - `secondValue` (string, nullable, required) - `actions` (array of objects, required) - `id` (string, required) - `actionType` (string, required) - `payload` (any, required) - `scopes` (array of objects, required) - `id` (string, required) - `scopeType` (string, required) - `entity` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `bankAccount` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `accountTemplate` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `400`: Invalid rule ID - `401`: Unauthorized - `403`: Insufficient role - `404`: Rule or workspace not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.rules.retrieve(ruleId); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/rules/$RULE_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a rule `POST /api/public/v1/rules` SDK: `prosaic.rules.create(params)` Creates a new rule in the workspace associated with the API key. ### Request body Content type: `application/json` - `name` (string, required) - `conditions` (array of objects, required) - `field` (string, required): One of: `description`, `type`, `date`, `amount`, `category`, `merchant`. - `operator` (string, required): One of: `endsWith`, `startsWith`, `is`, `equals`, `gte`, `contains`, `gt`, `lt`, `lte`, `between`. - `value` (string, required) - `secondValue` (string, nullable) - `actions` (array of objects, required) - `actionType` (string, required): One of: `post_journal`, `tag_dimensions`. - `payload` (any, required) - `scopes` (array of objects, required) - `description` (string, nullable) - `isActive` (boolean) - `targetType` (string): One of: `bank_transaction`. - `source` (string): One of: `ai`, `manual`, `duplicate`, `transactions_filters`, `transactions_reconcile`, `dimension_proposal`, `demo_seed`. ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `isActive` (boolean, required) - `targetType` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `conditions` (array of objects, required) - `id` (string, required) - `field` (string, required) - `operator` (string, required) - `value` (string, required) - `secondValue` (string, nullable, required) - `actions` (array of objects, required) - `id` (string, required) - `actionType` (string, required) - `payload` (any, required) - `scopes` (array of objects, required) - `id` (string, required) - `scopeType` (string, required) - `entity` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `bankAccount` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `accountTemplate` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `400`: Validation failed. Covers both shape errors (missing/invalid fields) and action-payload semantic errors caught by the request schema (e.g. proportion lines must sum to 1). - `401`: Unauthorized - `403`: Insufficient role - `404`: Workspace not found - `422`: Rule failed service-level validation against workspace data (e.g. unknown tax rate codes, account codes not allowed by the action type). Distinct from 400, which is raised by the request schema before the service is called. - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.rules.create({ name: 'Example Ltd', conditions: [ { field: 'description', operator: 'endsWith', value: 'string', }, ], actions: [ { actionType: 'post_journal', payload: 'string', }, ], scopes: [ { scopeType: 'workspace', }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/rules \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "conditions": [ { "field": "description", "operator": "endsWith", "value": "string" } ], "actions": [ { "actionType": "post_journal", "payload": "string" } ], "scopes": [ { "scopeType": "workspace" } ] }' ``` ## Update a rule `PATCH /api/public/v1/rules/{ruleId}` SDK: `prosaic.rules.update(ruleId, params)` ### Path parameters - `ruleId` (string, required) ### Request body Content type: `application/json` - `name` (string) - `description` (string, nullable) - `isActive` (boolean) - `conditions` (array of objects) - `field` (string, required): One of: `description`, `type`, `date`, `amount`, `category`, `merchant`. - `operator` (string, required): One of: `endsWith`, `startsWith`, `is`, `equals`, `gte`, `contains`, `gt`, `lt`, `lte`, `between`. - `value` (string, required) - `secondValue` (string, nullable) - `targetType` (string): One of: `bank_transaction`. - `actions` (array of objects) - `actionType` (string, required): One of: `post_journal`, `tag_dimensions`. - `payload` (any, required) - `scopes` (array of objects) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `description` (string, nullable, required) - `isActive` (boolean, required) - `targetType` (string, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `conditions` (array of objects, required) - `id` (string, required) - `field` (string, required) - `operator` (string, required) - `value` (string, required) - `secondValue` (string, nullable, required) - `actions` (array of objects, required) - `id` (string, required) - `actionType` (string, required) - `payload` (any, required) - `scopes` (array of objects, required) - `id` (string, required) - `scopeType` (string, required) - `entity` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `bankAccount` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `accountTemplate` (object, nullable, required) - `id` (string, required) - `name` (string, required) - `400`: Validation failed. Covers both shape errors (missing/invalid fields) and action-payload semantic errors caught by the request schema (e.g. proportion lines must sum to 1). - `401`: Unauthorized - `403`: Insufficient role - `404`: Rule or workspace not found - `422`: Rule failed service-level validation against workspace data (e.g. unknown tax rate codes, account codes not allowed by the action type). Distinct from 400, which is raised by the request schema before the service is called. - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.rules.update(ruleId, { name: 'Example Ltd', description: 'Office supplies', isActive: true, conditions: [ { field: 'description', operator: 'endsWith', value: 'string', }, ], targetType: 'bank_transaction', actions: [ { actionType: 'post_journal', payload: 'string', }, ], scopes: [ { scopeType: 'workspace', }, ], }); ``` ### Example (curl) ```bash curl -X PATCH https://app.prosaic.works/api/public/v1/rules/$RULE_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "description": "Office supplies", "isActive": true, "conditions": [ { "field": "description", "operator": "endsWith", "value": "string" } ], "targetType": "bank_transaction", "actions": [ { "actionType": "post_journal", "payload": "string" } ], "scopes": [ { "scopeType": "workspace" } ] }' ``` ## Soft-delete a rule `DELETE /api/public/v1/rules/{ruleId}` SDK: `prosaic.rules.del(ruleId)` ### Path parameters - `ruleId` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `success` (boolean, required): One of: `true`. - `400`: Invalid rule ID - `401`: Unauthorized - `403`: Insufficient role - `404`: Rule or workspace not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.rules.del(ruleId); ``` ### Example (curl) ```bash curl -X DELETE https://app.prosaic.works/api/public/v1/rules/$RULE_ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Scheduled tasks > Prosaic AI tasks that run a prompt unattended on a schedule, and running one now. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## List scheduled tasks `GET /api/public/v1/scheduled-tasks` SDK: `prosaic.scheduledTasks.list()` Returns the Prosaic AI scheduled tasks in the workspace associated with the API key, newest first. ### Responses - `200`: Successful response - `data` (array of objects, required) - `id` (string, required) - `name` (string, required) - `prompt` (string, required) - `entityId` (string, nullable, required) - `cron` (string, required) - `schedule` (string, required) - `timezone` (string, required) - `isEnabled` (boolean, required) - `autoApproveWrites` (boolean, required) - `emailTo` (string, nullable, required) - `lastRunAt` (string, date-time, nullable, required) - `lastStatus` (string, nullable, required) - `lastError` (string, nullable, required) - `runCount` (number, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - `403`: Insufficient role - `404`: Workspace not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.scheduledTasks.list(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/scheduled-tasks \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Get a scheduled task `GET /api/public/v1/scheduled-tasks/{id}` SDK: `prosaic.scheduledTasks.retrieve(id)` Returns a single Prosaic AI scheduled task, including how its last run went. ### Path parameters - `id` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `prompt` (string, required) - `entityId` (string, nullable, required) - `cron` (string, required) - `schedule` (string, required) - `timezone` (string, required) - `isEnabled` (boolean, required) - `autoApproveWrites` (boolean, required) - `emailTo` (string, nullable, required) - `lastRunAt` (string, date-time, nullable, required) - `lastStatus` (string, nullable, required) - `lastError` (string, nullable, required) - `runCount` (number, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - `403`: Insufficient role - `404`: Task not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.scheduledTasks.retrieve(id); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Create a scheduled task `POST /api/public/v1/scheduled-tasks` SDK: `prosaic.scheduledTasks.create(params)` Creates a Prosaic AI scheduled task. The task runs its prompt unattended on the given cadence, in Pacific/Auckland time. `emailTo` must be the address of a member of the same workspace — a task is a standing instruction to send a workspace's books somewhere, so arbitrary recipients are refused with 400. ### Request body Content type: `application/json` - `name` (string, required) - `prompt` (string, required) - `schedule` (object, required) - `cadence` (string, required): One of: `daily`, `weekdays`, `weekly`, `monthly`. - `hour` (number, required) - `minute` (number, required) - `weekday` (number) - `dayOfMonth` (number) - `entityId` (string, nullable) - `isEnabled` (boolean) - `autoApproveWrites` (boolean) - `emailTo` (string, nullable) ### Responses - `201`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `prompt` (string, required) - `entityId` (string, nullable, required) - `cron` (string, required) - `schedule` (string, required) - `timezone` (string, required) - `isEnabled` (boolean, required) - `autoApproveWrites` (boolean, required) - `emailTo` (string, nullable, required) - `lastRunAt` (string, date-time, nullable, required) - `lastStatus` (string, nullable, required) - `lastError` (string, nullable, required) - `runCount` (number, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `400`: Validation failed, or the email recipient is not a workspace member - `401`: Unauthorized - `403`: Entity is outside the caller's access - `404`: Workspace not found - `409`: Workspace is at its scheduled-task limit - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.scheduledTasks.create({ name: 'Example Ltd', prompt: 'string', schedule: { cadence: 'daily', hour: 1, minute: 1, }, }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/scheduled-tasks \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "prompt": "string", "schedule": { "cadence": "daily", "hour": 1, "minute": 1 } }' ``` ## Update a scheduled task `PATCH /api/public/v1/scheduled-tasks/{id}` SDK: `prosaic.scheduledTasks.update(id, params)` Updates a Prosaic AI scheduled task. Every field is optional; omitted fields are left as they are. Supplying `schedule` replaces the cadence, and `isEnabled` is how a task is paused or resumed. ### Path parameters - `id` (string, required) ### Request body Content type: `application/json` - `name` (string) - `prompt` (string) - `entityId` (string, nullable) - `schedule` (object) - `cadence` (string, required): One of: `daily`, `weekdays`, `weekly`, `monthly`. - `hour` (number, required) - `minute` (number, required) - `weekday` (number) - `dayOfMonth` (number) - `isEnabled` (boolean) - `autoApproveWrites` (boolean) - `emailTo` (string, nullable) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `name` (string, required) - `prompt` (string, required) - `entityId` (string, nullable, required) - `cron` (string, required) - `schedule` (string, required) - `timezone` (string, required) - `isEnabled` (boolean, required) - `autoApproveWrites` (boolean, required) - `emailTo` (string, nullable, required) - `lastRunAt` (string, date-time, nullable, required) - `lastStatus` (string, nullable, required) - `lastError` (string, nullable, required) - `runCount` (number, required) - `createdAt` (string, date-time, required) - `updatedAt` (string, date-time, required) - `meta` (object) - `count` (number, required) - `400`: Validation failed, or the email recipient is not a workspace member - `401`: Unauthorized - `403`: Entity is outside the caller's access - `404`: Task not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.scheduledTasks.update(id, { name: 'Example Ltd', prompt: 'string', entityId: 'ENTITY_ID', schedule: { cadence: 'daily', hour: 1, minute: 1, }, isEnabled: true, autoApproveWrites: true, emailTo: 'accounts@example.com', }); ``` ### Example (curl) ```bash curl -X PATCH https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example Ltd", "prompt": "string", "entityId": "ENTITY_ID", "schedule": { "cadence": "daily", "hour": 1, "minute": 1 }, "isEnabled": true, "autoApproveWrites": true, "emailTo": "accounts@example.com" }' ``` ## Run a scheduled task now `POST /api/public/v1/scheduled-tasks/{id}/run` SDK: `prosaic.scheduledTasks.run(id)` Queues one immediate run of the task without touching its schedule. The run is enqueued rather than executed inline, so a 202 means "accepted", not "finished" — poll the task and read `lastRunAt` / `lastStatus` to see how it went. Note the run executes with the task's own settings, which includes writing to the books unattended when `autoApproveWrites` is true. ### Path parameters - `id` (string, required) ### Responses - `202`: Successful response - `data` (object, required) - `id` (string, required) - `queued` (boolean, required) - `meta` (object) - `count` (number, required) - `400`: Invalid task ID - `401`: Unauthorized - `403`: Insufficient role - `404`: Task not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.scheduledTasks.run(id); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID/run \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` ## Delete a scheduled task `DELETE /api/public/v1/scheduled-tasks/{id}` SDK: `prosaic.scheduledTasks.del(id)` Soft-deletes a Prosaic AI scheduled task and unregisters its schedule. The chat sessions its past runs produced are kept — they are the record of what was spent and what was changed. ### Path parameters - `id` (string, required) ### Responses - `200`: Successful response - `data` (object, required) - `id` (string, required) - `deleted` (boolean, required) - `meta` (object) - `count` (number, required) - `401`: Unauthorized - `403`: Insufficient role - `404`: Task not found - `500`: Internal server error ### Example (Node SDK) ```ts const { data } = await prosaic.scheduledTasks.del(id); ``` ### Example (curl) ```bash curl -X DELETE https://app.prosaic.works/api/public/v1/scheduled-tasks/$ID \ -H "Authorization: Bearer $PROSAIC_API_KEY" ``` --- # Extensions > Outbound requests made through an extension's connections, with the credential attached server-side. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## Make an outbound request through an extension connection `POST /api/public/v1/extensions/{extensionId}/http` SDK: `prosaic.extensions.request(extensionId, params)` Performs one guarded HTTP request to a third party on behalf of an extension. The credential for the named connection is attached server-side — the caller never supplies or receives it. Requires a token minted for the extension named in the path. API keys and ordinary user tokens are rejected. Requires an extension-scoped token whose ext_id matches extensionId. Ordinary API keys and user OAuth tokens cannot call this endpoint. The embedded status/ok describe the upstream response, which can fail inside HTTP 200. ### Path parameters - `extensionId` (string, required) ### Request body Content type: `application/json` - `connection` (string, required) - `path` (string, required) - `method` (string) - `headers` (object) - `body` (any) - `timeoutMs` (number) - `entityId` (string) ### Responses - `200`: Successful response - `status` (number, required) - `ok` (boolean, required) - `headers` (object, required) - `body` (any, required) - `403`: The token is not for this extension, or the host is not allowed - `409`: The connection is not connected ### Example (Node SDK) ```ts const result = await prosaic.extensions.request(extensionId, { connection: 'string', path: 'string', }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/extensions/$EXTENSION_ID/http \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection": "string", "path": "string" }' ``` --- # Change sets > Proposed journals and reconciliations that an admin approves before they reach the ledger. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## Submit a change-set (proposed financial writes) for an entity `POST /api/public/v1/entities/{entityId}/change-sets` SDK: `prosaic.changeSets.create(entityId, params)` Records an agent-proposed set of write operations (`journal.post` and/or `reconcile`) as a PENDING change-set. Idempotent on the content hash — re-submitting identical content returns the existing change-set. The set is NOT committed here; an admin approves it (L1) before it hits the ledger. The read-only box token is permitted on this single write path and remains pinned to its entity. ### Path parameters - `entityId` (string, required) ### Request body Content type: `application/json` - `operations` (array of objects, required) - `sessionId` (string) - `agentSessionId` (string) ### Responses - `201`: Successful response - `success` (boolean, required): One of: `true`. - `data` (object, required) - `id` (string, required) - `status` (string, required) - `contentHash` (string, required) - `400`: Invalid body - `401`: Unauthorized - `403`: TOKEN_READ_ONLY / TOKEN_ENTITY_MISMATCH / ENTITY_ACCESS_DENIED - `404`: Entity has no workspace - `422`: CHANGE_SET_INVALID — an operation failed validation (e.g. amounts do not sum - `500`: Failed to record the change-set ### Example (Node SDK) ```ts const { data } = await prosaic.changeSets.create(entityId, { operations: [ { type: 'journal.post', payload: { narration: 'Office supplies', date: '2026-04-01', lines: [ {}, ], }, }, ], }); ``` ### Example (curl) ```bash curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/change-sets \ -H "Authorization: Bearer $PROSAIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "operations": [ { "type": "journal.post", "payload": { "narration": "Office supplies", "date": "2026-04-01", "lines": [ {} ] } } ] }' ``` --- # Version > The API version. Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer `. ## API version information `GET /api/public/v1` SDK: `prosaic.version.retrieve()` Returns information about the Prosaic Public API v1 ### Responses - `200`: Successful response - `version` (string, required) - `name` (string, required) - `status` (string, required) ### Example (Node SDK) ```ts const result = await prosaic.version.retrieve(); ``` ### Example (curl) ```bash curl https://app.prosaic.works/api/public/v1 \ -H "Authorization: Bearer $PROSAIC_API_KEY" ```