Reports

Payrails Reports let you export financial and operational data as CSV files for reconciliation, accounting, and business analysis. Reports are generated asynchronously — you request a report run, and once it completes, you download the file via a pre-signed URL. You can generate reports through the Payrails Portal or programmatically via the API.

Available report types

You can list all reports available to your organization using the Search & list reports endpoint.

Download reports via API

Generating a report is an asynchronous process. Follow these steps:

Step 1: Get an access token

Authenticate using your API credentials to obtain a bearer token. See Authentication for details.

Step 2: Create a report run

Submit a POST request to /analytics/reportRuns with your desired report type and date range.

POST /analytics/reportRuns
Authorization: Bearer <token>

{
  "reportCode": "payments",
  "parameters": {
    "intervalStart": "2026-04-01",
    "intervalEnd": "2026-04-07",
    "timezone": "Etc/UTC"
  }
}

The workspaceId field is optional. Include it only if you want to scope the report to a specific workspace. Omitting it returns data across all workspaces your credentials have access to.

Parameters

The API responds with 202 Accepted and a report run object in Pending status:

{
  "id": "cadb0015-3c26-4d7a-a9d3-2f8768b6d45a",
  "createdAt": "2026-04-08T10:20:00.000Z",
  "report": {
    "code": "payments",
    "name": "Payments"
  },
  "parameters": {
    "intervalStart": "2026-04-01",
    "intervalEnd": "2026-04-07",
    "timezone": "Etc/UTC"
  },
  "status": "Pending"
}

Step 3: Poll for completion

Report generation runs asynchronously. Poll GET /analytics/reportRuns/{id} using the id from the previous response until status changes from Pending to Successful.

GET /analytics/reportRuns/cadb0015-3c26-4d7a-a9d3-2f8768b6d45a
Authorization: Bearer <token>

Most report runs complete within 2–3 minutes. We recommend polling every 5–10 seconds.

Once complete, the response includes a result object with a pre-signed download URL:

{
  "id": "cadb0015-3c26-4d7a-a9d3-2f8768b6d45a",
  "status": "Successful",
  "result": {
    "fileName": "payments_2026-04-01_2026-04-07",
    "fileType": "csv",
    "url": "https://payrails-reports.s3.amazonaws.com/payments_2026-04-01_2026-04-07.csv",
    "expiresAt": "2026-04-09T10:20:00.000Z"
  },
  "completedAt": "2026-04-08T10:21:00.000Z"
}

Step 4: Download the CSV

Execute a GET request on result.url to download the file. This URL is pre-signed and expires at result.expiresAt — make sure to download the file before it expires.

Download reports via Portal

1. Log in to the Payrails Portal.
2. Navigate to Reports.
3. Select the report type and date range.
4. Click Download to export a CSV file.

Limitations

• File format: Reports are only available as CSV files.
• File size: Reports are capped at 5 GB per file. If your date range produces a report that exceeds this limit, the report run will fail. Reduce the date range and re-run the report.
• File expiry: The pre-signed download URL expires after a fixed TTL. Download the file before result.expiresAt. If it has expired, calling the GET /analytics/reportRuns/{id}endpoint will generate a new pre-signed download URL.
• No webhook or push notification: There is currently no callback or event mechanism to notify you when a report run is ready. Polling GET /analytics/reportRuns/{id} is the only way to check completion status. Build your integration to poll actively and handle both Successful and Failed terminal states.
• Report availability: The report types available to your organization depend on your Payrails module configuration. Use the Search & list reports endpoint to confirm which report codes are enabled for your account.

Error handling

Report runs can complete with a Failed status. Your integration should handle this explicitly. Do not assume a run will always succeed.

When a run fails, the response includes an error field with a code describing the reason.

{
  "id": "3c052d86-7f1d-44e2-b1b2-d331d492ebde",
  "status": "Failed",
  "error": "FILE_SIZE_EXCEEDED"
}

FAQ