Builder Guide

Build custom data modules

Model your own business data with Dynamic Records, custom fields and RecordId, then use the same secured records in pages and through the API.

Dynamic modules let you model business data inside your SaaS without building a specialized feature for every kind of record. Think of it as a database builder within your application: a module defines a kind of thing, custom fields describe its business information, and each item has a permanent RecordId. An asset register, an inspection log or an equipment inventory can use this model.

The business information can consist entirely of custom fields. Standard record identity, title, status, timestamps and visibility still belong to the platform. This is a logical data model within your SaaS database; it does not create a separate SQL database for each module.

How the pieces fit together

A Contractors UserType and a dynamic module named Contractors are independent choices. A record does not create a login, and putting a page on a UserType menu does not grant access to its records.

Plan a module from custom fields

Start with one clear record type. For an asset register, the standard title could be Warehouse forklift 12, with these custom fields:

The current field editor offers Text, Whole number, Decimal, Date and time, Yes / no, Choice and Structured JSON. Choose field keys carefully, use clear labels, and set required behavior, length limits, choices, grouping and order where appropriate. Use record relationships for connections to other records rather than assuming that a text field containing an ID creates a relationship.

Configure fields and display the module

1. Start with a configured custom module. Confirm the module exists in the target app and organization and has its own key. The current product does not provide a standalone create-module wizard or module-definition-create API. Entering a new key in Custom fields does not create a module. Ask the app builder which configured modules are available before adding fields.
2. Define the shared model. In Design, open a page associated with the module. Its custom-field panel lets authorized designers add builder fields and control whether organizations may add their own fields, with configured limits.
3. Add organization-specific fields when allowed. Open Custom fields, choose the page and existing module, then choose Open module fields. Supply a Key, Label and Type, configure the behavior, and choose Add field. Organization field keys use the c_ prefix. Every read and save checks field-management permission and builder policy.
4. Display it with Dynamic Records. Use the module.dynamic-records block with the actual configured moduleKey. Its standard list, detail and form use the returned field schema. See Dynamic Records for the renderer and developer examples, and Build pages from feature parts for arranging the workspace.
5. Publish and test. Place the page in the intended UserType menus and homepage configuration. Test with users who have different DataRoles and locations, including permitted and denied reads, creates, edits and removals. Field definitions and page publication are separate operations; a page preview alone is not a permission test.

RecordId connects the data

The same canonical record can participate in permitted relationships, favorites and activity without a second copy of the business item. Use the supported record relationship tools to connect an asset to other records. Each connected record keeps its own permissions; a link never grants access to a hidden record. Availability of search, automation or AI also depends on that feature's configuration and permission rules.

Use dynamic records through the API

Integrations can discover a configured module's public schema and work with its records. The public Developer API base is /v1/apps/{saasAppId}/modules/dynamic. Browser clients use the corresponding signed-in routes under /api/modules/dynamic.

For example, after configuring an assets module and an organization text field named c_asset_tag, this body creates a Personal record through POST /{moduleKey}:

{
  "title": "Warehouse forklift 12",
  "isPersonal": true,
  "fields": [
    { "fieldKey": "c_asset_tag", "valueText": "FL-012" }
  ]
}

Read the actual schema before sending values; the example field must already exist, and any other required fields must also be supplied. For a shared record, explicitly select a permitted DataRole and, when active locations exist, an authorized location or All locations. All locations requires all-location authority; an omitted choice is not All. Personal records have no DataRole or location.

List requests support search, status, pageNumber, pageSize and sort. The supported list orders are created_asc, created_desc, title_asc and title_desc; a field's Sortable setting does not add an arbitrary field-sort parameter to this route. Page size is at most 100; a write accepts at most 200 field inputs, with configured limits and validation still applying.

Read current details before editing or removing and send the returned updatedUtc as expectedUpdatedUtc. A stale change is refused so an integration does not silently overwrite someone else's work. The current edit contract preserves the record's Personal/DataRole scope; do not send a new visibility choice in an ordinary update.

These are record-data operations. Builder field definitions and field policy have separate design operations under /v1/apps/{saasAppId}/design/fields/{moduleKey}. A record-create request does not create a module or add field definitions. Use the current API reference and Developer API guides for authentication, operation scopes and the exact request contracts.

Permissions apply everywhere

The API uses verified app, organization and user identity and the same secured services and stored procedures as the browser. Developer credentials need the appropriate API scope and an authorized tenant principal. Reads and mutations still enforce Personal ownership or current DataRole and location permissions, with separate create, edit and remove authority. Each SaaS retains its own database set.

Hidden and encrypted fields are excluded from the generic public dynamic schema. Sensitive fields require their supported secure-field controls and permission-checked reveal/edit flow; this generic field API is not a way to reveal or overwrite them.

Capability review: 2026-09-14. See current features and setup requirements, the generated API Map and first-class module inventory.