API Reference: Reports

Overview

The Reports API manages saved reports end to end: create and configure a report (join paths and fields), trigger refreshes, read the computed rows, export them as a file, share reports with team users, and manage snapshots and snapshot schedules. A report combines data from a base collection with joined collections, selected fields, filters, and aggregation.

All Reports endpoints require the ADMIN_TEAM_REPORTS feature permission; mutating endpoints additionally require edit-level access to that permission. Every identifier on the wire is a public simplyId (CHAR-14 code such as REPT-1234-ABCD).

Key Concepts

• Report configuration — A base collection (reportBaseDataCollectionSimplyId) plus join paths, report fields, filters, and sort order. Fully editable through the API.
• Refresh — POST .../refresh queues a backend job that recomputes the report's data set and returns 202 immediately. POST .../run is an alias for the same operation.
• Report data — Available from GET .../data once the last refresh finished successfully; before that the endpoint returns an empty result set.
• Snapshot — A stored export of a report run, created manually or on a schedule, downloadable via a presigned URL.

Endpoints

Method	Path	Purpose
GET	/v1/reports	List saved reports.
POST	/v1/reports	Create a report.
GET	/v1/reports/{reportSimplyId}	Get a report definition.
PUT	/v1/reports/{reportSimplyId}	Update a report.
DELETE	/v1/reports/{reportSimplyId}	Delete a report.
POST	/v1/reports/{reportSimplyId}/refresh	Queue an on-demand refresh.
POST	/v1/reports/{reportSimplyId}/run	Alias for refresh.
POST	/v1/reports/{reportSimplyId}/copy	Create a personal copy of a report.
GET	/v1/reports/{reportSimplyId}/data	Read computed report rows.
GET	/v1/reports/{reportSimplyId}/export	Export report data as a file.
POST / PUT / DELETE	/v1/reports/{reportSimplyId}/join-paths[...]	Add, update, reorder, and delete join paths.
POST / PUT / DELETE	/v1/reports/{reportSimplyId}/fields[...]	Add, update, reorder, and delete report fields.
GET / POST / DELETE	/v1/reports/{reportSimplyId}/shares[...]	List, create, and remove report shares.
GET / POST / DELETE	/v1/reports/{reportSimplyId}/snapshots[...]	List, trigger, get, delete, and download snapshots.
GET / POST / PUT / DELETE	/v1/reports/{reportSimplyId}/snapshot-schedules[...]	Manage recurring snapshot schedules.

List Reports

Supports limit (default 100, max 500), offset, and an optional ownerTeamUserLinkSimplyId filter.

const reports = await s360.reports.list();

for (const report of reports.data) {
  console.log(`${report.reportSimplyId}: ${report.singularName}`);
}

curl -s "https://api.simply360.app/v1/reports?limit=50" \
  -H "Authorization: Bearer $S360_API_KEY"

Get Report Configuration

const report = await s360.reports.get('REPT-1234-ABCD');
console.log(report.data);

curl -s "https://api.simply360.app/v1/reports/REPT-1234-ABCD" \
  -H "Authorization: Bearer $S360_API_KEY"

Create a Report

Requires singularName and reportBaseDataCollectionSimplyId. Optional fields include pluralName and enumDataCollectionTypeId (PERSONAL_REPORT or TEAM_REPORT).

curl -s -X POST "https://api.simply360.app/v1/reports" \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "singularName": "Lapsed Donor",
    "pluralName": "Lapsed Donors",
    "reportBaseDataCollectionSimplyId": "COLL-1234-ABCD",
    "enumDataCollectionTypeId": "TEAM_REPORT"
  }'

After creating a report, add join paths (s360.reports.addJoinPath) and fields (s360.reports.addField). Join-path creation takes dataFieldSimplyId, fromDataCollectionSimplyId, and toDataCollectionSimplyId, with optional parentReportJoinPathSimplyId, joinType (LEFT, INNER, NOT_EXISTS), and multiRecordHandling (EXPLODE or ROLLUP).

Run a Report

Queues an asynchronous refresh of the report's data. The endpoint responds 202 with a PENDING status; poll the report definition or read /data once the refresh completes. If a refresh is already in progress the endpoint returns 409 CONFLICT.

const status = await s360.reports.run('REPT-1234-ABCD'); // or s360.reports.refresh(...)
console.log(`Status: ${status.data.refreshStatus}`); // "PENDING"

curl -s -X POST "https://api.simply360.app/v1/reports/REPT-1234-ABCD/run" \
  -H "Authorization: Bearer $S360_API_KEY"

Read Report Data

GET .../data accepts page, pageSize, sort, sortDir (ASC/DESC), and dataFilterState (JSON-encoded filter state). The response contains rows, columns, and paging meta. Until the report's last refresh succeeded, the endpoint returns an empty row set.

const data = await s360.reports.getData('REPT-1234-ABCD', { page: 1, pageSize: 100 });
console.log(data.data.meta.total);

Export Report Data

GET .../export?format=csv streams the export file (Content-Disposition: attachment). The format parameter accepts csv (default) or xlsx for a formatted Excel workbook. Exporting before a successful refresh returns 409 REPORT_DATA_NOT_READY.

curl -s -OJ "https://api.simply360.app/v1/reports/REPT-1234-ABCD/export?format=csv" \
  -H "Authorization: Bearer $S360_API_KEY"

# Excel export
curl -s -OJ "https://api.simply360.app/v1/reports/REPT-1234-ABCD/export?format=xlsx" \
  -H "Authorization: Bearer $S360_API_KEY"

Shares, Snapshots, and Schedules

• Shares — s360.reports.listShares / createShare / deleteShare grant other team users access to a report.
• Snapshots — s360.reports.listSnapshots / triggerSnapshot / getSnapshot / deleteSnapshot; getSnapshotDownloadUrl returns a presigned URL for the snapshot's export file.
• Snapshot schedules — s360.reports.listSnapshotSchedules / createSnapshotSchedule / updateSnapshotSchedule / deleteSnapshotSchedule automate recurring snapshots.

Usage Notes

• All Reports endpoints require the ADMIN_TEAM_REPORTS feature permission; create, update, delete, copy, and refresh also require edit-level access to it.
• run and refresh are the same operation. Calling either during an in-flight refresh returns 409 CONFLICT — wait for the current run to finish and retry.
• Copying a report (POST .../copy) requires an authenticated team-user context so the copy can be assigned an owner.
• Refreshed report output can also be inspected in the Simply360 dashboard.