Creating Forms via API

Learn how to create, update, and manage forms programmatically using the FormRobin API for automated form generation and management.

Overview

The FormRobin API allows you to programmatically:

  • Create new forms with custom settings
  • List all your forms with pagination
  • Retrieve specific form details
  • Update existing forms
  • Delete forms
  • Get form sessions (submissions) via API

You can access API settings from Settings > API in your FormRobin account:

FormRobin API Settings page showing Developer API and Personal Access Tokens sections

Prerequisites: You must be authenticated with a valid JWT token. See the API Authentication Guide.

Creating a New Form

Endpoint

POST https://forms.formrobin.com/api/v1/forms

Request Format

Headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Accept: application/json

Body (JSON):

{
  "name": "Contact Form",
  "folder_id": null,
  "data": {
    "submit_text": "Submit"
  },
  "email_notifications_enabled": true
}

Request Parameters

  • name (required, string, max 255 chars) - The form name
  • folder_id (optional, integer or null) - ID of folder to place form in. The folder must belong to your account.
  • data (optional, object) - Form configuration:
    • submit_text (optional, string, max 255 chars) - Submit button text (default: "Submit")
  • email_notifications_enabled (optional, boolean) - Enable email notifications (default: true)

Success Response

Status: 201 Created

Body:

{
  "data": {
    "id": 123,
    "name": "Contact Form",
    "folder_id": null,
    "email_notifications_enabled": true,
    "url": "https://formrobin.com/f/contact-form-abc123",
    "redirect_url": null,
    "webhook_url": null,
    "created_at": "2025-01-15T10:30:00.000000Z",
    "updated_at": "2025-01-15T10:30:00.000000Z"
  }
}

Note: The response includes a url field containing the full public URL for the form (e.g., https://formrobin.com/f/your-form-slug). The API does not return a separate slug field.

Example: Creating a Form

curl -X POST https://forms.formrobin.com/api/v1/forms \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Signup",
    "data": {
      "submit_text": "Subscribe"
    },
    "email_notifications_enabled": true
  }'

Listing All Forms

Endpoint

GET https://forms.formrobin.com/api/v1/forms

Description

Returns all your forms ordered by most recently created, paginated at 100 forms per page. This endpoint does not accept any query parameters for filtering, sorting, or searching.

Example: List Forms

curl -X GET "https://forms.formrobin.com/api/v1/forms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 123,
      "name": "Contact Form",
      "folder_id": null,
      "email_notifications_enabled": true,
      "url": "https://formrobin.com/f/contact-form-abc123",
      "redirect_url": null,
      "webhook_url": null,
      "created_at": "2025-01-15T10:30:00.000000Z",
      "updated_at": "2025-01-15T10:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://forms.formrobin.com/api/v1/forms?page=1",
    "last": "https://forms.formrobin.com/api/v1/forms?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://forms.formrobin.com/api/v1/forms",
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}

Note: Pagination uses 100 items per page. If you have more than 100 forms, use the next link or append ?page=2 to fetch subsequent pages.

Getting a Specific Form

Endpoint

GET https://forms.formrobin.com/api/v1/forms/{id}

Example

curl -X GET https://forms.formrobin.com/api/v1/forms/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

Returns the same form object structure as listed above, including the form's url, redirect_url, webhook_url, and timestamps.

Updating a Form

Endpoint

PUT https://forms.formrobin.com/api/v1/forms/{id}

Request Format

Body (JSON):

{
  "name": "Updated Contact Form",
  "data": {
    "submit_text": "Send Message"
  },
  "email_notifications_enabled": false
}

Request Parameters

All parameters are optional (you only need to include fields you want to update):

  • name (optional, string, max 255 chars)
  • folder_id (optional, integer or null)
  • data (optional, object)
  • email_notifications_enabled (optional, boolean)

Example: Update Form Name

curl -X PUT https://forms.formrobin.com/api/v1/forms/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Us - Updated"
  }'

Deleting a Form

Endpoint

DELETE https://forms.formrobin.com/api/v1/forms/{id}

Example

curl -X DELETE https://forms.formrobin.com/api/v1/forms/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

Status: 204 No Content (empty response body)

Note: Deleting a form permanently removes it and all associated sessions (submissions).

Getting Form Sessions

Endpoint

