Survey Creation API

SmartForm exposes a developer-first API for creating surveys programmatically. Each request is authenticated with your personal API key so that externally created surveys stay traceable and secure.

Tip: Prerequisites

Generate your API key from Settings → Developer API access inside the SmartForm application. Each user receives a unique key and can rotate it at any time.

Base URL

https://smartform.dev/api/v1

All Survey Creation endpoints live under /api/v1. Replace https://smartform.dev with your workspace domain when self-hosting.

Authentication

Provide your API key in one of the supported headers:

• Authorization: Bearer <API_KEY> (recommended)
• X-API-Key: <API_KEY>

Keys are scoped to the user who owns the survey. Requests with missing or invalid credentials return 401 Unauthorized.

Quick Start

Here's a simple example to create your first survey:

curl --request POST \
  --url https://smartform.dev/api/v1/survey \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Customer Feedback",
    "questions": [
      {
        "title": "How satisfied are you?",
        "type": "RATE",
        "isRequired": true
      }
    ],
    "oneQuestionPerStep": true,
    "displayTitle": true,
    "accentColor": "#C7D2FE"
  }'

Create a survey

POST /survey

Create a new survey with questions, styling, and configuration.

Request Body

{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our service",
  "questions": [
    {
      "title": "How satisfied are you?",
      "type": "RATE",
      "isRequired": true,
      "fieldType": "USER_DEFINED"
    },
    {
      "title": "First Name",
      "type": "INPUT",
      "isRequired": true,
      "fieldType": "PROGRAMMATIC",
      "paramName": "first_name"
    }
  ],
  "oneQuestionPerStep": true,
  "displayTitle": true,
  "hideProgressBar": false,
  "accentColor": "#C7D2FE",
  "backgroundColor": "#E7E3DC",
  "formBackgroundColor": "#FFFFFF",
  "logoUrl": null,
  "logoPosition": "TOP_LEFT"
}

Parameters

Survey Configuration

Styling Options

Questions

Field Types

SmartForm supports two types of form fields to give you flexibility in how data is collected:

USER_DEFINED (Default)

Standard interactive fields where users provide their own answers through the survey interface.

PROGRAMMATIC

Fields that are automatically pre-filled from URL parameters when users access the survey. These fields are disabled in the UI to prevent user editing.

Example Usage:

• Create a survey with a programmatic field: paramName: "first_name"
• Share the survey URL: https://smartform.dev/survey/abc123?first_name=John
• The "First Name" field will be automatically filled with "John"

Parameter Naming:

• Use snake_case format (e.g., first_name, user_id)
• Avoid special characters
• Parameters are case-sensitive

Response

Success Response (200)

{
  "id": "clwxyz12ab34"
}

Use this id to construct the survey URL: https://smartform.dev/survey/{id}

Error Responses

Common 400 Errors:

• Survey title exceeds 100 characters
• Question title exceeds 500 characters
• Invalid question type
• Invalid logo position
• Malformed hex color codes

Code Examples

cURL

curl --request POST \
  --url https://smartform.dev/api/v1/survey \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Customer Feedback Survey",
    "description": "Help us improve our service",
    "questions": [
      {
        "title": "How satisfied are you?",
        "type": "RATE",
        "isRequired": true,
        "fieldType": "USER_DEFINED"
      },
      {
        "title": "Your Name",
        "type": "INPUT",
        "isRequired": true,
        "fieldType": "PROGRAMMATIC",
        "paramName": "user_name"
      }
    ],
    "oneQuestionPerStep": true,
    "displayTitle": true,
    "hideProgressBar": false,
    "accentColor": "#C7D2FE",
    "backgroundColor": "#E7E3DC",
    "formBackgroundColor": "#FFFFFF",
    "logoPosition": "TOP_LEFT"
  }'

JavaScript (Node.js)

const response = await fetch('https://smartform.dev/api/v1/survey', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Customer Feedback Survey',
    questions: [
      {
        title: 'How satisfied are you?',
        type: 'RATE',
        isRequired: true,
      },
    ],
    oneQuestionPerStep: true,
    displayTitle: true,
    accentColor: '#C7D2FE',
    backgroundColor: '#E7E3DC',
    formBackgroundColor: '#FFFFFF',
    logoPosition: 'TOP_LEFT',
  }),
});

const result = await response.json();
console.log('Survey created:', result.id);

Best Practices

Security

• Always use HTTPS for API calls
• Store API keys securely (never in client-side code)
• Rotate API keys regularly via SmartForm settings

Development

• Test programmatic fields by appending parameters to survey URLs
• Validate survey IDs before using them in production
• Handle API errors gracefully with appropriate retry logic

Integration

• Programmatic fields are automatically disabled in the survey UI
• Use meaningful parameter names that match your data schema
• Consider user privacy when pre-filling personal information

---

Need help? Contact support@smartform.dev for assistance.