Forms API

The Forms API enables SDK consumers to submit form data and trigger email notifications to configured recipients. Use it for contact forms, lead capture, feedback, and any scenario where form data needs to be emailed.

Overview

Form email notifications must be configured in the dashboard before use:

1. Navigate to SDK Settings > Forms tab
2. Enable form email notifications
3. Add recipient email addresses
4. Optionally customize the from name, subject template, reply-to, and email template

User submits form
       ↓
POST /api/sdk/forms/submit
       ↓
  ┌─────────────────────┐
  │  Validate API Key   │
  └─────────────────────┘
       ↓
  ┌─────────────────────┐
  │  Check config       │ ← formEmailConfig.enabled?
  └─────────────────────┘
       ↓
  ┌─────────────────────┐
  │  Generate email     │ ← Uses configured template
  └─────────────────────┘
       ↓
  ┌─────────────────────┐
  │  Send via SendGrid  │ → Recipients from config
  └─────────────────────┘
       ↓
  ┌─────────────────────┐
  │  Track submission   │ → FormSubmission analytics
  └─────────────────────┘

Submit Form

POST /api/sdk/forms/submit

Submit form data and send an email notification to the configured recipients.

Request Body:

{
  // Optional - Form identification
  formName?: string;              // Display name (default: "Form Submission")
  formId?: string;                // Unique form identifier for analytics

  // Required - Form data
  fields: Record<string, any>;    // Key-value pairs of form fields (must be non-empty)

  // Optional - Context
  pageUrl?: string;               // URL where form was submitted
  metadata?: {                    // Additional metadata
    pageTitle?: string;
    sessionId?: string;
    [key: string]: any;
  };
}

Response:

{
  "success": true
}

Example:

curl -X POST https://app.fig1.ai/api/sdk/forms/submit \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_your_api_key" \
  -d '{
    "formName": "Contact Form",
    "formId": "contact-main",
    "fields": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "subject": "Partnership Inquiry",
      "message": "I am interested in discussing a potential partnership."
    },
    "pageUrl": "https://example.com/contact",
    "metadata": {
      "pageTitle": "Contact Us"
    }
  }'

Dashboard Configuration

Form email settings are managed in the dashboard under SDK Settings > Forms.

Configuration Fields

Email Templates

Framework Examples

React / Next.js

async function submitForm(formData: Record<string, string>) {
  const response = await fetch('https://app.fig1.ai/api/sdk/forms/submit', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Fig1-API-Key': process.env.NEXT_PUBLIC_FIG1_API_KEY!,
    },
    body: JSON.stringify({
      formName: 'Contact Form',
      formId: 'contact-main',
      fields: formData,
      pageUrl: window.location.href,
      metadata: { pageTitle: document.title },
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Form submission failed');
  }

  return response.json();
}

React Native

async function submitForm(fields: Record<string, string>) {
  const response = await fetch('https://app.fig1.ai/api/sdk/forms/submit', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Fig1-API-Key': Config.FIG1_API_KEY,
    },
    body: JSON.stringify({
      formName: 'Feedback Form',
      formId: 'feedback-app',
      fields,
      metadata: { platform: 'ios' },
    }),
  });

  const data = await response.json();
  if (!response.ok) {
    Alert.alert('Error', data.error || 'Submission failed');
    return;
  }

  Alert.alert('Success', 'Your form has been submitted!');
}

Flutter / Dart

Future<void> submitForm(Map<String, String> fields) async {
  final response = await http.post(
    Uri.parse('https://app.fig1.ai/api/sdk/forms/submit'),
    headers: {
      'Content-Type': 'application/json',
      'X-Fig1-API-Key': fig1ApiKey,
    },
    body: jsonEncode({
      'formName': 'Contact Form',
      'formId': 'contact-main',
      'fields': fields,
    }),
  );

  if (response.statusCode != 200) {
    final error = jsonDecode(response.body);
    throw Exception(error['error'] ?? 'Form submission failed');
  }
}

Error Responses

Missing API Key (401)

{
  "error": "API key is required"
}

Form Emails Not Enabled (403)

{
  "error": "Form email notifications are not enabled for this site"
}

Empty Fields (400)

{
  "error": "fields is required and must be a non-empty object"
}

No Recipients Configured (400)

{
  "error": "No recipient email addresses configured"
}

SendGrid Failure (500)

{
  "error": "Failed to send email notification"
}

Analytics

Each successful submission creates a FormSubmission analytics record containing:

Best Practices

1. Use Form IDs for Analytics

Always provide a formId to distinguish different forms:

{ formId: "contact-main", formName: "Contact Form" }
{ formId: "newsletter-signup", formName: "Newsletter" }
{ formId: "feedback-product", formName: "Product Feedback" }

2. Include Page Context

Pass pageUrl and metadata.pageTitle so recipients know where submissions came from:

{
  pageUrl: window.location.href,
  metadata: { pageTitle: document.title }
}

3. Validate Client-Side First

Validate form fields in your app before submitting to avoid unnecessary API calls:

if (!fields.email || !fields.message) {
  showError("Please fill in all required fields");
  return;
}

4. Handle Errors Gracefully

const response = await fetch('/api/sdk/forms/submit', { ... });
const data = await response.json();

if (!response.ok) {
  console.error('Form submission failed:', data.error);
  // Show user-friendly message
}