GET
/
external-api
/
v1
/
reports
List Reports
curl --request GET \
  --url https://getbill.io/external-api/v1/reports \
  --header 'Authorization: <authorization>'
{
  "error": false,
  "data": [
    {
      "id": "report_abc123",
      "type": "financial",
      "title": "Monthly Financial Summary - January 2024",
      "description": "Comprehensive financial report including debt amounts, collection rates, and revenue analysis",
      "status": "completed",
      "filename": "financial_summary_2024_01.pdf",
      "file_size": 245760,
      "mime_type": "application/pdf",
      "period_from": "2024-01-01",
      "period_to": "2024-01-31",
      "generated_at": "2024-02-01T09:30:00Z",
      "created_at": "2024-02-01T09:00:00Z",
      "download_available": true
    },
    {
      "id": "report_def456",
      "type": "collection",
      "title": "Collection Performance Report - Q4 2023",
      "description": "Quarterly analysis of collection activities, success rates, and team performance",
      "status": "completed",
      "filename": "collection_performance_q4_2023.xlsx",
      "file_size": 186420,
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "period_from": "2023-10-01",
      "period_to": "2023-12-31",
      "generated_at": "2024-01-15T14:22:00Z",
      "created_at": "2024-01-15T14:00:00Z",
      "download_available": true
    }
  ],
  "pagination": {
    "total": 47,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

​
Overview

This endpoint returns a list of all reports generated for your company, including financial summaries, collection statistics, and performance analytics.

​
Authentication

Requires a valid OAuth 2.0 access token with the reports:read scope.

​
Request

​
Authorization
string
required
Bearer token for authentication

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"20"
Number of items per page (maximum 100)
​
type
string
Filter by report type (financial, collection, performance)
​
status
string
Filter by report status (generating, completed, failed)
​
period_from
string
Filter reports covering periods from this date (YYYY-MM-DD)
​
period_to
string
Filter reports covering periods to this date (YYYY-MM-DD)
​
generated_after
string
Filter reports generated after this date (YYYY-MM-DD)
​
generated_before
string
Filter reports generated before this date (YYYY-MM-DD)

​
Example Request

curl -X GET "/external-api/v1/reports?type=financial&status=completed&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response

​
error
boolean
Always false for successful requests
​
data
array
Array of report objects
​
pagination
object
Pagination metadata

​
Success Response

{
  "error": false,
  "data": [
    {
      "id": "report_abc123",
      "type": "financial",
      "title": "Monthly Financial Summary - January 2024",
      "description": "Comprehensive financial report including debt amounts, collection rates, and revenue analysis",
      "status": "completed",
      "filename": "financial_summary_2024_01.pdf",
      "file_size": 245760,
      "mime_type": "application/pdf",
      "period_from": "2024-01-01",
      "period_to": "2024-01-31",
      "generated_at": "2024-02-01T09:30:00Z",
      "created_at": "2024-02-01T09:00:00Z",
      "download_available": true
    },
    {
      "id": "report_def456",
      "type": "collection",
      "title": "Collection Performance Report - Q4 2023",
      "description": "Quarterly analysis of collection activities, success rates, and team performance",
      "status": "completed",
      "filename": "collection_performance_q4_2023.xlsx",
      "file_size": 186420,
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "period_from": "2023-10-01",
      "period_to": "2023-12-31",
      "generated_at": "2024-01-15T14:22:00Z",
      "created_at": "2024-01-15T14:00:00Z",
      "download_available": true
    }
  ],
  "pagination": {
    "total": 47,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

​
Report Types

  • Monthly/quarterly revenue summaries
  • Debt portfolio analysis
  • Payment collection rates
  • Outstanding amounts by aging
  • Followup activity summaries
  • Agent performance metrics
  • Communication channel effectiveness
  • Success rate analysis
  • KPI dashboards
  • Trend analysis
  • Comparative period reports
  • Goal tracking
  • User-defined report configurations
  • Filtered data exports
  • Specialized analytics

​
Error Responses

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}