API Reference: Data Collections

Overview

Data Collections define the schema for your data in Simply360. Each collection has a set of typed fields that determine what its records can store, and may carry an archetype that describes what the collection represents (for example, PERSON archetypes power messaging and conversation features). The read endpoints on this page are standard-tier and work with any API key whose Data Role can read the collection. Schema administration (creating collections, renaming, managing settings) is also available over the API as a privileged, first-party surface — see Administration & Schema Operations below.

Key Concepts

• Archetype — Optional classification of what a collection represents: PERSON, ORGANIZATION, EVENT, LOCATION, COMMUNICATION, CASE, INVOICE, FINANCIAL_TRANSACTION, TASK, PROJECT, HOUSEHOLD, CAMPAIGN, or PARTICIPATION. Child collections can inherit their parent's archetype; responses expose both archetype and effectiveArchetype.
• Collection type — The type / enumDataCollectionTypeId value: STANDARD collections own records directly, SMART collections compute membership from filter criteria, and CUSTOM_LIST collections back list-style fields.
• Fields — Each collection contains typed fields (text, number, date, email, phone, record references, files, images, and more). Every field definition carries a public dataFieldSimplyId.
• Display name — A configurable expression (dataRecordCalculatedNameFormula) that determines how each record is labeled. The computed label is returned as name on Data Record responses.
• Localized names — name, singularName, pluralName, and field titles may be plain strings or objects keyed by language tag (for example { "en": "People" }).

List Collections

Retrieve all collections readable by your API key's Data Role. Each summary includes id (the collection's simplyId), names, archetype, type, fieldCount, recordCount, and parentDataCollectionSimplyId.

TypeScript SDK

const collections = await s360.dataCollections.list();

for (const col of collections.data) {
  console.log(`${col.id}: ${JSON.stringify(col.name)} (${col.archetype ?? 'no archetype'})`);
}

cURL

curl -s "https://api.simply360.app/v1/data-collections" \
  -H "Authorization: Bearer $S360_API_KEY"

Get a Collection

Retrieve a single collection. The response includes its full readable field schema in the fields array.

TypeScript SDK

const collection = await s360.dataCollections.get('XXXX-XXXX-XXXX');

for (const field of collection.data.fields) {
  console.log(`${field.dataFieldSimplyId}: ${JSON.stringify(field.title)} (${field.dataType})`);
}

cURL

curl -s "https://api.simply360.app/v1/data-collections/XXXX-XXXX-XXXX" \
  -H "Authorization: Bearer $S360_API_KEY"

List Fields

Retrieve only the fields for a specific collection. Each field definition includes dataFieldSimplyId, title, columnName, dataType, isRequired, sortOrder, and the field's config settings object.

TypeScript SDK

const fields = await s360.dataCollections.listFields('XXXX-XXXX-XXXX');

for (const field of fields.data) {
  console.log(`${field.dataFieldSimplyId}: ${JSON.stringify(field.title)} [${field.dataType}]`);
}

cURL

curl -s "https://api.simply360.app/v1/data-collections/XXXX-XXXX-XXXX/fields" \
  -H "Authorization: Bearer $S360_API_KEY"

Get a Single Field

const field = await s360.dataCollections.getField('XXXX-XXXX-XXXX', 'FLDS-FRST-NAME');

curl -s "https://api.simply360.app/v1/data-collections/XXXX-XXXX-XXXX/fields/FLDS-FRST-NAME" \
  -H "Authorization: Bearer $S360_API_KEY"

Common Field Types

The dataType value on a field definition is one of the platform's field data types. Common values:

Type	Description	Example Value
PLAIN_TEXT	Single-line text	"Jane Doe"
FORMATTED_TEXT	Rich text / HTML	"<p>Hello</p>"
NUMBER	Whole number	42
DECIMAL	Decimal number	42.5
MONEY	Monetary amount	199.00
DATE	ISO 8601 date	"2026-03-06"
DATE_TIME	ISO 8601 timestamp	"2026-03-06T14:30:00Z"
EMAIL_ADDRESS	Email address	"jane@example.com"
PHONE_NUMBER	Phone in E.164 format	"+15551234567"
BOOLEAN	True / false toggle	true
URL	Web address	"https://example.org"
PHYSICAL_ADDRESS	Structured postal address	Address object
SINGLE_DATA_RECORD	Reference to one record in another collection	Record simplyId
MULTI_DATA_RECORD	References to multiple records	Array of simplyIds
SINGLE_FILE / MULTI_FILE	File attachment(s)	File simplyId(s)
SINGLE_IMAGE / MULTI_IMAGE	Image attachment(s)	File simplyId(s)

Administration & Schema Operations

Beyond the standard read endpoints, the API exposes the schema-administration surface the Simply360 dashboard itself uses. These operations are privileged tier: they require admin-level feature permissions and are not available to OAuth-scoped tokens.

Endpoint	Description
POST /v1/data-collections	Create a data collection for the selected team.
POST /v1/data-collections/{dataCollectionSimplyId}/rename	Rename a collection (singular/plural names and underlying table).
GET / PUT /v1/data-collections/{dataCollectionSimplyId}/admin-detail	Read or update full admin settings for a collection.
PUT /v1/data-collections/{dataCollectionSimplyId}/field-display-overrides	Update inherited-field display overrides.
POST /v1/data-collections/{dataCollectionSimplyId}/generate-field-descriptions	AI-generate field and collection descriptions; apply reviewed output with PATCH .../apply-field-descriptions. Bulk variants exist for both.
POST /v1/data-collections/{dataCollectionSimplyId}/recalculate-record-names	Recalculate all record display names.
POST /v1/data-collections/{dataCollectionSimplyId}/recalculate-calculated-relationship-fields	Recalculate calculated-relationship field values.
POST /v1/data-collections/{dataCollectionSimplyId}/preview-smart-membership	Preview SMART collection membership for a draft filter.
POST /v1/data-collections/{dataCollectionSimplyId}/resync-smart-membership	Resync SMART collection membership.
POST /v1/data-collections/{dataCollectionSimplyId}/import-token	Generate a short-lived CSV import token for the collection.

For whole-schema workflows, the standard-tier Team Schema endpoints export and version the complete team schema (collections, fields, views, wizards, and automations):

• GET /v1/team-schema/export — export the team's complete schema.
• GET /v1/team-schema/versions and GET /v1/team-schema/versions/compare — version history and diffs.
• GET /v1/team-schema/changed — check whether the schema has changed since the last snapshot.

Related: GET /v1/create-menu/data-collections/{dataCollectionSimplyId} (standard tier) returns create-form metadata for a collection — the field layout the dashboard's create menu renders.

Usage Notes

• Collection and field simplyId values are stable identifiers. Use them for integrations and configuration rather than display names.
• When creating or updating Data Records, the keys of the fields object are always field simplyIds, never the human-readable field title. See API Reference: Data Records.
• Computed values (record display names, aggregated fields) are calculated server-side and cannot be written through the API.
• SMART collections compute their membership from filter criteria; create records in the underlying standard collections instead.
• Field visibility is permission-scoped: the API only returns fields the caller's Data Role can read, and fieldCount reflects that scope.