Preview bulk transaction upload

POST /api/v1/transactions/bulk-upload/preview

Preview and validate a CSV/Excel file before uploading transactions.

This endpoint allows you to:

Validate the file format and structure
See how many transactions will be uploaded
Preview sample transactions
Check for duplicate transactions (optional)
Apply date range filtering

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

Operation ID: preview_bulk_transaction_upload_api_v1_transactions_bulk_upload_preview_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: BulkTransactionUploadPreviewRequest

s3_key string required: S3 key of the CSV file containing transactions
start_date string · date: Optional: Only preview transactions on or after this date (YYYY-MM-DD).
end_date string · date: Optional: Only preview transactions on or before this date (YYYY-MM-DD).
check_duplicates boolean: If true, checks for duplicate transactions against existing database records.
ledger_id string: Optional: Ledger ID to check duplicates against. If not provided, checks all ledgers for the business.
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: BulkTransactionUploadPreviewResponse

success boolean required: Whether the file was successfully parsed
total_rows integer required: Total number of rows in the file (including headers)
valid_transactions integer required: Number of valid transactions found
invalid_rows integer required: Number of rows that failed validation
filtered_by_date integer required: Number of transactions filtered out by date range
duplicates_found integer required: Number of duplicate transactions found (if check_duplicates was true)
transactions_to_upload integer required: Number of transactions that would be uploaded
sample_transactions array · object required: Sample of first 10 valid transactions (for preview)
errors array · string: List of validation errors encountered
warnings array · string: List of warnings (e.g., skipped rows)
duplicate_transactions array · object: List of duplicate transactions found (if check_duplicates was true)

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/preview

bash

curl -X POST 'https://api.ondayzero.com/api/v1/transactions/bulk-upload/preview' \
  -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/preview', {
  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/preview", headers=headers, json=payload)
data = response.json()