API Reference: Data Wizards

List Data Wizards, inspect their schema, and execute them programmatically.

Overview

Data Wizards are configurable multi-step forms that guide users through creating or updating records, sending messages, and following workflows. Wizards can be used by team members internally or embedded externally for constituents (for example, a public registration form on a marketing site). The API lets you list wizards, inspect their input schema, and execute them programmatically against a target record.

The list, get, and schema endpoints require the TEAM_ADMIN_DATA_WIZARDS feature permission on your API key or token.

Key Concepts

Steps — Each wizard is an ordered sequence of steps. A step collects field values, displays information, requires authentication, or executes step tasks.
Step Tasks — Actions that run when a step is submitted: update fields, create a record, send a message, and so on. Tasks that collect input link to specific Data Fields.
Schema — The wizard's programmatic input shape: its steps, each step's tasks, and the fields each task collects (with data type and required flag).
Target record — Programmatic execution runs the wizard against an existing Data Record identified by dataRecordSimplyId.
Embeddable — Wizards can be embedded on external websites using the Simply360 embed library or accessed via a direct URL. See Embedding DataViews, Wizards & the Conversation Widget.

List Wizards

Returns the selected team's wizards, newest first. limit and offset are optional; omit them to return all wizards.

TypeScript SDK

const wizards = await s360.dataWizards.list();

for (const wizard of wizards.data) {
  console.log(`${wizard.id}: ${JSON.stringify(wizard.name)}`);
}

cURL

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

Get a Wizard

Retrieve a wizard's configuration including its ordered steps and firstStepId.

TypeScript SDK

const wizard = await s360.dataWizards.get('WIZD-1234-ABCD');
for (const step of wizard.data.steps ?? []) {
  console.log(`Step: ${JSON.stringify(step.title ?? step.name)}`);
}

cURL

curl -s "https://api.simply360.app/v1/data-wizards/WIZD-1234-ABCD" \
  -H "Authorization: Bearer $S360_API_KEY"

Get Wizard Schema

The schema endpoint returns just the input shape — useful for AI agents and code generators that need to know what to submit without parsing the full step tree. Steps contain tasks; tasks that collect input list their linked fields.

cURL

curl -s "https://api.simply360.app/v1/data-wizards/WIZD-1234-ABCD/schema" \
  -H "Authorization: Bearer $S360_API_KEY"

Response Shape

{
  "data": {
    "dataWizardSimplyId": "WIZD-1234-ABCD",
    "name": { "en": "Volunteer Signup" },
    "steps": [
      {
        "dataWizardStepSimplyId": "STEP-1234-ABCD",
        "title": { "en": "Contact Details" },
        "tasks": [
          {
            "dataWizardStepTaskSimplyId": "TASK-1234-ABCD",
            "type": "UPDATE_DATA_RECORD",
            "title": { "en": "Collect contact info" },
            "fields": [
              {
                "dataFieldSimplyId": "FLDS-EMAL-ADDR",
                "columnName": "emailAddress",
                "dataType": "EMAIL_ADDRESS",
                "name": { "en": "Email Address" },
                "isRequired": true
              }
            ]
          }
        ]
      }
    ]
  }
}

SDK: await s360.dataWizards.getSchema('WIZD-1234-ABCD') returns the same payload.

Execute a Wizard

Run a wizard's steps and tasks server-side against a target Data Record. The body requires dataRecordSimplyId (the record to execute against) and accepts an optional formData object keyed by field id for tasks that collect input. The response confirms success and how many steps were processed.

Execution writes data. The caller needs the wizard's RUN data permission (system and team admins bypass this), and session tokens are not accepted on this endpoint.

TypeScript SDK

const result = await s360.dataWizards.execute('WIZD-1234-ABCD', {
  dataRecordSimplyId: 'WXYZ-5678-IJKL',
  formData: {
    'FLDS-FRST-NAME': 'Jane',
    'FLDS-LAST-NAME': 'Doe',
    'FLDS-EMAL-ADDR': 'jane@example.com',
  },
});

console.log(result.data); // { success, message, dataWizardSimplyId, dataRecordSimplyId }

cURL

curl -s -X POST "https://api.simply360.app/v1/data-wizards/WIZD-1234-ABCD/execute" \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataRecordSimplyId": "WXYZ-5678-IJKL",
    "formData": {
      "FLDS-FRST-NAME": "Jane",
      "FLDS-LAST-NAME": "Doe",
      "FLDS-EMAL-ADDR": "jane@example.com"
    }
  }'

Run Access

GET /v1/data-wizards/{dataWizardSimplyId}/run-access verifies that the signed-in user can run a wizard and returns run metadata (firstDataWizardStepSimplyId, stepCount). This endpoint accepts Cognito user authentication only — it backs first-party wizard launch surfaces and is not callable with an API key.

Authoring Operations

Wizard authoring is exposed as a privileged-tier surface (admin feature permissions required; not available to OAuth-scoped tokens): create/update/delete wizards (POST/PUT/DELETE /v1/data-wizards[/{dataWizardSimplyId}]), steps (/v1/data-wizard-steps), step tasks (/v1/data-wizard-step-tasks), task field and collection links, external-access collection links, plus admin-list, admin-detail, submission instances, and Studio readiness reads. Author wizards in DataWizard Studio unless you are building schema tooling.

Wizard Outcome Operations

Signed-in Cognito Team Users can use the privileged Wizard Studio outcome surface:

GET /v1/data-wizards/{dataWizardSimplyId}/outcomes returns success/error Automation summaries with public IDs and redacted execution status.
POST /v1/data-wizards/{dataWizardSimplyId}/outcome-presets/preview validates a guided preset and returns its canonical configuration, output/field/terminal manifest, generated content, blockers, warnings, and review fingerprint.
POST /v1/data-wizards/{dataWizardSimplyId}/outcome-presets/apply accepts that exact reviewed configuration, fingerprint, and idempotency key and atomically creates or updates the managed assets.
PATCH /v1/data-wizards/{dataWizardSimplyId}/outcomes/{automationSimplyId}/enabled enables or disables one same-Wizard Automation.

These operations are first-party privileged endpoints, not API-key or OAuth operations. Reads require Wizard view feature/object access; preview/apply/enablement require Wizard manage-settings access. Presets also enforce readable fields and relationship paths, same-Team active senders/recipients, Outgoing Message template permission, and fixed-recipient send permission where applicable. All entity references are public *SimplyId values. Use the generated OpenAPI schemas and TypeScript SDK rather than constructing untyped configuration.

Usage Notes

Use the schema endpoint to discover the inputs a wizard expects before calling execute — especially useful when the wizard configuration changes.
Execution runs the wizard's steps and tasks in sequence server-side and returns once processing completes; it preserves calculated names, generated-record side effects, and audit attribution.
Wizard completion can trigger automations (WIZARD_COMPLETED / WIZARD_COMPLETION_FAILED triggers). See API Reference: Automations.
Embedded wizards on third-party sites use the Simply360 embed library, which handles step-by-step interaction for end users — no API key in the browser.