Skip to main content
GET
/
api
/
v1
/
forms
/
{formId}
Get Form
curl --request GET \
  --url https://api.example.com/api/v1/forms/{formId}
{
  "id": "<string>",
  "name": "<string>",
  "title": "<string>",
  "description": "<string>",
  "formType": "<string>",
  "formTypeDisplay": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "submissionCount": 123,
  "fields": [
    {
      "id": "<string>",
      "name": "<string>",
      "label": "<string>",
      "type": "<string>",
      "required": true,
      "placeholder": "<string>",
      "options": [
        {}
      ],
      "products": [
        {}
      ],
      "displayMode": "<string>",
      "productIds": [
        {}
      ]
    }
  ],
  "emailSettings": {
    "enabled": true,
    "developerNotificationsEnabled": true
  },
  "usersJoinedSettings": {
    "enabled": true,
    "count": 123
  },
  "formTypeSpecific": {},
  "error": "<string>"
}

​
Authentication

This endpoint requires API key authentication. Provide your API key in one of two ways:
  • Recommended: X-API-Key header
  • Fallback: apiKey query parameter

​
Path Parameters

​
formId
string
required
The unique identifier of the form to retrieve

​
Query Parameters

​
apiKey
string
API key for authentication (fallback method). Prefer using the X-API-Key header instead.

​
Response

​
id
string
Unique identifier for the form
​
name
string
Name of the form
​
title
string
Display title of the form (same as name)
​
description
string
Description of the form
​
formType
string
Type of form in lowercase (e.g., “survey”, “contact”, “feedback”, “order”, “rsvp”, “waitlist”, “application”, “custom”, “analytics_opt_in”)
​
formTypeDisplay
string
Human-readable form type display name (e.g., “Survey”, “Contact”, “Feedback”)
​
createdAt
string
ISO 8601 timestamp when the form was created
​
updatedAt
string
ISO 8601 timestamp when the form was last updated
​
submissionCount
number
Total number of submissions received for this form
​
fields
array
Array of form field definitions
​
emailSettings
object
Email notification configuration
​
usersJoinedSettings
object
Settings for tracking users who have joined (if enabled)
​
formTypeSpecific
object
Form type-specific configuration based on the form type

​
Rate Limiting

This endpoint is rate-limited per API key and form ID. Rate limit information is returned in the response headers:
  • X-RateLimit-Limit: Maximum number of requests allowed
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

​
Error Responses

​
error
string
Error message describing what went wrong

​
Status Codes

  • 400 - Bad Request: Invalid parameters
  • 401 - Unauthorized: Invalid or inactive API key
  • 404 - Not Found: Form not found or user not found
  • 429 - Too Many Requests: Rate limit exceeded
  • 500 - Internal Server Error
curl -X GET "https://api.mantlz.app/api/v1/forms/clx1234567890abcdef" \
  -H "X-API-Key: your_api_key_here"

​
Example Response

{
  "id": "clx1234567890abcdef",
  "name": "Product Feedback Survey",
  "title": "Product Feedback Survey",
  "description": "Collect user feedback on our products",
  "formType": "feedback",
  "formTypeDisplay": "Feedback",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-03-01T14:22:00.000Z",
  "submissionCount": 42,
  "fields": [
    {
      "id": "email",
      "name": "email",
      "label": "Email Address",
      "type": "email",
      "required": true,
      "placeholder": "[email protected]"
    },
    {
      "id": "rating",
      "name": "rating",
      "label": "How would you rate our product?",
      "type": "select",
      "required": true,
      "placeholder": "Select a rating",
      "options": ["1 - Poor", "2 - Fair", "3 - Good", "4 - Very Good", "5 - Excellent"]
    },
    {
      "id": "comments",
      "name": "comments",
      "label": "Additional Comments",
      "type": "textarea",
      "required": false,
      "placeholder": "Share your thoughts..."
    }
  ],
  "emailSettings": {
    "enabled": true,
    "developerNotificationsEnabled": false
  },
  "usersJoinedSettings": null,
  "formTypeSpecific": {
    "supportsRating": true
  }
}

​
Notes

  • You can only retrieve forms that belong to the user associated with your API key
  • The fields array is parsed from the form’s JSON schema
  • The formTypeSpecific object contains different properties depending on the formType
  • Email settings functionality requires STANDARD or PRO plan
  • Developer notifications require PRO plan

Build docs developers (and LLMs) love

Get started for freeTalk to us