Getting Started

Welcome to GhostForm! This guide will help you create your first form in minutes.

Quick Start

1. Sign up for a free account
2. Create a form using the Form Builder
3. Embed your form on your website
4. View submissions in your dashboard

Creating Your First Form

After signing up, click "Create a form" to open the Form Builder.

1. Enter a form name (e.g., "Contact Form")
2. Add fields by clicking "Add Field"
3. Configure each field (label, type, validation)
4. Set form settings (success message, redirect URL)
5. Click "Save Form"

Form Settings

• Form Name: Display name for your form
• Slug: URL-friendly identifier (auto-generated from name)
• Success Message: Message shown after successful submission
• Redirect URL: Optional URL to redirect after submission
• Rate Limit: Maximum submissions per hour per IP
• Form Enabled: Toggle to enable/disable form submissions

Form Builder

The Form Builder lets you create forms with various field types and validation rules.

Field Types

Field Configuration

Each field can be configured with:

• Label: Display name for the field
• Placeholder: Hint text shown in empty fields
• Required: Make the field mandatory
• Default Value: Pre-filled value
• Description: Help text shown below the field
• Validation: Min/max length, number ranges, etc.
• Error Message: Custom error message for validation failures

Validation Rules

Text/Email/Textarea:
  - minLength: Minimum character count
  - maxLength: Maximum character count

Number:
  - min: Minimum numeric value
  - max: Maximum numeric value

Email:
  - Automatic email format validation

Embedding Forms

GhostForm offers multiple ways to embed your forms on any website.

Method 1: iframe Embed (Recommended)

The simplest way to embed a form. Just copy and paste one line of code.

<iframe 
  src="https://yourdomain.com/form/your-form-slug" 
  width="100%" 
  height="600" 
  frameborder="0" 
  style="border: none; border-radius: 16px;"
></iframe>

Pros: Simple, works without JavaScript, isolated styling

Cons: Fixed height, less styling control

Method 2: Full HTML Embed

Copy the complete HTML form code with all styles included.

1. Go to "My Forms"
2. Click the "Embed" button next to your form
3. Select "Full HTML Embed"
4. Copy the HTML code
5. Paste it into your website's HTML

Pros: Full control, matches GhostForm styling, no external dependencies

Cons: Longer code to paste

Method 3: Direct Link

Share a direct link to your form or use it in your own HTML.

<a href="https://yourdomain.com/form/your-form-slug">
  Fill out our form
</a>

Getting Embed Code

1. Navigate to "My Forms"
2. Find your form
3. Click the "Embed" button (clipboard icon)
4. Choose your preferred embed method
5. Click "Copy" to copy the code

API Reference

GhostForm provides a RESTful API for programmatic form management.

Authentication

Most API endpoints require authentication via session cookies. Log in through the web interface to obtain a session.

Form Management

List All Forms

GET /api/forms

Response: Array of form objects
[
  {
    "id": "uuid",
    "name": "Contact Form",
    "slug": "contact-form",
    "fields": [...],
    "settings": {...},
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
]

Get Form by ID

GET /api/forms/by-id/{id}

Response: Form object

Get Form by Slug (Public)

GET /api/forms/{slug}

Response: Form object (no authentication required)

Create Form

POST /api/forms
Content-Type: application/json

{
  "name": "Contact Form",
  "slug": "contact-form",
  "fields": [
    {
      "id": "name",
      "type": "text",
      "label": "Name",
      "required": true
    },
    {
      "id": "email",
      "type": "email",
      "label": "Email",
      "required": true
    }
  ],
  "settings": {
    "successMessage": "Thank you!",
    "redirectUrl": "https://example.com/thanks",
    "rateLimit": 10,
    "enabled": true
  }
}

Response: Created form object

Update Form

PUT /api/forms/by-id/{id}
Content-Type: application/json

{
  "name": "Updated Form Name",
  "slug": "updated-slug",
  "fields": [...],
  "settings": {...}
}

Response: Updated form object

Delete Form

DELETE /api/forms/by-id/{id}

Response: {
  "success": true,
  "message": "Form deleted successfully"
}

Submissions

Get Submissions

GET /api/submissions/{slug}

Response: Array of submission objects
[
  {
    "id": "uuid",
    "formId": "uuid",
    "formSlug": "contact-form",
    "data": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

Submit to Form

POST /api/submit/{slug}
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Response: {
  "success": true,
  "message": "Thank you for your submission!",
  "redirectUrl": "https://example.com/thanks"
}

Error Responses

All endpoints return standard HTTP status codes:

• 200: Success
• 201: Created
• 400: Bad Request (validation errors)
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too Many Requests (rate limit exceeded)

Rate Limiting

Protect your forms from spam and abuse with configurable rate limits.

How It Works

Rate limiting tracks submissions per IP address. Each IP can submit a form a limited number of times per hour.

Configuration

1. Open your form in the Form Builder
2. In "Form Settings", find "Rate Limit"
3. Enter the maximum number of submissions per hour (e.g., 10)
4. Save your form

Rate Limit Behavior

• Limits are enforced per IP address
• Time window is 1 hour (rolling window)
• When exceeded, returns 429 Too Many Requests
• Error message includes retry information

Example

If you set a rate limit of 10 submissions per hour:

• IP 1.2.3.4 can submit 10 times in an hour
• IP 5.6.7.8 can also submit 10 times (separate limit)
• After 1 hour, the count resets for each IP

Privacy Note

IP addresses are stored only for rate limiting purposes and are not used for tracking or analytics. This is a legitimate security measure to prevent abuse.

Examples

Common use cases and code examples.

Contact Form

Fields:
- Name (text, required)
- Email (email, required)
- Message (textarea, required)

Settings:
- Success Message: "Thanks for contacting us!"
- Redirect URL: "/thank-you"

Newsletter Signup

Fields:
- Email (email, required)

Settings:
- Success Message: "You're subscribed!"
- Rate Limit: 5 (prevent spam)

Survey Form

Fields:
- Name (text, required)
- Age (number, min: 18, max: 100)
- Favorite Color (select: Red, Blue, Green)
- Subscribe (checkbox)
- Feedback (textarea)

Settings:
- Success Message: "Survey submitted!"

Programmatic Form Creation

// Using fetch API
const response = await fetch('/api/forms', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include', // Include cookies
  body: JSON.stringify({
    name: 'My Form',
    slug: 'my-form',
    fields: [
      {
        id: 'email',
        type: 'email',
        label: 'Email',
        required: true
      }
    ],
    settings: {
      successMessage: 'Thank you!',
      enabled: true
    }
  })
})

const form = await response.json()