All API resources
API reference

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

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

  • entityIdstringrequired

Query parameters

  • pageinteger

    Page number (starts at 1)

    Default: 1

  • pageSizeinteger

    Number of items per page

    Default: 20

  • dateFromstring (date)

    Start date for filtering transactions (ISO 8601 format)

  • dateTostring (date)

    End date for filtering transactions (ISO 8601 format)

  • includePreConversionstring

    Include transactions dated before the entity's conversion date (default false)

    One of: true, false

  • journalIdstring (uuid)

    Filter by journal ID to get transactions reconciled to a specific journal

  • reconciliationStatusstring

    Filter by reconciliation status

    One of: reconciled, unreconciled

  • viewstring

    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

  • dataarray of objectsrequired
  • paginationobjectrequired
    Show 6 child attributes
    • currentPagenumberrequired
    • pageSizenumberrequired
    • totalCountnumberrequired
    • totalPagesnumberrequired
    • hasNextPagebooleanrequired
    • hasPreviousPagebooleanrequired
  • 400 Bad request - missing or invalid parameters
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - No access to the specified entity
Node SDK
const page = await prosaic.transactions.list(entityId);
curl
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

application/json

  • updatesarray of objectsrequired
    Show 13 child attributes
    • idstringrequired
    • invoiceIdstring
    • invoiceAllocationsarray of objects
      Show 2 child attributes
      • invoiceIdstringrequired
      • amountnumberrequired
    • billAllocationsarray of objects
      Show 2 child attributes
      • billIdstringrequired
      • amountnumberrequired
    • refundCreditobject
      Show 1 child attribute
      • contactIdstringrequired
    • creditHoldingobject
      Show 2 child attributes
      • accountCodestringrequired
      • taxCodestringrequired
    • fixedAssetDisposalobject
      Show 4 child attributes
      • fixedAssetIdstringrequired
      • reverseLaterDepreciationboolean
      • saleTaxCodestring
      • accountCodesobject
        Show 6 child attributes
        • lossstring
        • gainstring
        • private_lossstring
        • private_gainstring
        • depreciation_recoverystring
        • capital_gainstring
    • fixedAssetPurchaseobject
      Show 9 child attributes
      • namestringrequired
      • entityFixedAssetTypeIdstringrequired
      • startDatestringrequired
      • depreciationMethodstringrequired
      • assetNumberstring
      • businessUsePercentagenumber
      • taxCodestring
      • depreciationRatenumber
      • usefulLifeYearsnumber
    • narrationstring
    • taxModestring

      One of: NO_TAX, TAX_INCLUSIVE, TAX_EXCLUSIVE

    • fileIdsarray of strings
    • destinationEntityIdstring
    • assignmentarray of objects
      Show 8 child attributes
      • codestringrequired
      • namestringrequired
      • taxCodestringrequired
      • creditnumber
      • debitnumber
      • descriptionstring
      • destinationEntityIdstring
      • dimensionOptionIdsarray of strings

Responses

200 Successful response

  • successbooleanrequired

    One of: true

  • dataobjectrequired
    Show 4 child attributes
    • requestIdstringrequired
    • transactionIdsarray of stringsrequired
    • statusstringrequired
    • entityJobsarray of objectsrequired
      Show 3 child attributes
      • entityIdstringrequired
      • jobIdstringrequired
      • transactionCountnumberrequired
  • messagestringrequired
  • 400 Bad request - validation error
  • 401 Unauthorized - Invalid or missing API key
  • 404 Transaction(s) not found, already reconciled, or access denied
  • 409 Conflict - transactions already being processed
  • 500 Internal server error
Node SDK
const { data } = await prosaic.transactions.reconcileBulk({
  updates: [
    {
      id: 'ID',
    },
  ],
});
curl
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

  • entityIdstringrequired
  • transactionIdstringrequired

Request body

application/json

  • assignmentarray of objectsrequired
    Show 7 child attributes
    • codestringrequired
    • namestringrequired
    • taxCodestringrequired
    • creditnumber
    • debitnumber
    • descriptionstring
    • dimensionOptionIdsarray of strings
  • narrationstring
  • taxModestring

    One of: NO_TAX, TAX_INCLUSIVE, TAX_EXCLUSIVE

  • fileIdsarray of strings

Responses

200 Successful response

  • successbooleanrequired

    One of: true

  • dataobjectrequired
    Show 3 child attributes
    • transactionIdstringrequired
    • journalIdstringrequired
    • logicalJournalIdstringrequired
  • 400 Bad request - validation error or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION).
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - No access to the specified entity
  • 404 Transaction not found or already reconciled
  • 500 Internal server error
Node SDK
const { data } = await prosaic.transactions.reconcile(entityId, transactionId, {
  assignment: [
    {
      code: '200',
      name: 'Example Ltd',
      taxCode: 'TAX_CODE',
    },
  ],
});
curl
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

  • entityIdstringrequired
  • transactionIdstringrequired

Request body

application/json

  • reverseReasonstring

Responses

200 Successful response

  • successbooleanrequired

    One of: true

  • dataobjectrequired
    Show 5 child attributes
    • transactionIdstringrequired
    • logicalJournalIdstringrequired
    • reversalJournalIdstringrequired
    • reversedAtstring (date-time)required
    • reverseReasonstringrequired
  • 400 Bad request - validation error or transaction cannot be reversed
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - No access to the specified entity
  • 404 Transaction not found or access denied
  • 409 The receipt can't be unmatched because some of its credit was refunded (`PAYMENT_REFUNDED`). Unmatch the refund first.
  • 500 Internal server error
Node SDK
const { data } = await prosaic.transactions.reverse(entityId, transactionId, {
  reverseReason: 'string',
});
curl
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"
  }'