List Response Types

Payiano's API provides a flexible response system for all list endpoints, allowing developers to control how data is returned — whether as standard JSON, aggregated summaries, or downloadable export files.

This unified approach ensures that the same endpoint can serve both API integrations and analytical or reporting use cases efficiently.

Tip: Use the response_type query parameter to control the output format of any list endpoint. The same filtering, sorting, and pagination parameters work consistently across all response types.

Response Types Overview

API Integration

json_list

Standard JSON responses with pagination metadata. Ideal for building user interfaces, data tables, and general API integrations.

Analytics & Reporting

json_aggregate

Aggregated data with metrics and grouping. Perfect for dashboards, business intelligence, and analytical applications.

Data Export

CSV / XLS / XLSX

Downloadable files in various formats for external analysis, reporting tools, and data sharing with stakeholders.

Unified Interface

Consistent

Same parameters work across all response types. Apply filters, sorting, and includes regardless of output format.

Response Type Comparison

Response TypeContent TypeUse CaseDefaultIncludes Support
json_listapplication/jsonAPI integrations, UI development
json_aggregateapplication/jsonDashboards, analytics, reporting
—
—
export_csvtext/csvData sharing, spreadsheet analysis
—
export_xlsapplication/vnd.ms-excelLegacy Excel compatibility
—
export_xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetModern Excel and spreadsheet tools
—
Note: json_list is the default response type and does not need to be explicitly specified. The includes parameter works with both json_list and export formats.

Detailed Response Formats

json_list Standard JSON Response

Default

The default response type that returns a paginated list of resources with comprehensive metadata. Ideal for building user interfaces and general API integrations. No need to specify this explicitly unless overriding another response type.

Key Features

  • Full pagination metadata
  • Support for includes parameter
  • Complete resource objects with all fields
  • Optimized for UI consumption
  • Default response type (no parameter needed)

Response Structure

interface IJsonListResponse { items: (IItem)[] current_page: number per_page: number total_items: number total_pages: number }
GET/client/customers?response_type=json_list
Sandbox: https://api.payiano.dev/v1/client/customers?response_type=json_list
Live: https://api.payiano.com/v1/client/customers?response_type=json_list
Response
200
Response schema:
application/json
Response body:
total_pages
Type: integer

The total number of pages that are available for the items search criteria.

current_page
Type: integer

The current pagination page.

per_page
Type: integer

The amount of items items return per page.

total_items
Type: integer

The total number of items that match the search criteria.

items
Type: array_of_objects

The list of items that match the search criteria.

Response sample:
1
{ 2 "per_page": 25, 3 "total_pages": 1, 4 "total_items": 1, 5 "current_page": 1, 6 "items": [] 7}

json_aggregate Aggregated Analytics

Returns aggregated data with metrics and grouping capabilities. Requires the aggregations parameter to define which metrics and dimensions to compute.

Key Features

  • Support for count, sum, avg metrics
  • Multi-dimensional grouping
  • Metadata describing aggregation structure
  • Optimized for dashboards and BI tools
  • Requires aggregations parameter
Learn more: See our Data Aggregations Guide for detailed usage examples.

Response Structure

enum FieldTypes { 'boolean' = 'boolean', 'date' = 'date', 'enum' = 'enum', 'enum_number' = 'enum_number', 'number' = 'number', 'reference_id' = 'reference_id', 'string' = 'string', 'datetime' = 'datetime', 'ulid' = 'ulid', 'id' = 'id' } type FieldType = keyof typeof FieldTypes
interface IFieldValue { metric: 'avg' | 'count' | 'sum' value: string | number }
interface IField { field: string values: (IFieldValue)[] }
interface IMetadataGroupBy { field: string type: FieldType }
interface IGroupBy { field: string type: FieldType value: string | number }
interface IItem { group_by: (IGroupBy)[] fields: (IField)[] }
interface IMetadata { group_by: (IMetadataGroupBy)[] }
interface IJsonAggregateResponse { items: (IItem)[] metadata: IMetadata }
GET/client/customers?response_type=json_aggregate
Sandbox: https://api.payiano.dev/v1/client/customers?response_type=json_aggregate
Live: https://api.payiano.com/v1/client/customers?response_type=json_aggregate

export_* File Export Formats

Generate downloadable files in various formats for external analysis, reporting tools, and data sharing. All export formats support the same filtering, sorting, and includes as JSON responses.

export_csv CSV Export

Comma-separated values format. Lightweight and widely compatible with spreadsheet applications and data analysis tools.

Content-Type: text/csv

export_xls Excel XLS

Legacy Excel format (.xls). Compatible with older versions of Microsoft Excel and other spreadsheet applications.

Content-Type: application/vnd.ms-excel

export_xlsx Excel XLSX

Modern Excel format (.xlsx). Recommended for current versions of Microsoft Excel, Google Sheets, and other modern applications.

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Export Response Headers

Export responses return file downloads with appropriate Content-Type headers and include a Content-Disposition header that triggers automatic file downloads in browsers and specifies the filename. The response body will be the binary file content rather than JSON.

Content-Disposition: attachment; filename=customers-2025-10-28.csv

The filename follows the pattern: {resource-plural}-{YYYY-MM-DD}.{ext} (e.g., customers-2025-10-28.csv)