All API resources
Transactions
Bank transactions: list them, reconcile them one at a time or in bulk, and reverse a reconciliation.
Base URL https://app.prosaic.works/api/public/v1. Every request needs an API key or access token; see the overview.
List bank transactions
/api/public/v1/entities/{entityId}/transactionsSDK: 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
entityIdstringrequired
Query parameters
pageintegerPage number (starts at 1)
Default:
1pageSizeintegerNumber of items per page
Default:
20dateFromstring (date)Start date for filtering transactions (ISO 8601 format)
dateTostring (date)End date for filtering transactions (ISO 8601 format)
includePreConversionstringInclude transactions dated before the entity's conversion date (default false)
One of:
true,falsejournalIdstring (uuid)Filter by journal ID to get transactions reconciled to a specific journal
reconciliationStatusstringFilter by reconciliation status
One of:
reconciled,unreconciledviewstringfull(default) returns each transaction with its bank account, linked GL account, user, merchant, category and suggestions in full.compactreturns 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,compactDefault:
"full"
Responses
200 Successful response
dataarray of objectsrequiredpaginationobjectrequiredShow 6 child attributesHide child attributes
currentPagenumberrequiredpageSizenumberrequiredtotalCountnumberrequiredtotalPagesnumberrequiredhasNextPagebooleanrequiredhasPreviousPagebooleanrequired
400Bad request - missing or invalid parameters401Unauthorized - Invalid or missing API key403Forbidden - No access to the specified entity
const page = await prosaic.transactions.list(entityId);curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions \
-H "Authorization: Bearer $PROSAIC_API_KEY"Reconcile bank transactions (bulk or single)
/api/public/v1/transactions/reconcileSDK: 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
requestIdfor 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
taxCodefrom 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
application/json
updatesarray of objectsrequiredShow 13 child attributesHide child attributes
idstringrequiredinvoiceIdstringinvoiceAllocationsarray of objectsShow 2 child attributesHide child attributes
invoiceIdstringrequiredamountnumberrequired
billAllocationsarray of objectsShow 2 child attributesHide child attributes
billIdstringrequiredamountnumberrequired
refundCreditobjectShow 1 child attributeHide child attributes
contactIdstringrequired
creditHoldingobjectShow 2 child attributesHide child attributes
accountCodestringrequiredtaxCodestringrequired
fixedAssetDisposalobjectShow 4 child attributesHide child attributes
fixedAssetIdstringrequiredreverseLaterDepreciationbooleansaleTaxCodestringaccountCodesobjectShow 6 child attributesHide child attributes
lossstringgainstringprivate_lossstringprivate_gainstringdepreciation_recoverystringcapital_gainstring
fixedAssetPurchaseobjectShow 9 child attributesHide child attributes
namestringrequiredentityFixedAssetTypeIdstringrequiredstartDatestringrequireddepreciationMethodstringrequiredassetNumberstringbusinessUsePercentagenumbertaxCodestringdepreciationRatenumberusefulLifeYearsnumber
narrationstringtaxModestringOne of:
NO_TAX,TAX_INCLUSIVE,TAX_EXCLUSIVEfileIdsarray of stringsdestinationEntityIdstringassignmentarray of objectsShow 8 child attributesHide child attributes
codestringrequirednamestringrequiredtaxCodestringrequiredcreditnumberdebitnumberdescriptionstringdestinationEntityIdstringdimensionOptionIdsarray of strings
Responses
200 Successful response
successbooleanrequiredOne of:
truedataobjectrequiredShow 4 child attributesHide child attributes
requestIdstringrequiredtransactionIdsarray of stringsrequiredstatusstringrequiredentityJobsarray of objectsrequiredShow 3 child attributesHide child attributes
entityIdstringrequiredjobIdstringrequiredtransactionCountnumberrequired
messagestringrequired
400Bad request - validation error401Unauthorized - Invalid or missing API key404Transaction(s) not found, already reconciled, or access denied409Conflict - transactions already being processed500Internal server error
const { data } = await prosaic.transactions.reconcileBulk({
updates: [
{
id: 'ID',
},
],
});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
/api/public/v1/entities/{entityId}/transactions/{transactionId}/reconcileSDK: 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 thecodefield (e.g., "2030") in the assignmentcodefield below. - Tax codes: Retrieve the entity's tax rates via
GET /api/public/v1/entities(filter byentityId). ThetaxRates[].codefield (e.g., "GST15", "EXEMPT", "ZERO") is used in the assignmenttaxCodefield below.
Integration Flow
- GET
/entities- Retrieve entity with availabletaxRates[] - GET
/entities/{entityId}/transactions- List unreconciled transactions - POST
/entities/{entityId}/transactions/{transactionId}/reconcile- Reconcile with:- Select appropriate account (from entity's chart of accounts)
- Select tax rate using
taxCodefrom step 1 - Specify
taxModebased on whether your amounts include/exclude tax
- 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
taxCodefrom 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
entityIdstringrequiredtransactionIdstringrequired
Request body
application/json
assignmentarray of objectsrequiredShow 7 child attributesHide child attributes
codestringrequirednamestringrequiredtaxCodestringrequiredcreditnumberdebitnumberdescriptionstringdimensionOptionIdsarray of strings
narrationstringtaxModestringOne of:
NO_TAX,TAX_INCLUSIVE,TAX_EXCLUSIVEfileIdsarray of strings
Responses
200 Successful response
successbooleanrequiredOne of:
truedataobjectrequiredShow 3 child attributesHide child attributes
transactionIdstringrequiredjournalIdstringrequiredlogicalJournalIdstringrequired
400Bad request - validation error or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION).401Unauthorized - Invalid or missing API key403Forbidden - No access to the specified entity404Transaction not found or already reconciled500Internal server error
const { data } = await prosaic.transactions.reconcile(entityId, transactionId, {
assignment: [
{
code: '200',
name: 'Example Ltd',
taxCode: 'TAX_CODE',
},
],
});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
/api/public/v1/entities/{entityId}/transactions/{transactionId}/reverseSDK: 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
- Creates a reversal journal entry that negates the original reconciliation
- Updates the reconciliation status to REVERSED
- Makes the bank transaction available for reconciliation again
- Maintains full audit trail of the reversal
Integration Flow
- GET
/entities/{entityId}/transactions- Find reconciled transactions to reverse - POST
/entities/{entityId}/transactions/{transactionId}/reverse- Reverse the reconciliation - The transaction becomes available for new reconciliation via the reconcile endpoint
Path parameters
entityIdstringrequiredtransactionIdstringrequired
Request body
application/json
reverseReasonstring
Responses
200 Successful response
successbooleanrequiredOne of:
truedataobjectrequiredShow 5 child attributesHide child attributes
transactionIdstringrequiredlogicalJournalIdstringrequiredreversalJournalIdstringrequiredreversedAtstring (date-time)requiredreverseReasonstringrequired
400Bad request - validation error or transaction cannot be reversed401Unauthorized - Invalid or missing API key403Forbidden - No access to the specified entity404Transaction not found or access denied409The receipt can't be unmatched because some of its credit was refunded (`PAYMENT_REFUNDED`). Unmatch the refund first.500Internal server error
const { data } = await prosaic.transactions.reverse(entityId, transactionId, {
reverseReason: 'string',
});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"
}'