Bulk upload transactions to new source account

POST /api/v1/transactions/bulk-upload

Upload historical transactions from a CSV/Excel file to a new source account.

Workflow (via Temporal for durability):

Local engine:

Gets/creates ledger
Reads transactions from the CSV/Excel file in S3
Creates Transaction + Journal Entry rows with categorization
Runs AI categorization pass for uncategorized transactions

Teal engine:

Gets/creates ledger and personal source account in Teal
Reads transactions from the CSV/Excel file in S3
Posts transactions to Teal source account
Imports journal entries created by Teal

Supported File Formats: .csv, .xlsx, .xls

CSV/Excel Columns (flexible naming):

date/datetime/transaction_date: Transaction date (YYYY-MM-DD or ISO format)
amount/transaction_amount/value: Amount in dollars (positive or negative)
description/memo/name: Transaction description

Operation ID: bulk_upload_transactions_api_v1_transactions_bulk_upload_post · View as markdown · OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: BulkTransactionUploadRequest

ledger_id string: Optional: UUID of existing ledger to use. If provided, ledger creation is skipped and ledger_name/ledger fields are ignored.
ledger_name string: Display name for the new ledger (required if ledger_id not provided, e.g., 'My Old Credit Card XXXX')
source_account_name string: Optional: Display name for the source account. Defaults to ledger name if not provided.
business_personal string: Whether the source account is a business or personal account. 'business' (default) for company transactions, 'personal' for owner draws/contributions.
invert_transaction_amounts boolean: If true, transaction amounts are inverted during import. Useful when CSV has opposite sign convention.
s3_key string required: S3 key of the CSV file containing transactions
start_date string · date: Optional: Only upload transactions on or after this date (YYYY-MM-DD). Filters transactions before upload.
end_date string · date: Optional: Only upload transactions on or before this date (YYYY-MM-DD). Filters transactions before upload.
check_duplicates boolean: If true, checks for duplicate transactions before uploading. Duplicates are skipped.
duplicate_match_fields array · string: Fields to use for duplicate detection: 'amount', 'date', 'description'. Defaults to all three.
currency string: Currency for this account (USD, CAD, AUD, EUR, or GBP). Defaults to business default.
editable boolean: If true, journal entries can be manually posted to this account.
type string: Account type: asset, liability, equity, revenue, expense. Required in Custom Mode.
description string: Optional description of the account's purpose.
status string: Account status: 'active' or 'inactive'. Inactive accounts hidden from dropdowns.
debit_credit string: Normal balance: 'debit' (assets/expenses) or 'credit' (liabilities/equity/revenue). Required in Custom Mode.
sort_code string: Sort code for chart ordering (e.g., '1000' for assets, '4000' for revenue). Required in Custom Mode.
sub_type string: Sub-classification (current_assets, operating_expenses, etc.). Required in Custom Mode.
report_cash_flow boolean: Include in cash flow statement. Required in Custom Mode.
financial_account_type string: Templated Mode: bank_account, credit_card, payments, payroll, loan, prepaid_card, accounts_receivable, accounts_payable.
parent_id string: UUID of parent ledger for sub-accounts (e.g., 'Operating Expenses' → 'Office Supplies').
column_mapping object: User-supplied mapping from DayZero field names to CSV column names. Keys: 'date', 'amount', 'description'. Values: the CSV header to use. When provided, auto-detection is skipped.

Responses

201 Successful Response

Schema: BulkTransactionUploadResponse

workflow_id string required: Temporal workflow ID for tracking progress
business_id string required: Business ID the upload is for
ledger_name string required: Name of the ledger being created
status string required: Workflow status (typically 'started' initially)
executor string required: Execution backend (typically 'temporal')

400 Bad Request - Invalid input

401 Unauthorized - Authentication required

403 Forbidden - Insufficient permissions

422 Validation Error

Schema: HTTPValidationError

detail array · ValidationError ValidationError

5 fields

loc array · string | integer required
msg string required
type string required
input object
ctx object

Code samples

POST /api/v1/transactions/bulk-upload

bash

curl -X POST 'https://api.ondayzero.com/api/v1/transactions/bulk-upload' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "s3_key": "string"
}'

javascript

const response = await fetch('https://api.ondayzero.com/api/v1/transactions/bulk-upload', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "s3_key": "string"
}),
});
const data = await response.json();

python

import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {
  "s3_key": "string"
}

response = httpx.post("https://api.ondayzero.com/api/v1/transactions/bulk-upload", headers=headers, json=payload)
data = response.json()