Installation

Welcome to Form Platform! This guide will help you create your first form and start collecting responses.

Prerequisites

Before you begin, you'll need:

• An account on Form Platform (sign up at app.formr.dev)

• A web browser (for the dashboard)

• Basic knowledge of HTML/JavaScript (for integration)

Step 1: Sign Up and Log In

1. Visit app.formr.dev

2. Click Sign Up and create your account

3. Verify your email address

4. Log in to the dashboard

Step 2: Create Your First Form

Using the Dashboard

1. Navigate to Forms

   • Click Forms in the sidebar

   • Click Create Form

2. Define Your Form

   • Enter a form title (e.g., "Contact Form")

   • Select an environment (start with "development")

   • Add fields using the form builder

3. Add Fields

   • Click Add Field

   • Choose field type (text, email, textarea, etc.)

   • Set label and validation rules

   • Mark required fields

4. Save Your Form

   • Click Save to create the form

   • Your form will be in "draft" status

5. Make It Live

   • Change status to "live" to make it publicly accessible

   • Copy the form ID for use in integrations

Example: Simple Contact Form

Here's what a basic contact form looks like:

{
  "id": "contact-form",
  "title": "Contact Us",
  "status": "live",
  "environment": "development",
  "fields": [
    {
      "id": "name",
      "type": "text",
      "label": "Your Name",
      "required": true
    },
    {
      "id": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "pii": true
    },
    {
      "id": "message",
      "type": "textarea",
      "label": "Message",
      "required": true
    }
  ]
}

Step 3: Get Your API Keys

Publishable Keys (Public Forms)

Publishable keys allow public form submissions:

1. Navigate to Settings > API Keys

2. Select your environment (e.g., "development")

3. Click Create Publishable Key

4. Copy the key (format: pk-live-...)

5. Use this key in your frontend code

Note: Publishable keys are safe to use in client-side code.

Secret Keys (Server-Side)

Secret keys are for authenticated API access:

1. Navigate to Settings > API Keys

2. Select your environment

3. Click Create Secret Key

4. Copy the key immediately (format: sk_live_...)

5. Store it securely - you cannot retrieve it later

Important: Never commit secret keys to version control. Use environment variables.

Step 4: Integrate Your Form

Option 1: Embed with HTML (Easiest)

Add a simple script to any HTML page:

<form method="post" action="https://api.formr.dev/submit" data-formr="contact-form">
  <input name="name" type="text" placeholder="Your Name" required />
  <input name="email" type="email" placeholder="Email" required />
  <textarea name="message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>

<script async src="https://cdn.formr.dev/v1/browser.min.js"></script>

Option 2: Use the SDK

Install the SDK:

npm install formr

Submit a form:

import { Formr } from 'formr';

const formr = new Formr();

// Submit form
await formr.forms.submit('contact-form', {
  name: 'John Doe',
  email: '[e-mail]',
  message: 'Hello!'
});

Option 3: Use React Components

Install the React components:

npm install formr-ui

Use in your React app:

import { useFormr, Form, Field, Errors } from 'formr-ui';

export default function ContactForm() {
  const { submit, errors, pending } = useFormr({
    formId: 'contact-form',
  });

  return (
    <Form onSubmit={submit}>
      <Field name="name" type="text" label="Name" required />
      {errors.name && <Errors field="name" />}
      
      <Field name="email" type="email" label="Email" required />
      {errors.email && <Errors field="email" />}
      
      <Field name="message" type="textarea" label="Message" required />
      
      <button disabled={pending}>
        {pending ? 'Sending...' : 'Send'}
      </button>
    </Form>
  );
}

Option 4: Use the REST API

Submit via API:

curl -X POST https://api.formr.dev/forms/contact-form/submit \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "name": "John Doe",
      "email": "[e-mail]",
      "message": "Hello!"
    }
  }'

Step 5: View Responses

In the Dashboard

1. Navigate to Responses

2. Select your form from the dropdown

3. View all submissions in a table

4. Click a response to see details

5. Export data as CSV or JSON

Via API

const formr = new Formr({ apiKey: process.env.FORMR_KEY });

// List responses
const { items } = await formr.responses.list({
  formId: 'contact-form'
});

// Get specific response
const response = await formr.responses.get('rsp_123');

Step 6: Set Up Webhooks (Optional)

Get real-time notifications when forms are submitted:

1. Navigate to Webhooks

2. Click Create Webhook

3. Enter your endpoint URL

4. Select events (e.g., response.created)

5. Save and test

Your endpoint will receive POST requests with form submission data.

Next Steps

Now that you have your first form working, explore more features:

• Dashboard Guide - Learn all dashboard features

• API Reference - Explore the full API

• SDK Guide - Deep dive into the SDK

• React Components - Build with React

• Webhooks - Set up real-time notifications

• Analytics - Track form performance

• Security - Learn about security features

Common Tasks

Change Form Status

• Draft: Form is being edited, not accessible

• Live: Form is publicly accessible

• Archived: Form is no longer active

Switch Environments

Use the environment selector in the dashboard to switch between:

• Development (for testing)

• Production (for live forms)

Export Data

1. Go to Responses

2. Select your form

3. Click Export

4. Choose format (CSV or JSON)

5. Download the file

Troubleshooting

Form Not Submitting

• Check that the form status is "live"

• Verify the form ID is correct

• Check browser console for errors

• Ensure required fields are filled

API Key Issues

• Verify you're using the correct key type (publishable vs secret)

• Check that the key is for the correct environment

• Ensure the key hasn't been deleted

Responses Not Appearing

• Check the environment selector matches your form's environment

• Verify the form ID in your integration

• Check that submissions are successful (no errors)

Need Help?

• Documentation: Browse our documentation index

• API Reference: See API Reference

• Examples: Check our example projects

Next Steps

• Dashboard Guide - Master the dashboard

• API Reference - Explore all endpoints

• SDK Guide - Use the JavaScript SDK