What you can do
Worthic’s REST API and MCP tools allow authorized integrations to:
- Retrieve transactions.
- Create new transactions.
- Submit transactions as proposals for review.
- Edit eligible pending or confirmed transactions.
- Confirm reviewed transactions.
- Manage supported split details and financing relationships.
REST provides HTTP endpoints for applications and integrations. MCP exposes named tools that a connected assistant can call.
Both interfaces enforce the client’s workspace and reporting-line permissions. Document upload, extraction, and document-review operations are separate functions.
Operations and permissions
REST paths below are relative to /api/v1.
| Action | REST operation | MCP tool | Required capability |
|---|---|---|---|
| Retrieve transactions | GET /transactions | search_transactions | read:transactions |
| Create a transaction | POST /transactions | submit_transaction | write:transactions |
| Propose a transaction | POST /transaction-proposals | propose_transaction | propose:transactions |
| Read the transaction editor | GET /transactions/{transactionId}/editor | get_transaction_editor | read:transactions |
| Edit a transaction | PATCH /transactions/{transactionId}/editor | edit_transaction | write:transactions |
| Confirm a transaction | POST /transactions/{transactionId}/confirm | confirm_transaction | confirm:transactions |
Capabilities and access scope work together. Permission to write transactions does not grant access to every account or reporting line.
Use the account and reporting-line listing operations to obtain valid identifiers within the client’s scope. These require their corresponding read permissions.
Creating a transaction
Use submit_transaction or POST /api/v1/transactions when an integration has transaction information ready to record.
The creation request includes:
| Field | Purpose |
|---|---|
| accountId | The destination account, which must support transaction logging. |
| reportingLineId | The reporting line assigned to the transaction; required when the account has more than one visible reporting line. |
| bookedAt | The transaction date in YYYY-MM-DD format. |
| description | A description of the movement. |
| amount | A positive numeric amount. |
| direction | Inflow for money in or outflow for money out. |
| currency | The transaction currency, where supplied. |
| category, notes, tags | Optional categorization and supporting information. |
| externalTransactionId | A stable identifier from the originating system, used to help recognize the same transaction on later submissions. |
Use a positive amount and specify its direction separately. For example, a payment of 125 is represented by amount: 125 and direction: "outflow".
Creation example
For REST, send this body to POST /api/v1/transactions. For MCP, pass the same transaction arguments to submit_transaction.
{
"accountId": "<account ID>",
"reportingLineId": "<reporting-line ID>",
"bookedAt": "2026-10-06",
"description": "Office internet — October",
"amount": 125,
"direction": "outflow",
"currency": "USD",
"notes": "Monthly service payment",
"tags": ["Internet"],
"externalTransactionId": "supplier-payment-2026-1042"
}
Replace the example identifiers and currency with values appropriate to the account.
A newly created transaction starts as pending confirmation. Creating it does not automatically confirm it, even if the client also has confirmation permission.
Submitting a proposal
Use propose_transaction or POST /api/v1/transaction-proposals when the integration’s role is to propose transactions for human review.
Proposals use the same basic transaction fields as submissions but require propose:transactions rather than write:transactions. Worthic identifies them as API proposals.
A proposal is not an off-ledger draft. Both newly submitted transactions and newly proposed transactions are pending ledger records and can affect balances, net worth, and other reporting before confirmation.
Choose the proposal operation to distinguish the integration’s review-oriented role—not to postpone the transaction’s financial effect.
Avoiding duplicate submissions
Supply a stable externalTransactionId when the source system provides one. Keep that identifier unchanged when referring to the same movement.
Worthic checks incoming transactions against existing transaction identities. A recognized submission can return an existing transaction instead of creating another one.
Do not use repeated creation requests to update an existing transaction. Retrieve its editor and use the editing operation.
Idempotency keys provide additional protection when retrying the same request after a timeout or uncertain response:
- REST: Use the Idempotency-Key header.
- MCP: Use the idempotencyKey argument.
Reuse the key for an identical retry. Use a new key for a different operation or revised request.
An external transaction identifier identifies the source movement; an idempotency key identifies a particular request.
Reading an existing transaction’s editor
Before editing, retrieve the current editor:
- REST: GET /api/v1/transactions/{transactionId}/editor
- MCP: get_transaction_editor
The response includes:
- Current transaction details and field values.
- Available category trees and reporting lines.
- Supported editable field names and split-field prefixes.
- Relevant linked information.
- An expectedVersion value.
Use the returned identifiers and field names rather than guessing them.
Editing a transaction
Editing uses the same validation and save workflow as Worthic’s transaction editor.
Depending on the record, supported edits include descriptions, notes, tags, reporting lines, categories, amounts, directions, currencies, cashflow dates, accrual values, and applicable specialized details.
The creation and editing request formats differ. An edit supplies a fields array, with each entry containing a field name and an array of string values.
- Omitted fields retain their existing values.
- Supplied fields replace their current values.
- An empty array requests that a field be cleared, where permitted.
- Required fields remain subject to validation.
REST editing example
After retrieving the editor, send:
PATCH /api/v1/transactions/{transactionId}/editor
With:
{
"expectedVersion": "<version returned by the editor>",
"fields": [
{
"name": "description",
"values": ["Office internet — October service"]
}
]
}
MCP editing example
Call edit_transaction with:
{
"transactionId": "<transaction ID>",
"expectedVersion": "<version returned by the editor>",
"fields": [
{
"name": "description",
"values": ["Office internet — October service"]
}
]
}
These examples change only the description.
For specialized fields containing structured values, follow the editor response and API specification.
Protected information and access restrictions
The transaction’s account identity and source identifiers are not caller-writable through the editor.
Imported Ledger dates are read-only. Use cashflowDate when adjusting the reporting date of an imported transaction.
Category assignments must match the applicable account and reporting-line context. Supporting documents and linked records must also be within the client’s permitted scope.
Accounts that use balance events instead of transaction logging are not managed through these transaction operations.
Version conflicts
Send the expectedVersion returned by the most recent editor read. Treat it as an opaque value rather than calculating or changing it.
If the transaction or relevant linked information changes before the edit is saved, Worthic rejects the stale request. REST returns 409 Conflict, with stale_transaction_edit for a stale transaction editor.
To recover:
1. Retrieve the editor again.
2. Review what changed.
3. Reapply only the changes that are still appropriate.
4. Submit using the new version.
Do not replace the version and resend an old edit without checking the latest record.
Version checking prevents stale updates. Idempotency handles retries; it does not replace the version check.
Confirmation is a separate action
Editing preserves confirmation status:
- Pending transactions remain pending.
- Confirmed transactions remain confirmed.
After reviewing a pending transaction, an authorized client can call confirm_transaction or:
POST /api/v1/transactions/{transactionId}/confirm
This requires confirm:transactions.
Confirmation records that the transaction has been reviewed. It does not mark the point when a pending ledger transaction first starts affecting balances.
Split transactions and specialized details
The editor supports applicable split, investment, payslip, rental, financing, and property-register fields.
For splits, use the component identifiers and field prefixes returned by the editor. Required assignments and signed totals must satisfy the same rules as edits made in Worthic.
If some split components are outside the client’s scope, changes are restricted. Access to one component does not permit unrestricted changes to the entire group.
For advanced details not exposed by the basic creation request, create the transaction first, retrieve its editor, and use the supported editing fields.
Mortgage and loan relationships
Financing operations can inspect and link corresponding bank and liability transactions.
Dedicated MCP tools include:
- get_financing_details
- list_financing_matches
- link_financing_transactions
- unlink_financing_transactions
Corresponding REST operations are available in the API specification.
Changing financing relationships requires reconcile:financing. Editing financing fields through the transaction editor also requires the editor’s write permission.
Review the matching records and use the current version required by the financing operation. Linking aligns the selected reporting line, payment categories, and cashflow date without confirming either transaction.
Removing a link does not automatically change the retained reporting-source selection. Review that selection afterward.
Checking results and errors
Store the returned transaction ID after creation and inspect the saved values after editing. A successful edit returns refreshed editor information for subsequent operations.
| Response | What to check |
|---|---|
| 400 | Missing or invalid values, unsupported fields, or inconsistent transaction details. |
| 403 | Required capabilities and permitted account, reporting-line, or linked-record access. |
| 404 | Whether the transaction exists and is accessible to the client. |
| 409 | The specific conflict code: the editor may be stale, a financing match may have changed, or an incoming transaction may have been permanently discarded. |
Consult the REST API specification for exact schemas and operation-specific requirements.