{"templateId":"markdown","versions":[{"version":"1.0","label":"1.0","link":"/omni-api/1.0/overview/file-uploads/status","default":false,"active":false,"folderId":"6bec560c"},{"version":"1.1","label":"1.1","link":"/omni-api/1.1/overview/file-uploads/status","default":false,"active":false,"folderId":"6bec560c"},{"version":"1.2","label":"1.2","link":"/omni-api/overview/file-uploads/status","default":true,"active":true,"folderId":"6bec560c"}],"sharedDataIds":{"sidebar":"sidebar-omni-api/@1.0/overview/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"File status and reconciliation"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"file-status-and-reconciliation","__idx":0},"children":["File status and reconciliation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/omni/files/{fileId}"]}," with the API token to read a file belonging to your issuer. A file ID has the form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fu_<UUID>"]},". Unknown files and files belonging to another issuer return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},". Polling reads persisted state and never starts processing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-files","__idx":1},"children":["List files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/omni/files"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"files\": [...], \"nextCursor\": \"fu_<UUID>\" }"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextCursor"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when no further page is available."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Query parameter"},"children":["Query parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextCursor"]}," from the preceding page; omit for the first page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["50"]},", maximum ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["percents-txn-stream"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plaid-txn-stream"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["omni-txn-stream"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txnStream"]}," filter."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingMode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automated"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manual"]}," filter."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Files are ordered by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}," descending and then file ID descending. Continue with the returned cursor and the same filters."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"status-fields","__idx":2},"children":["Status fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filename"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reservation identity, reconciliation name, and selected format."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp when the upload URL was reserved."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadExpiresAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upload URL expiry timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receivedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Actual object upload timestamp; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," before receipt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation completion timestamp, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingStartedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Actual ingestion start, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when ingestion has not begun."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingFinishedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Terminal file-handling timestamp, including validation failure and successful sandbox validation; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," before completion. It does not imply ingestion occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["csv"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_upload"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["received"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingMode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automated"]}," for native/Plaid; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manual"]}," for legacy formats."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validationStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["passed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_applicable"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_started"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed_with_errors"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation_only"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," before available; otherwise ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detectedRows"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ingestedRows"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["duplicateRows"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejectedRows"]},", each a non-negative integer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMetadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," or an error object with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," and optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missingAccountIds"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknownPercentsMerchantIds"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorUuid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error instance identifier for support, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detectedRows"]}," counts discovered transaction rows. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ingestedRows"]}," counts persisted transaction facts, including facts that receive a reward/business rejection. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["duplicateRows"]}," counts skipped known duplicates. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejectedRows"]}," counts file-validation or technical ingestion failures; reward eligibility rejection does not increment it. These counts do not represent reward approval."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All timestamps use ISO 8601. Raw object-storage metadata is not part of the public response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]}," means file ingestion completed. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed_with_errors"]}," means processing completed with reported row errors; inspect counts and error context. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," means validation or processing failed. Successful sandbox validation uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingStatus=validation_only"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validationStatus=passed"]},"; failed validation uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processingStatus=failed"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validationStatus=failed"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_applicable"]}," and manual processing allow reconciliation of legacy files without implying automated ingestion."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An uploaded file that cannot be read for validation receives a terminal failure with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorUuid"]}," and unknown counts. Other files continue processing. Contact support using that identifier and use a new filename when resubmitting the file."]}]},"headings":[{"value":"File status and reconciliation","id":"file-status-and-reconciliation","depth":1},{"value":"List files","id":"list-files","depth":2},{"value":"Status fields","id":"status-fields","depth":2}],"frontmatter":{"seo":{"title":"File status and reconciliation"}},"lastModified":"2026-10-02T20:53:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/omni-api/overview/file-uploads/status","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}