NueForm

Forms API

Create, retrieve, update, delete, publish, and duplicate forms.

The Forms API lets you programmatically manage your NueForm forms. You can list, create, retrieve, update, delete, publish, unpublish, and duplicate forms.

All request and response bodies use snake_case field names.

Endpoints
GET/api/v1/formsPOST/api/v1/formsGET/api/v1/forms/:idPUT/api/v1/forms/:idDELETE/api/v1/forms/:idPOST/api/v1/forms/:id/publishDELETE/api/v1/forms/:id/publishPOST/api/v1/forms/:id/duplicate

List Forms

GET/api/v1/forms

Returns a paginated list of forms the authenticated user has access to, including personal forms and forms from teams the user belongs to.

Query Parameters

pageinteger

Page number (default: 1)

per_pageinteger

Results per page (default: 50)

searchstring

Filter forms by title (case-insensitive partial match)

team_idstring

Only return forms belonging to this team

publishedboolean

Filter by published status (true or false)

Response

json
{
  "forms": [
    {
      "id": "665a1b2c3d4e5f6a7b8c9d0e",
      "title": "Customer Feedback Survey",
      "description": "Quarterly satisfaction survey for Q1 2026",
      "slug": "a1b2c3d4e5f6",
      "published": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-02-20T14:22:00.000Z",
      "theme_color": "#6366f1",
      "background_color": "#0a0a0a",
      "response_count": 142,
      "team": {
        "id": "665b2c3d4e5f6a7b8c9d0e1f",
        "name": "Marketing"
      }
    }
  ],
  "total": 24,
  "page": 1,
  "per_page": 50
}

Code Examples

bash
curl -X GET "https://api.nueform.io/api/v1/forms?page=1&per_page=10&published=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Form

POST/api/v1/forms

Creates a new form. You can optionally include an array of questions to create along with the form.

Request Body

titlestring

Form title (cannot be blank)

descriptionstring

Form description

team_idstring

Assign the form to a team (requires create_forms permission)

publishedboolean

Whether the form is published (default: false)

theme_colorstring

Primary theme color (hex, default: #6366f1)

background_colorstring

Background color (hex, default: #0a0a0a)

text_colorstring

Question text color (hex)

answer_text_colorstring

Answer input text color (hex)

placeholder_colorstring

Input placeholder color (hex)

button_colorstring

Button background color (hex)

button_text_colorstring

Button text color (hex)

title_colorstring

Title text color (hex)

description_colorstring

Description text color (hex)

option_text_colorstring

Choice option text color (hex)

indicator_bg_colorstring

Step indicator background color (hex)

indicator_text_colorstring

Step indicator text color (hex)

font_familystring

Question font family

font_family_answerstring

Answer input font family

font_family_buttonstring

Button font family

font_family_descriptionstring

Description font family

font_family_optionstring

Choice option font family

font_family_indicatorstring

Step indicator font family

question_font_sizestring

Question font size (e.g., "24px")

custom_cssstring

Custom CSS injected into the form renderer

show_progress_barboolean

Show a progress bar (default: true)

branding_logo_urlstring

URL for the branding logo

branding_footer_textstring

Custom footer text

hide_brandingboolean

Hide NueForm branding (default: false)

top_logo_urlstring

URL for a logo displayed at the top of the form

top_logo_sizestring

Top logo size (e.g., "120px")

top_logo_alignmentstring

Top logo alignment ("left", "center", "right")

top_logo_cssstring

Custom CSS for the top logo

watermark_cssstring

Custom CSS for the watermark

welcome_titlestring

Welcome screen title

welcome_descriptionstring

Welcome screen description

welcome_button_textstring

Welcome screen button text (default: "Start")

thank_you_titlestring

Thank-you screen title (default: "Thank you!")

thank_you_descriptionstring

Thank-you screen description

modestring

Form mode: "standard", "knowledge_quiz", "lead_qualification", "match_quiz" (default: "standard")

quiz_settingsobject

Quiz configuration (for quiz modes)

variablesobject

Form-level variables for logic

start_logic_jumpsarray

Logic jump rules applied at form start

webhook_urlstring

URL to receive POST on submission (Pro plan required)

limit_one_responseboolean

Limit to one response per visitor (default: false)

incremental_submissionboolean

Save answers incrementally as the respondent progresses (default: false)

questionsarray

Array of question objects to create (see below)

Request Example

json
{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "type": "short_text",
      "title": "What is your name?",
      "required": true
    },
    {
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "required": true,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      }
    },
    {
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "required": true,
      "properties": {
        "steps": 5,
        "shape": "star"
      }
    }
  ]
}