GET https://forms.formrobin.com/api/v1/forms/{id}/sessions

Query Parameters

  • completed (optional, boolean) - When true, returns only completed sessions ordered by completion date. When false or omitted, returns all sessions ordered by most recent.

Example: Get All Sessions

curl -X GET "https://forms.formrobin.com/api/v1/forms/123/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example: Get Completed Sessions Only

curl -X GET "https://forms.formrobin.com/api/v1/forms/123/sessions?completed=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 456,
      "form_id": 123,
      "form_field_responses": [
        {
          "id": 789,
          "form_session_id": 456,
          "form_field_id": 10,
          "form_field_label": "Email Address",
          "value": "user@example.com"
        }
      ],
      "completed_at": "2025-01-15T10:35:00.000000Z",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null,
      "referrer_url": null,
      "landing_page_url": null,
      "device_type": "desktop",
      "browser_name": "Chrome",
      "browser_version": "120.0",
      "operating_system": "Windows",
      "ip_address": "192.168.1.1",
      "created_at": "2025-01-15T10:30:00.000000Z",
      "updated_at": "2025-01-15T10:35:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": {
    "current_page": 1,
    "per_page": 100,
    "total": 42
  }
}

Each session includes full form_field_responses with the field label and submitted value, plus UTM tracking data, device information, and timestamps. Sessions are paginated at 100 per page.

Understanding Form URLs

When you create a form, FormRobin automatically generates a unique slug based on the form name. The API returns the full public URL in the url field:

https://formrobin.com/f/{slug}

For example, a form named "Contact Form" might have the URL https://formrobin.com/f/contact-form-abc123.

Best Practices

  • Validate input: Check for required fields before making requests
  • Handle errors: Always check status codes and error messages
  • Store form IDs: Save the returned form ID for future updates
  • Use pagination: Use the next link or ?page=N parameter to page through results (100 per page)
  • Folder organization: Use folders to organize forms created via API
  • Descriptive names: Use clear, meaningful form names

Limitations

  • Form fields: The API creates empty forms. You must add fields manually in the UI or via future API updates
  • No bulk operations: Must create/update forms one at a time
  • Ownership: Can only manage your own forms
  • No template support: Cannot create forms from templates via API
  • Slug generation: Slugs are auto-generated and cannot be customized
  • No filtering or sorting: The list endpoint returns all forms ordered by newest first, with no query parameters for search or sort

Common Error Responses

400 Bad Request - Invalid JSON or missing required fields

{
  "message": "Validation failed",
  "errors": {
    "name": ["The name field is required."]
  }
}

401 Unauthorized - Invalid or expired token

{
  "message": "Unauthenticated."
}

404 Not Found - Form doesn't exist or doesn't belong to you

{
  "message": "Form not found."
}

422 Unprocessable Entity - Validation error

{
  "message": "The given data was invalid.",
  "errors": {
    "folder_id": ["The selected folder is invalid."]
  }
}

Troubleshooting

Issue: "The name field is required" error.

Fix: Ensure your request includes the name field in the JSON body. The name is the only required field when creating a form.

Issue: "The selected folder is invalid" error.

Fix: Verify the folder_id exists and belongs to your account. Check your folders in the dashboard to find the correct ID. Set folder_id to null if you don't want to assign a folder.

Issue: Form created but has no fields.

Fix: The API creates empty forms. After creating a form via API, you must add fields manually in the FormRobin dashboard. Future API versions may support field creation.

Issue: Cannot delete a form (403 Forbidden).

Fix: Ensure the form belongs to your account. You can only delete forms you own. Check that you're using the correct form ID.

FAQ

Q: Can I create form fields via the API?

A: Not currently. The API creates empty forms. You must add fields manually in the UI after creating the form programmatically.

Q: Can I duplicate a form via API?

A: No. To duplicate a form, get the form details via GET /api/v1/forms/{id}, then create a new form with the same settings. Note that fields won't be copied.

Q: What happens to sessions when I delete a form?

A: All form sessions are permanently deleted along with the form. This action cannot be undone.

Q: Can I retrieve sessions via API?

A: Yes. Use GET /api/v1/forms/{id}/sessions to retrieve session data in JSON format, including all field responses, UTM tracking, and device information. For CSV export, use the web dashboard.


Need help with the Forms API? Contact our support team - we're here to help!

Related Articles