Managing Data
A Form defines the fields and access rules for structured data. The API calls it a DataType. A DataRecord holds one submission's field values.
Create and publish the Form before writing records. Use the Forms guide for the editor; this section covers the API contracts and synchronization work.
Tasks
| Guide | What you will do |
|---|---|
| Creating Members | Connect identities from your system to Members, then preview and import a CSV. |
| Importing Data | Create or update Form records through REST or CSV. |
| Exporting Data | Retrieve records and receive changes through webhooks. |
| Working with PHI | Confirm workspace authorization and label sensitive Form fields before sending patient data. |
Schema and records
| API concept | Meaning |
|---|---|
| DataType | A Form's schema, identified by its ID or slug. |
| Field slug | The key used in a record's fieldValues; use the schema's slug, not its display label. |
| DataRecord | A record with its own ID, field values, and applicable ownership. |
externalId | An identifier from your system, used to reconcile records through the upsert API. |
isCollection | Whether the Form supports multiple records rather than one per Member. |
Read the DataTypes reference for the current schema and field types, and the DataRecords reference for request and response fields. These references own the complete field lists.
Ownership and access
recordScope distinguishes Member-owned records, workspace records, and anonymous
submissions. Anonymous Forms use a separate submission API; they do not create
DataRecords. Use the Forms guide to choose the appropriate
scope and the DataTypes reference to configure it programmatically.
On a Member-scoped Form, a Member can work with their own records without a
separate Role grant on that Form. Every Workspace Member can read workspace-scoped
records; creating, editing, or deleting them requires records:write.
An adminOnly Form restricts its records to Members with records:admin, including
records they would otherwise own. Admin-only fields also require records:admin.
Keep PHI handling and field sensitivity separate from
these access controls.
Supplying a memberId or externalId does not grant access to another Member's
records. Writing for another Member requires records:write; reading their records
requires applicable administrative, sharing, or chart-access authority. Use an
explicit access grant to share a specific
resource rather than adding a per-Form Role permission. Assignment-scoped access
remains limited to that Assignment's records.
Synchronization identifiers
Keep your system's identifier separate from Gravity Rail's record ID. Use the explicit upsert request when repeating an import should update the same record. External IDs match within a DataType; use the same Form and identifier on subsequent requests.
For Member identity reconciliation, follow Creating Members. For file bytes and sharing, use the Files reference and File sharing reference; Form record imports do not upload files automatically.
Expressions and message templates use the same data through their documented contexts. See Prompt Templates and CEL Expressions for context availability and paths.