Response

Returns the created form object with all questions:

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": false,
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d002",
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "description": null,
      "required": true,
      "order": 1,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      },
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d003",
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "description": null,
      "required": true,
      "order": 2,
      "properties": {
        "steps": 5,
        "shape": "star"
      },
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

Code Examples

bash
curl -X POST "https://api.nueform.io/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Feedback Survey",
    "description": "Help us improve our product",
    "questions": [
      {
        "type": "short_text",
        "title": "What is your name?",
        "required": true
      }
    ]
  }'

Get Form

GET/api/v1/forms/:id

Retrieves a single form by ID, including all questions ordered by their position.

Path Parameters

idstring

The form ID

Response

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-02-20T14:22:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "text_color": null,
  "answer_text_color": null,
  "placeholder_color": null,
  "button_color": null,
  "button_text_color": null,
  "font_family": null,
  "question_font_size": null,
  "custom_css": null,
  "show_progress_bar": true,
  "incremental_submission": false,
  "limit_one_response": false,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "branding_logo_url": null,
  "branding_footer_text": null,
  "hide_branding": false,
  "mode": "standard",
  "webhook_url": null,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "response_count": 142,
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

Code Examples

bash
curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Form

PUT/api/v1/forms/:id

Updates a form's fields and synchronizes its questions. When you include a questions array, NueForm will:

  • Update existing questions (matched by id)
  • Create new questions (no id or unrecognized id)
  • Delete questions that exist on the form but are not present in the array

If the form is currently published, the has_unpublished_changes flag is automatically set to true.

Path Parameters

idstring

The form ID

Request Body

Accepts all fields from Create Form except team_id. Only include fields you want to change.

Request Example

json
{
  "title": "Updated Survey Title",
  "description": "Revised description for Q2",
  "theme_color": "#10b981",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your full name?",
      "required": true
    },
    {
      "type": "long_text",
      "title": "Any additional comments?",
      "required": false
    }
  ]
}

Response

Returns the updated form object with all questions (same schema as Get Form).

Code Examples

bash
curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Survey Title",
    "theme_color": "#10b981"
  }'

Delete Form

DELETE/api/v1/forms/:id

Permanently deletes a form and all associated data, including questions, responses, versions, and changelog entries. Associated file uploads are cleaned up asynchronously.

This action is irreversible. All responses collected for this form will be permanently deleted.

Path Parameters

idstring

The form ID

Response

json
{
  "success": true
}

Code Examples

bash
curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish Form

POST/api/v1/forms/:id/publish

Publishes a form by creating a versioned snapshot of the current form and its questions. Each publish increments the version number. The form becomes publicly accessible at its shareable URL.

Path Parameters

idstring

The form ID

Response

Returns the form object with a published_version field indicating the new version number:

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "published_version": 3,
  "questions": [ ... ]
}

Code Examples

bash
curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Unpublish Form

DELETE/api/v1/forms/:id/publish

Unpublishes a form, making it no longer accessible at its public URL. The published version snapshot is retained so you can re-publish later.

Path Parameters

idstring

The form ID

Response

Returns the updated form object with published set to false.

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "published": false,
  "questions": [ ... ]
}

Code Examples

bash
curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Duplicate Form

POST/api/v1/forms/:id/duplicate

Creates a copy of an existing form, including all questions. Logic jump references are automatically remapped to the new question IDs. The duplicated form is always created in an unpublished state.

Path Parameters

idstring

The ID of the form to duplicate

Request Body

titlestring

Title for the new form (default: "Original Title (Copy)")

team_idstring

Assign the duplicate to a different team

Request Example

json
{
  "title": "Customer Feedback Survey v2",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f"
}

Response

Returns the newly created form object (same schema as Get Form) with published set to false.

Code Examples

bash
curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer Feedback Survey v2" }'

Error Responses

All endpoints return standard error responses.

Error Codes

400Bad Request

Validation error or missing required field

401Unauthorized

Missing or invalid API key

403Forbidden

Insufficient permissions for team forms

404Not Found

Form not found

500Server Error

Internal server error

Error Example

json
{
  "error": "Title is required"
}
Last updated: May 23, 2026