Skip to main content

Exporting Data

Use the DataRecords API to read a page of records, or download a CSV when you need a file. For the shared schema and ownership model, see Managing Data. To write or round-trip a file, see Importing Data. The DataRecords API reference and Members API reference define the complete request and response schemas.

The commands below use synthetic data and environment variables. Keep API keys in a secret manager or shell environment; do not print credentials or log CSV rows. Before sending PHI, follow Working with PHI.

List Form records​

Set GRAVITYRAIL_API_KEY, GRAVITYRAIL_WORKSPACE_UUID, and GRAVITYRAIL_DATA_TYPE_ID for a test workspace and Form. The route is GET /api/v2/w/{workspace_uuid}/data-types/{data_type_id}/records:

curl --fail-with-body \
  "https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/data-types/${GRAVITYRAIL_DATA_TYPE_ID}/records?page=1&page_size=10" \
  --header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}"

The response is a paginated object with items, total, page, pageSize, and totalPages. Each item is a DataRecord; its fieldValues keys are Form field slugs. The page number starts at 1. page_size defaults to 10 and accepts 1–100; an invalid value falls back to 10.

Supported filters are:

ParameterEffect
member_idRecords owned by one Member.
member_idsComma-separated Member IDs, up to 100. Takes precedence over member_id.
search and search_fieldSearch text within the selected field slug. Both are needed for field search.
dataRecordFilterIdApply a saved record filter.
queryApply a JSON Query IR predicate for data_record.
page, page_sizeSelect the page and its size.

A saved filter and query are combined with the other criteria. Arbitrary field names are not interpreted as filters: parameters such as email, status, sortBy, and sortOrder do not filter or sort these records. Use a saved filter or the documented query predicate for field conditions. The request requires records:read and the Form's read access. The response is further limited by record and field permissions for the acting Member.

Export a Form's records​

In the Workspace, open Forms, open the Form's records, then select Export. The API uses POST with no request body:

curl --fail-with-body --request POST \
  "https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/data-types/${GRAVITYRAIL_DATA_TYPE_ID}/export" \
  --header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
  --output records.csv

The caller needs records:read, the required session assurance, and list_all access to the DataType. The export includes records and fields the caller is authorized to read; it does not bypass record grants or field visibility. See the DataRecords API reference for the current permission and endpoint contract.

The CSV starts with Record ID, External ID, Member ID, Created At, and Updated At, followed by readable Form fields. Record ID is the record's UUID, which a re-import uses to update that same record. Its final column is Gravity Rail Export v1. Every cell is quoted. String values that spreadsheet software could evaluate as formulas are reversibly escaped in the file; list and object values are written as JSON. Keep the marker column when re-importing an unedited export so the importer can restore escaped text and structured values. See Importing Data for the round-trip behavior and import limits.

Export Members​

POST /api/v2/w/{workspace_uuid}/members/export downloads a Member CSV. It requires the members:admin scope. For example, select Member ID and name and filter to non-archived Members:

curl --fail-with-body --request POST \
  "https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/members/export?selected_fields=id&selected_fields=name&is_archived=false" \
  --header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
  --output members.csv

selected_fields and selected_data_types may be repeated. When omitted, selected_fields uses the documented default Member columns. Selected non-collection Forms add columns named form.<form-slug>.<field-slug>. Available filters include search, role, memberFilterId, a JSON query, member_types, and is_archived. member_types accepts a comma-separated list; the older singular member_type is deprecated. Archived Members are excluded by default. The Members API reference lists valid fields, filters, and response behavior.

Member exports can include identity and Form values. Store the downloaded file with the same controls as the source Workspace data. Do not put row values, emails, phone numbers, or patient information into application logs or support reports.

Receive changes with webhooks​

Webhooks are separate from CSV exports. Choose the contract that matches your configuration and use its reference for setup, signatures, event bodies, and delivery behavior:

The V1 payload reference provides the event-specific bodies. Do not infer delivery guarantees from a successful API write; use the relevant webhook version's documented retry and delivery contract.