Form Interaction

When to Use

• Collecting additional information before a workflow can proceed
• AI output review with structured feedback fields
• Exception handling — ask a human to fill in missing or ambiguous data
• Onboarding steps that require verified user input
• Audit-required sign-off with structured attestation fields

Atlas Forms Integration

The form type uses Atlas Forms as its form engine. You define the form in the Atlas Forms designer using a formId. At runtime, EdgeInteract fetches the form schema by formId and renders it inside FormComponent. The user fills in the fields and submits — the submitted data is returned as the response payload.

Live Mockup

Request Payload Schema

interface FormPayload {
  /** Atlas Forms form ID — fetched from Atlas Forms service at render time */
  formId: string;

  /** Optional: pre-populate form fields with known values */
  initialValues?: Record<string, any>;

  /** Optional: context message shown above the form */
  context?: string;
}

Full Request Example

const response = await sendInteraction({
  type: 'form',
  targetUserId: 'usr_vendor_ops_team',
  title: 'Vendor Onboarding — Missing Information',
  payload: {
    formId: 'vendor-onboarding-v2',
    context: 'The following vendor record is missing required fields. Please complete and submit.',
    initialValues: {
      legalName: 'Acme Supplies Ltd',   // pre-populate known values
      country: 'IE'
    }
  },
  timeoutMs: 604_800_000,   // 7 days
  priority: 'normal'
});

if (response.outcome === 'submitted') {
  const { taxNumber, contactEmail, paymentTerms } = response.data.formData;
  await vendorService.updateRecord(vendorId, { taxNumber, contactEmail, paymentTerms });
}

Response Schema

interface FormResponse {
  interactionId: string;
  respondedBy:   string;
  outcome:       'submitted';
  data: {
    /** The submitted form values, keyed by field name as defined in Atlas Forms */
    formData: Record<string, any>;

    /** Atlas Forms submission ID for traceability */
    submissionId?: string;
  };
  timestamp: string;
}

Response Example

{
  "interactionId": "int_01HXYFORM99Z",
  "respondedBy":   "usr_vendor_ops_alice",
  "outcome":       "submitted",
  "data": {
    "formData": {
      "legalName":    "Acme Supplies Ltd",
      "taxNumber":    "IE1234567T",
      "contactEmail": "ap@acme.com",
      "paymentTerms": "Net 30"
    },
    "submissionId": "sub_01HXYFORM_001"
  },
  "timestamp": "2026-05-25T11:22:10Z"
}

Validation Rules