Form Submissions API

SmartForm exposes a developer-first API for posting submissions to forms you own. Each request is authenticated with your personal API key so that externally created submissions 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 Form Submission 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 form. Requests with missing or invalid credentials return 401 Unauthorized.

Quick Start

Submit a response to an existing survey:

curl --request POST \
  --url https://smartform.dev/api/v1/forms/YOUR_SURVEY_ID/submissions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": [
      { "questionId": "question_1", "value": "Very satisfied" },
      { "questionId": "question_2", "value": "user@example.com" }
    ]
  }'

Submit responses

POST /forms/{formId}/submissions

Send batched answers for a survey or form you own. The formId matches the SmartForm survey ID and can be copied from the URL inside the builder.

Request Body

{
  "submittedAt": "2024-04-05T16:03:12.000Z",
  "fields": [
    {
      "questionId": "clwxyz12ab34",
      "value": "Very satisfied"
    },
    {
      "questionId": "clwxyz98zy76",
      "values": ["Fast onboarding", "Helpful support"]
    },
    {
      "questionId": "clwxyz77mn45",
      "value": 9
    }
  ],
  "context": {
    "pageUri": "https://example.com/signup",
    "pageName": "Sign up"
  }
}

Parameters

Submission Data

Note: Each field must have either value or values, but not both.

Field Types

• Single Value: Use value for text inputs, ratings, and single selections
• Multiple Values: Use values array for multi-select choice questions
• Data Types: Strings, numbers, and booleans are accepted; all values are stringified server-side

Validation Rules

• Answers cannot exceed 255 characters
• Question IDs must exist in the target survey
• Survey must be active (not archived)
• All required questions must have responses

Response

Success Response (200)

{
  "submissionId": "clx0abc123",
  "formId": "clwxyz12ab34",
  "receivedAt": "2024-04-05T16:03:13.205Z",
  "status": "accepted"
}

Error Responses

Common Issues:

• Question IDs must match exactly as defined in SmartForm
• Required questions cannot be omitted
• Choice questions may require values array instead of single value
• Timestamps must be valid ISO-8601 format

Code Examples

cURL

curl --request POST \
  --url https://smartform.dev/api/v1/forms/YOUR_SURVEY_ID/submissions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": [
      { "questionId": "question_1", "value": "Very satisfied" },
      { "questionId": "question_2", "value": "user@example.com" },
      { "questionId": "question_3", "values": ["Option A", "Option C"] }
    ],
    "submittedAt": "2024-04-05T16:03:12.000Z",
    "context": {
      "pageUri": "https://example.com/feedback",
      "pageName": "Product Feedback"
    }
  }'

JavaScript (Node.js)

const response = await fetch('https://smartform.dev/api/v1/forms/SURVEY_ID/submissions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: [
      { questionId: 'question_1', value: 'Excellent' },
      { questionId: 'question_2', value: 'user@example.com' },
    ],
    submittedAt: new Date().toISOString(),
  }),
});

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

Python

import requests
import json

url = "https://smartform.dev/api/v1/forms/YOUR_SURVEY_ID/submissions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "fields": [
        {"questionId": "question_1", "value": "Very satisfied"},
        {"questionId": "question_2", "value": "user@example.com"}
    ]
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(f"Submission ID: {result['submissionId']}")

Best Practices

Reliability

• Implement idempotent retries for network failures
• Use exponential backoff for rate limiting
• Validate survey IDs before sending submissions
• Store submissionId for tracking and debugging

Data Integrity

• Match question types correctly (single vs. multiple values)
• Respect field length limits (255 characters max)
• Include all required question responses
• Use consistent timestamp formats

Security

• Never expose API keys in client-side code
• Rotate keys regularly via SmartForm settings
• Use HTTPS for all API communications
• Validate data before submission

Integration

• Log submission IDs to correlate with internal events
• Handle different response formats for various question types
• Consider batching multiple submissions when possible
• Monitor API usage and error rates

---

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