{"openapi":"3.1.0","info":{"title":"GET /api/v1/credit/import-batches/{staging_id}/report","version":"1.0.0","description":"The import report of a loan file's last run"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/import-batches/{staging_id}/report":{"get":{"tags":["credit"],"summary":"The import report of a loan file's last run","description":"File identity (name, SHA-256), the mapping used, and per line the file's count, principal and outstanding against the book's, with every mismatch and rejected row, and who ran it when. `format=csv` and `format=pdf` return it as a document. Operator action: an API token receives `403`.","operationId":"credit_import_get_report","parameters":[{"name":"staging_id","in":"path","required":true,"schema":{"type":"string","title":"Staging Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv","pdf"],"type":"string","description":"json (the default): the report as data. csv, pdf: as a document.","default":"json","title":"Format"},"description":"json (the default): the report as data. csv, pdf: as a document."},{"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"}}],"responses":{"200":{"description":"The import report: the JSON envelope, or with `format` the spreadsheet (`text/csv`) or the document (`application/pdf`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ImportReportResponse_"}},"text/csv":{"schema":{"type":"string"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"credit_import_get_report_api_v1_credit_import_batches__staging_id__report_get"}}},"components":{"schemas":{"ImportExpectedTotals":{"properties":{"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count","description":"Expected row count."},"principal_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Principal Cents","description":"Expected principal."},"outstanding_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Outstanding Cents","description":"Expected outstanding."}},"type":"object","title":"ImportExpectedTotals","description":"The control totals the operator gave from the partner's book."},"ImportReportLine":{"properties":{"line_key":{"type":"string","title":"Line Key","description":"The line key."},"credit_line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Line Id","description":"The line."},"created":{"type":"boolean","title":"Created","description":"The import opened the line.","default":false},"file_count":{"type":"integer","title":"File Count","description":"Rows in the file for this line."},"file_principal_cents":{"type":"integer","title":"File Principal Cents","description":"Principal the file states."},"file_outstanding_cents":{"type":"integer","title":"File Outstanding Cents","description":"Outstanding the file states."},"book_count":{"type":"integer","title":"Book Count","description":"Loans on the line carrying the file's ids."},"book_principal_cents":{"type":"integer","title":"Book Principal Cents","description":"Their principal on the book."},"book_outstanding_cents":{"type":"integer","title":"Book Outstanding Cents","description":"Their outstanding on the book."},"imported":{"type":"integer","title":"Imported","description":"New loans.","default":0},"duplicates":{"type":"integer","title":"Duplicates","description":"Already on the line.","default":0},"rejected":{"type":"integer","title":"Rejected","description":"Did not load.","default":0},"ties":{"type":"boolean","title":"Ties","description":"File and book agree on count and money."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the line did not load."}},"type":"object","required":["line_key","file_count","file_principal_cents","file_outstanding_cents","book_count","book_principal_cents","book_outstanding_cents","ties"],"title":"ImportReportLine","description":"One line: what the file says against what the book holds."},"ImportReportResponse":{"properties":{"report_id":{"type":"string","title":"Report Id","description":"The batch id."},"program_id":{"type":"string","title":"Program Id","description":"The program."},"program_name":{"type":"string","title":"Program Name","description":"The program's display name."},"filename":{"type":"string","title":"Filename","description":"The file's name as uploaded."},"sha256":{"type":"string","title":"Sha256","description":"SHA-256 of the file."},"row_count":{"type":"integer","title":"Row Count","description":"Rows in the file."},"mapping":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Mapping","description":"Target field → source column used."},"amounts_in":{"type":"string","enum":["dollars","cents"],"title":"Amounts In","description":"The unit the money was read in."},"dry_run":{"type":"boolean","title":"Dry Run","description":"The run was a dry run."},"applied":{"type":"boolean","title":"Applied","description":"The run wrote to the book."},"as_of":{"type":"string","format":"date","title":"As Of","description":"Loan status was assessed as at this date."},"staged_at":{"type":"string","format":"date-time","title":"Staged At","description":"When the file was staged."},"staged_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Staged By","description":"Who staged it."},"run_at":{"type":"string","format":"date-time","title":"Run At","description":"When the run happened."},"run_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run By","description":"Who ran it."},"expected":{"$ref":"#/components/schemas/ImportExpectedTotals","description":"The control totals the run was given."},"file_totals":{"$ref":"#/components/schemas/ImportTotals","description":"What the file states, every row."},"loaded_totals":{"$ref":"#/components/schemas/ImportTotals","description":"What loaded: the figures the control totals are checked against."},"book_totals":{"$ref":"#/components/schemas/ImportTotals","description":"What the book holds for the file's loans."},"lines":{"items":{"$ref":"#/components/schemas/ImportReportLine"},"type":"array","title":"Lines","description":"Per line: what the file says against what the book holds."},"mismatches":{"items":{"type":"string"},"type":"array","title":"Mismatches","description":"Everything that did not tie: control totals first, then lines. After an apply the control totals refused, a last entry says nothing was written and what to do."},"ties":{"type":"boolean","title":"Ties","description":"No mismatches at all."},"rejections":{"items":{"$ref":"#/components/schemas/ImportRowRejection"},"type":"array","title":"Rejections","description":"Every rejected row, in file order (`rejection_count` is its length)."},"rejection_count":{"type":"integer","title":"Rejection Count","description":"Every rejected row.","default":0},"warnings":{"items":{"$ref":"#/components/schemas/ImportWarning"},"type":"array","title":"Warnings","description":"Every warning of the run: run-level first, then rows."}},"type":"object","required":["report_id","program_id","program_name","filename","sha256","row_count","amounts_in","dry_run","applied","as_of","staged_at","run_at","ties"],"title":"ImportReportResponse","description":"The import report: the file against the book, per line, and who ran it.\n\nBook figures are as the book stood at the end of the run: on a dry run,\nas it would have stood; on an apply, as it was written (they tie to the\nloan tape for the same loans until the next payment or accrual moves\nthem)."},"ImportRowRejection":{"properties":{"row_number":{"type":"integer","title":"Row Number","description":"Position in the file, from 1."},"line_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line Key","description":"The row's line key."},"external_settlement_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Settlement Id","description":"The row's issuer transaction id, when it has one."},"reason":{"type":"string","title":"Reason","description":"Why it was rejected."}},"type":"object","required":["row_number","reason"],"title":"ImportRowRejection","description":"A row that did not load, and why."},"ImportTotals":{"properties":{"count":{"type":"integer","title":"Count","description":"Rows that loaded: new plus duplicates.","default":0},"principal_cents":{"type":"integer","title":"Principal Cents","description":"Original principal.","default":0},"outstanding_cents":{"type":"integer","title":"Outstanding Cents","description":"Outstanding.","default":0}},"type":"object","title":"ImportTotals","description":"Counts and money over the rows that loaded (or would)."},"ImportWarning":{"properties":{"code":{"type":"string","title":"Code","description":"`no_interest_ceiling`: the program has no ceiling on a loan's interest, and the ceiling is frozen onto each loan when it is created, so these loans stay uncapped for good. `repeats_id_on_other_line`: the row loaded although its transaction id is already on another line."},"message":{"type":"string","title":"Message","description":"What it means and what to do, in words."},"row_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Number","description":"Position in the file, from 1; null for the run."},"line_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line Key","description":"The row's line key."},"external_settlement_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Settlement Id","description":"The row's issuer transaction id."}},"type":"object","required":["code","message"],"title":"ImportWarning","description":"Something the operator should read before applying; the run did not stop."},"SuccessEnvelope_ImportReportResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/ImportReportResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ImportReportResponse]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}