{"openapi":"3.1.0","info":{"title":"POST /api/v1/transactions/bulk-upload/preview","version":"1.0.0","description":"Preview bulk transaction upload"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/transactions/bulk-upload/preview":{"post":{"tags":["transactions"],"summary":"Preview bulk transaction upload","description":"Preview and validate a CSV/Excel file before uploading transactions.\n\nThis endpoint allows you to:\n- Validate the file format and structure\n- See how many transactions will be uploaded\n- Preview sample transactions\n- Check for duplicate transactions (optional)\n- Apply date range filtering\n\n**Supported File Formats:** .csv, .xlsx, .xls","operationId":"preview_bulk_transaction_upload_api_v1_transactions_bulk_upload_preview_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTransactionUploadPreviewRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTransactionUploadPreviewResponse"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"detail":"Invalid request parameters"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BulkTransactionUploadPreviewRequest":{"properties":{"s3_key":{"type":"string","minLength":1,"title":"S3 Key","description":"S3 key of the CSV file containing transactions"},"start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date","description":"Optional: Only preview transactions on or after this date (YYYY-MM-DD)."},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date","description":"Optional: Only preview transactions on or before this date (YYYY-MM-DD)."},"check_duplicates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Check Duplicates","description":"If true, checks for duplicate transactions against existing database records.","default":false},"ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ledger Id","description":"Optional: Ledger ID to check duplicates against. If not provided, checks all ledgers for the business."},"column_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Column Mapping","description":"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."}},"type":"object","required":["s3_key"],"title":"BulkTransactionUploadPreviewRequest","description":"Request schema for previewing/validating CSV before upload.\n\nValidates the file structure, parses transactions, applies date filtering,\nand optionally checks for duplicates. Does NOT upload any transactions."},"BulkTransactionUploadPreviewResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the file was successfully parsed"},"total_rows":{"type":"integer","title":"Total Rows","description":"Total number of rows in the file (including headers)"},"valid_transactions":{"type":"integer","title":"Valid Transactions","description":"Number of valid transactions found"},"invalid_rows":{"type":"integer","title":"Invalid Rows","description":"Number of rows that failed validation"},"filtered_by_date":{"type":"integer","title":"Filtered By Date","description":"Number of transactions filtered out by date range"},"duplicates_found":{"type":"integer","title":"Duplicates Found","description":"Number of duplicate transactions found (if check_duplicates was true)"},"transactions_to_upload":{"type":"integer","title":"Transactions To Upload","description":"Number of transactions that would be uploaded"},"sample_transactions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":10,"title":"Sample Transactions","description":"Sample of first 10 valid transactions (for preview)"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"List of validation errors encountered"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"List of warnings (e.g., skipped rows)"},"duplicate_transactions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Duplicate Transactions","description":"List of duplicate transactions found (if check_duplicates was true)"}},"type":"object","required":["success","total_rows","valid_transactions","invalid_rows","filtered_by_date","duplicates_found","transactions_to_upload","sample_transactions"],"title":"BulkTransactionUploadPreviewResponse","description":"Response schema for CSV preview/validation.\n\nContains validation results, statistics, sample transactions, and any errors\nor warnings encountered during parsing. Also includes duplicate detection\nresults if check_duplicates was enabled.","example":{"duplicates_found":5,"errors":[],"filtered_by_date":2,"invalid_rows":3,"sample_transactions":[{"amount":-125.5,"date":"2024-01-15","description":"Office Supplies - Staples"}],"success":true,"total_rows":150,"transactions_to_upload":138,"valid_transactions":145,"warnings":["Row 5: Invalid date format","Row 12: Missing amount"]}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}