Poll GET /api/v1/omni/files/{fileId} with the API token to read a file belonging to your issuer. A file ID has the form fu_<UUID>. Unknown files and files belonging to another issuer return 404. Polling reads persisted state and never starts processing.
GET /api/v1/omni/files returns { "files": [...], "nextCursor": "fu_<UUID>" }. nextCursor is null when no further page is available.
| Query parameter | Meaning |
|---|---|
cursor | nextCursor from the preceding page; omit for the first page. |
pageSize | Default 50, maximum 100. |
content | Optional percents-txn-stream, plaid-txn-stream, omni-txn-stream, or txnStream filter. |
processingMode | Optional automated or manual filter. |
Files are ordered by createdAt descending and then file ID descending. Continue with the returned cursor and the same filters.
| Field | Meaning |
|---|---|
fileId, filename, content | Reservation identity, reconciliation name, and selected format. |
createdAt | Timestamp when the upload URL was reserved. |
uploadExpiresAt | Upload URL expiry timestamp. |
receivedAt | Actual object upload timestamp; null before receipt. |
validatedAt | Validation completion timestamp, or null. |
processingStartedAt | Actual ingestion start, or null when ingestion has not begun. |
processingFinishedAt | Terminal file-handling timestamp, including validation failure and successful sandbox validation; null before completion. It does not imply ingestion occurred. |
fileType | csv or json. |
uploadStatus | awaiting_upload, received, or expired. |
processingMode | automated for native/Plaid; manual for legacy formats. |
validationStatus | pending, passed, failed, or not_applicable. |
processingStatus | not_started, pending, processing, completed, completed_with_errors, failed, or validation_only. |
counts | null before available; otherwise detectedRows, ingestedRows, duplicateRows, and rejectedRows, each a non-negative integer. |
errorMetadata | null or an error object with message and optional missingAccountIds and unknownPercentsMerchantIds. |
errorUuid | Error instance identifier for support, or null. |
detectedRows counts discovered transaction rows. ingestedRows counts persisted transaction facts, including facts that receive a reward/business rejection. duplicateRows counts skipped known duplicates. rejectedRows counts file-validation or technical ingestion failures; reward eligibility rejection does not increment it. These counts do not represent reward approval.
All timestamps use ISO 8601. Raw object-storage metadata is not part of the public response.
completed means file ingestion completed. completed_with_errors means processing completed with reported row errors; inspect counts and error context. failed means validation or processing failed. Successful sandbox validation uses processingStatus=validation_only and validationStatus=passed; failed validation uses processingStatus=failed and validationStatus=failed. not_applicable and manual processing allow reconciliation of legacy files without implying automated ingestion.
A passing validation result does not itself imply ingestion completion. Whole-file validation prevents ingestion when the file is malformed. Subsequent file processing outcomes do not represent final individual transaction, reward, or invoice decisions.
An uploaded file that cannot be read for validation receives a terminal failure with an errorUuid and unknown counts. Other files continue processing. Contact support using that identifier and use a new filename when resubmitting the file.