Skip to main content
Create a new form programmatically by providing a source form as a template and defining the steps and components for the new form. The generated form inherits all styling, fonts, backgrounds, and layout settings from the source form.
You’ll need an API key to use this endpoint. See the API Keys documentation to create one.

​
How It Works

  1. You provide a source form ID — this form acts as a style template. The generated form inherits its fonts, colors, backgrounds, and component styles.
  2. You define the steps and components for the new form. Each step contains one or more components (inputs, dropdowns, scheduling widgets, etc.).
  3. The API creates the form, publishes it, and returns the form ID and URL.
The source form must belong to the same environment and must not be deleted. Component types that are not in the source form’s styles will automatically receive default styling.

​
Request

curl -X POST 'https://forms.withsurface.com/api/v1/environments/{environmentId}/forms/generate' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceFormId": "your-source-form-id",
    "name": "My Generated Form",
    "steps": [
      {
        "name": "Contact Info",
        "components": [
          {
            "type": "IdentityInfo",
            "content": {
              "fields": [
                { "type": "text", "name": "firstName", "label": "First Name", "required": true },
                { "type": "text", "name": "lastName", "label": "Last Name", "required": true },
                { "type": "email", "name": "emailAddress", "label": "Email", "required": true }
              ]
            }
          },
          {
            "type": "NextButton",
            "content": { "label": "Continue" }
          }
        ]
      },
      {
        "name": "Additional Details",
        "components": [
          {
            "type": "Dropdown",
            "content": {
              "question": "What is your role?",
              "options": ["Engineering", "Product", "Design", "Marketing", "Sales", "Other"]
            }
          },
          {
            "type": "NextButton",
            "content": { "label": "Submit" }
          }
        ]
      }
    ]
  }'

​
Body Parameters

​
sourceFormId
string
required
The ID of an existing form to use as a style template. The generated form inherits all visual settings (fonts, colors, backgrounds, component styles) from this form.
​
name
string
required
Display name for the generated form.
​
steps
array
required
Array of step objects (minimum 2). Each step represents a page/screen in the form.

​
Supported Component Types

​
Input Components

​
ShortInput
component
Single-line text input.
​
LongInput
component
Multi-line text area.
​
IdentityInfo
component
Collects identity fields (name, email, company, etc.). This component has a strict schema — only the fields array is accepted.

​
Selection Components

​
Dropdown
component
Dropdown select menu. Requires at least one option.
​
MultipleOptionsQuestion
component
Single or multi-select options question.

​
Scheduling Components

​
Scheduler
component
Embeds a calendar scheduling widget (supports Calendly, Cal.com, HubSpot, SavvyCal, RevenueHero, and more). Requires a calendar URL.
​
NextButton
component
Button to advance to the next step.

​
Display Components

​
Header
component
A text header displayed at the top of a step.
​
Disclaimer
component
A block of disclaimer or legal text.

​
Other Components

Additional component types are supported: EmailForm, FileUploader, GraphicOptions, PasswordInput, and more. These follow the same pattern — pass the type and relevant content fields.

​
Response

​
success
boolean
Whether the form was created successfully.
​
result
object

​
Example Response

200 - Success
{
  "success": true,
  "result": {
    "form": {
      "id": "cm5abc123def456",
      "url": "/s/cm5abc123def456"
    }
  }
}

​
Error Responses

{
  "message": "Invalid request body",
  "errors": [
    {
      "message": "CalendlyScreen requires a calendar URL (via 'dataUrl', 'url', or 'calendarUrl')",
      "path": ["steps", 0, "components", 1, "content"]
    }
  ]
}

​
Form with Scheduling

Create a lead capture form with a scheduler step: 
curl -X POST 'https://forms.withsurface.com/api/v1/environments/{environmentId}/forms/generate' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceFormId": "your-source-form-id",
    "name": "Demo Booking Form",
    "steps": [
      {
        "name": "Your Info",
        "components": [
          {
            "type": "IdentityInfo",
            "content": {
              "fields": [
                { "type": "text", "name": "firstName", "label": "First Name", "required": true },
                { "type": "text", "name": "lastName", "label": "Last Name", "required": true },
                { "type": "email", "name": "emailAddress", "label": "Work Email", "required": true },
                { "type": "text", "name": "companyName", "label": "Company", "required": true }
              ]
            }
          },
          {
            "type": "NextButton",
            "content": { "label": "Book a Demo" }
          }
        ]
      },
      {
        "name": "Schedule",
        "components": [
          {
            "type": "CalendlyScreen",
            "content": {
              "dataUrl": "https://calendly.com/your-team/30min",
              "message": "Pick a time that works for you"
            }
          }
        ]
      }
    ]
  }'