Pagination, Sorting & Field Selection

Offset-Based Pagination

Simply360 list endpoints use offset-based pagination. You control pagination with two query parameters: limit and offset. (A few specialized endpoints document their own paging parameters in the API Reference.)

Parameter	Type	Default	Description
limit	integer	25	Number of records per page. Minimum 1, maximum 100.
offset	integer	0	Number of records to skip before returning results.

Example Request

curl -s "https://api.simply360.app/v1/data-records?dataCollectionSimplyId=XXXX-XXXX-XXXX&limit=10&offset=20" \
  -H "Authorization: Bearer $S360_API_KEY"

Pagination Metadata

Every paginated response includes a pagination object inside meta. Use the hasMore flag to determine whether additional pages exist.

{
  "data": [ ... ],
  "meta": {
    "requestId": "req_abc123def456",
    "pagination": {
      "total": 150,
      "limit": 25,
      "offset": 0,
      "hasMore": true
    }
  }
}

Field	Type	Description
total	integer	Total records matching the query (across all pages).
limit	integer	Limit applied to this request.
offset	integer	Offset applied to this request.
hasMore	boolean	true if more records exist beyond the current page.

Sorting

Use the sort query parameter to control the order of results. Prefix a field name with - for descending order. Separate multiple sort fields with commas; they are applied in order of precedence.

On GET /v1/data-records, the sortable fields are createdAt, updatedAt, and calculatedName (the record's display name). When no sort is provided, results are ordered by createdAt descending (newest first). Unrecognized sort fields fall back to createdAt.

Value	Meaning
sort=createdAt	Creation date ascending (oldest first).
sort=-createdAt	Creation date descending (newest first).
sort=-updatedAt,calculatedName	Last updated descending, then record name ascending as a tiebreaker.

curl -s "https://api.simply360.app/v1/data-records?dataCollectionSimplyId=XXXX-XXXX-XXXX&sort=-createdAt&limit=50" \
  -H "Authorization: Bearer $S360_API_KEY"

Paginating Through All Records

To retrieve every record in a collection, loop through pages until hasMore is false. The Simply360 SDK uses manual offset pagination — there is no auto-paginator helper, so you advance the offset yourself.

TypeScript SDK

import { Simply360 } from '@simply360/sdk';
import type { DataRecord } from '@simply360/sdk';

const s360 = new Simply360({ apiKey: process.env.S360_API_KEY! });

async function getAllRecords(dataCollectionSimplyId: string): Promise<DataRecord[]> {
  const all: DataRecord[] = [];
  const limit = 100;
  let offset = 0;

  while (true) {
    const response = await s360.dataRecords.list({
      dataCollectionSimplyId,
      limit,
      offset,
      sort: '-createdAt',
    });

    all.push(...response.data);

    if (!response.meta.pagination.hasMore) break;
    offset += limit;
  }

  return all;
}

Raw HTTP

async function getAllRecords(dataCollectionSimplyId: string, apiKey: string) {
  const all: unknown[] = [];
  const baseUrl = 'https://api.simply360.app/v1';
  const limit = 100;
  let offset = 0;

  while (true) {
    const url = `${baseUrl}/data-records?dataCollectionSimplyId=${dataCollectionSimplyId}&limit=${limit}&offset=${offset}&sort=-createdAt`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    if (!response.ok) throw new Error(`API ${response.status}`);

    const body = await response.json();
    all.push(...body.data);

    if (!body.meta.pagination.hasMore) break;
    offset += limit;
  }

  return all;
}

Field Selection

Use the fields query parameter to request only the fields you need. This reduces response size and can improve performance for large collections with many custom fields.

Pass a comma-separated list of DataField simplyIds.

curl -s "https://api.simply360.app/v1/data-records?dataCollectionSimplyId=XXXX-XXXX-XXXX&fields=FLDS-FRST-NAME,FLDS-LAST-NAME,FLDS-EMAL-ADDR" \
  -H "Authorization: Bearer $S360_API_KEY"

Field selection is also supported on GET /v1/data-records/{dataRecordSimplyId}.

Expanding Related Resources

Use the expand query parameter to include related metadata in the response, reducing the number of API calls. On DataRecord endpoints, the supported expansions are:

Value	Adds to the response
collection	The parent DataCollection's simplyId and name.
fieldDefinitions	The collection's DataField definitions (simplyId, name, column name, and data type).

Expansions are returned in the response's meta.expanded object rather than inline on each record. Unsupported expansion values are ignored.

curl -s "https://api.simply360.app/v1/data-records/WXYZ-5678-IJKL?expand=collection,fieldDefinitions" \
  -H "Authorization: Bearer $S360_API_KEY"

You can combine fields and expand in the same request: fields limits each record's fields object, while expand adds the related metadata under meta.expanded.