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

Set to true to publish the form right after it is created. Publishing runs the same checks as Publish Form. If a check fails, the form is still created as a draft: the response is 201 with published: false and a publish_error object (reason, message, question_ids, upgrade_required). Don't create the form again — fix the issue, then call Publish Form. Default: false (draft)

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)

auto_translateboolean

NueLingo — translate the published form on demand into any supported language for respondents (Pro+; stored as false on other plans). Requires a default language; takes effect on publish.

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,
  "auto_translate": 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: your changes are saved as a draft, and respondents keep seeing the published version until you publish again.

published changes the form's state instead of being saved as a field:

  • On a draft form, published: true publishes it after your changes are saved, with the same checks as Publish Form. If a check fails, your changes are still saved and the API returns 409 Conflict with form_id and saved_as_draft: true.
  • On a form that is already live, published: true changes nothing — call Publish Form to make your changes live.
  • published: false takes a live form offline, like Unpublish Form.

On team forms, only team admins and owners can change published.

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

Query Parameters

delete_signed_contractsboolean

Required true to delete a form that has completed signed contracts. They are permanently deleted with the form, including the signed PDFs and audit trails. Without it, such a form is not deleted: the API answers 409 with reason: form_has_signed_contracts and signed_contracts (how many).

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 — the same pipeline as the Publish button in the builder. Each publish increments the version number, and the form becomes publicly accessible at its shareable URL.

Before anything is published, NueForm checks that:

  • team forms are published only by team admins and owners, and personal forms only by their owner (anyone else gets 403 Forbidden, or 404 Not Found if they aren't a member of the form's team);
  • Pro features (booking questions, e-signature contracts, data nodes, form webhooks and payments into your own Stripe account) are included in the form owner's plan (the team owner's plan for team forms);
  • booking, email-step, Fuse and composite questions are fully configured.

If any check fails, the form is not published and the API returns 409 Conflict with a reason code and the question_ids to fix (see Error Handling). Successful responses include published_version and a warnings array of non-blocking notices.

Path Parameters

idstring

The form ID

Response

Returns the published form with published_version (the new version number) and warnings (non-blocking notices, often empty):

json
{
  "data": {
    "id": "665a1b2c3d4e5f6a7b8c9d0e",
    "title": "Customer Feedback Survey",
    "slug": "a1b2c3d4e5f6",
    "published": true,
    "has_unpublished_changes": false,
    "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
    "published_version": 3,
    "warnings": [
      {
        "code": "booking_attendee_ask",
        "question_id": "66a1b2c3d4e5f6a7b8c9d004",
        "question_title": "Book a demo",
        "message": "Booking question \"Book a demo\" has no attendee email mapping, so respondents will be asked for their email when they book."
      }
    ],
    "questions": [ ... ]
  }
}

Publish blocked (409)

Nothing is published. reason says which check failed and question_ids lists the questions to fix; upgrade_required is true when the form owner's plan needs an upgrade:

json
{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}

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. Team forms can only be unpublished by team admins and owners, and personal forms by their owner; anyone else gets 403 Forbidden, or 404 Not Found if they aren't a member of the form's team.

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

409Conflict

Publish blocked: a publish check failed (see Publish Form)

500Server Error

Internal server error

Error Example

json
{
  "error": "Title is required"
}
Last updated: October 8, 2026