Form Submission API

Submit form data with contact information, consent management, and custom fields.

Endpoint

POST /api/v1/forms/accept-submission

Authentication

Requires bearer token authentication. See Authentication.

Request Format

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

{
  // Required: Form identifier
  form_id: string;

  // Optional: Unique submission identifier (for idempotency)
  submission_id?: string;

  // Contact Information
  email?: string;
  phone?: string;
  first_name?: string;
  last_name?: string;

  // Address
  street?: string;
  city?: string;
  state?: string;
  zip?: string;
  country?: string;

  // Consent Management (at least one consent required)
  consent_to_primary_purpose?: boolean;
  consent_to_primary_purpose_deadline_date?: string;     // ISO 8601 format
  consent_to_primary_purpose_deadline_interval?: string; // e.g., "30d", "1y"

  consent_to_general_contact_email?: boolean;
  consent_to_general_contact_phone?: boolean;
  consent_to_general_contact_deadline_date?: string;
  consent_to_general_contact_deadline_interval?: string;

  // Custom Fields
  [key: string]: any;
}

Consent Deadlines

Consent deadlines can be specified in two formats:

ISO 8601 Date

{
  "consent_to_primary_purpose_deadline_date": "2026-12-31T23:59:59Z"
}

Time Interval

{
  "consent_to_primary_purpose_deadline_interval": "1y"
}

Supported intervals: 30d, 90d, 1y, 2y, etc. Uses the ms library format.

Both Formats

If both are provided, the earlier deadline is used:

{
  "consent_to_primary_purpose_deadline_date": "2027-12-31T23:59:59Z",
  "consent_to_primary_purpose_deadline_interval": "6M"
}

Response Format

Success Response

{
  "success": true,
  "message": "Form submission accepted"
}

HTTP Status: 200 OK

Error Response

{
  "error": "ValidationError",
  "message": "Validation failed",
  "code": "form_id_missing"
}

HTTP Status: 400 Bad Request

Error Codes

Code	Description
form_id_missing	The form_id field is required
submission_id_invalid	Invalid format for submission_id
consent_missing	At least one consent must be provided
consent_to_primary_purpose_missing	Primary purpose consent required when other fields are present
consent_to_primary_purpose_invalid	Invalid value for primary purpose consent
consent_to_primary_purpose_declined	Primary purpose consent was declined
consent_to_primary_purpose_deadline_missing	Deadline required for primary purpose consent
consent_to_primary_purpose_deadline_invalid	Invalid deadline format
consent_to_general_contact_phone_missing	Phone number required when phone consent is granted
consent_to_general_contact_phone_invalid	Invalid phone number format
consent_to_general_contact_email_missing	Email required when email consent is granted
consent_to_general_contact_email_invalid	Invalid email format
consent_to_general_contact_deadline_invalid	Invalid deadline format for general contact consent

Examples

Newsletter Signup

curl -X POST https://api.statelessapp.com/api/v1/forms/accept-submission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "newsletter-signup",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "consent_to_general_contact_email": true,
    "consent_to_general_contact_deadline_interval": "1y"
  }'

Event Registration

curl -X POST https://api.statelessapp.com/api/v1/forms/accept-submission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "event-registration",
    "email": "attendee@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+15551234567",
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US",
    "consent_to_primary_purpose": true,
    "consent_to_primary_purpose_deadline_date": "2026-12-31T23:59:59Z",
    "event_preferences": "vegetarian",
    "attendance_confirmed": true
  }'

Petition Signature

curl -X POST https://api.statelessapp.com/api/v1/forms/accept-submission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "climate-petition",
    "submission_id": "unique-submission-123",
    "email": "activist@example.com",
    "first_name": "Alex",
    "last_name": "Johnson",
    "consent_to_primary_purpose": true,
    "consent_to_primary_purpose_deadline_interval": "2y",
    "consent_to_general_contact_email": true,
    "consent_to_general_contact_deadline_interval": "1y",
    "street": "456 Oak Ave",
    "city": "Portland",
    "state": "OR",
    "zip": "97201",
    "country": "US",
    "comment": "We need urgent climate action!"
  }'

Use Cases

• Newsletter Signups: Collect email addresses with consent for marketing communications
• Event Registrations: Gather attendee information with custom fields
• Volunteer Recruitment: Capture contact details and availability preferences
• Petition Signatures: Collect signatures with optional comments and demographic data
• Survey Responses: Store survey answers with respondent contact information

Notes

• At least one consent field must be set to true
• Custom fields can be added beyond the standard fields
• The submission_id field enables idempotent submissions (resubmitting with the same ID won't create duplicates)
• Consent deadlines are stored and enforced by the system
• Phone numbers should be in E.164 format (e.g., +15551234567)