Upload files

In order to extend your data set with us directly we provide you with the option to upload files. These files are processed to enhance our data models and improve the accuracy of visualizations and insights available through our analytics tools. This option also gives ability to share files that are specifically needed in order to run our reconciliation product for you.

You can upload files in the following ways

• Upload files programmatically using our FileUpload API
• Upload files through the Portal view (coming soon)

Structure Overview

To ensure successful processing, please adhere to the following specifications:

• Format: Only CSV files are currently supported.
• Size Limit: Maximum 5GB per file.
• Schema: Files must follow the same schema as defined in our Transactions Report https://docs.payrails.com/docs/transactions#/

Upload files via API - How It Works

1. Request an Upload URL

   Call the POST /analytics/files/upload endpoint to request a temporary, pre-signed S3 URL. This URL acts as a secure, one-time gateway to our storage. Request Body as below:

   {
     "datasetType": "transactions",
     "file": {
       "name": "testprovider_transactions_2025-01-01.csv",
       "type": "csv"
     }
   }

2. Upload Your File (Technical Implementation)

   Once you have the pre-signed URL, you can upload your data file using a standard HTTP PUT request.

   Using curl: For a quick implementation or testing, you can use the following curl command. We recommend using the --write-out flag during testing to verify the HTTP status code returned by the server.

   Bash

   curl --request PUT \
     --upload-file '{your_file_path}' \
     '{presigned_url}' \
     --write-out "\nHTTP_STATUS:%{http_code}\n"

   • Note: The -write-out portion is optional but highly useful for debugging; a successful upload will return an HTTP 200.
   • Expiration: The pre-signed URL is valid for 1 hour. If the upload does not start within this window, you must request a new URL.

3. Processing & Validation

   After the upload is complete, our system automatically begins validation in the background. We check the file for structural integrity and header alignment.

4. Check File Status

   Since large files (up to 5GB) may take time to process, you can monitor the progress programmatically.

   • Endpoint: GET /analytics/files/{id}
   • Details: Retrieve the current processing status (Pending, Processing, Completed, or Failed) and view import statistics once finished.

5. Data Integration & Visualization

   Once the status is marked as Complete, your data is automatically merged into our analytics engine where we further process it. Once processing is complete, your custom data will now power your dashboards, providing a unified view of your performance and reconciliation insights.

📘

Note on Performance: Files containing large volumes of data may take longer to process and visualize. We recommend monitoring the file status via the API for high-volume uploads.