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 responses via API

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
  • 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",
    "slug": "contact-form-abc123",
    "folder_id": null,
    "data": {
      "submit_text": "Submit"
    },
    "email_notifications_enabled": true,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "form_fields": [],
    "sessions_count": 0,
    "completed_sessions_count": 0
  }
}

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

Query Parameters

  • search (optional, string, max 255) - Search forms by name
  • folder_id (optional, integer or null) - Filter by folder
  • sort (optional, string) - Sort field (name, created_at, updated_at)
  • direction (optional, string) - Sort direction (asc or desc)
  • per_page (optional, integer, 1-100) - Items per page (default: 15)

Example: List Forms

curl -X GET "https://forms.formrobin.com/api/v1/forms?search=contact&sort=created_at&direction=desc&per_page=25" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 123,
      "name": "Contact Form",
      "slug": "contact-form-abc123",
      ...
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 42,
    "per_page": 25
  },
  "links": {
    "next": "https://forms.formrobin.com/api/v1/forms?page=2",
    "prev": null
  }
}

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 detailed form information including fields, session counts, and folder details.

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 responses.

Getting Form Responses

Endpoint

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

Example

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

Returns paginated list of form submissions with response data.

Understanding Form Slugs

When you create a form, FormRobin automatically generates a unique slug based on the form name. The slug is used in the form's public URL:

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

For example, "Contact Form" might become 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: Don't retrieve all forms at once if you have many
  • 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

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. Use GET /api/v1/folders  to list your folders. 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 responses when I delete a form?

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

Q: Can I export responses via API?

A: Yes. Use GET /api/v1/forms/{id}/responses  to retrieve response data in JSON format. For CSV export, use the web dashboard.


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

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles