Developers

Forms

Update form

put

https://api.typeform.com/forms/{form_id}

Updates an existing form.

Your request body must include all the existing form fields, in addition to the new email field.

Overwrites the previously stored form with the given form_id. Any new fields in your request will be added to the form. Likewise, any fields you don't include in your request will be deleted from the form. Make sure your PUT request contains every field you want to include in your updated form, including the field id.

NOTE: Tread carefully when updating fields in forms. PUT overwrites the entire form, so if you don't include each field (with the original field id) in your PUT request, the missing fields and results for those fields will be deleted.

Details about the fields and elements for this endpoint are available in the Create Form description.

The theme property applies a theme to the form. If you don't specify a value for the 'theme' property, Typeform applies a new copy of the default theme to the form, even if you already have a copy of the default theme applied to this form.

Request

Path Parameters

form_id

string, required

Unique ID for the form. Find in your form URL. For example, in the URL "https://mysite.typeform.com/to/u6nXL7" the form_id is u6nXL7.

Request Body

fields

array of object

ref

string

Readable name you can use to reference the field.

title

string, required

Unique name you assign to the field on this form.

type

string, required

Valid values:datedropdownemailfile_uploadgrouplegallong_textmultiple_choicenumberopinion_scalepaymentpicture_choiceratingshort_textstatementwebsiteyes_nophone_number

The type of field.

properties

object

description

string

Question or instruction to display for the field.

choices

array of object

Answer choices. Available for dropdown, multiple_choice, and picture_choice types.

ref

string

Readable name you can use to reference the answer choice. Available for multiple_choice and picture_choice types. Not available for dropdown types.

label

string

Text for the answer choice.

attachment

object

Identifies the image to use for the answer choice. Available only for picture_choice types.

type

string

Valid values:image

Type of attachment.

href

string

URL for the image to use for the answer choice. Images must already exist in your account---use the image's Typeform URL.

fields

array of array

Contains the fields that belong in a question group. Only payment and group blocks are not allowed inside a question group. Available for the group type.

allow_multiple_selection

boolean

true to allow respondents to select more than one answer choice. false to allow respondents to select only one answer choice. Available for multiple_choice and picture_choice types.

randomize

boolean

true if answer choices should be presented in a new random order for each respondent. false if answer choices should be presented in the same order for each respondent. Available for multiple_choice, picture_choice and dropdown types.

allow_other_choice

boolean

true to include an "Other" option so respondents can enter a different answer choice from those listed. false to limit answer choices to those listed. Available for multiple_choice and picture_choice types.

vertical_alignment

boolean

true to list answer choices vertically. false to list answer choices horizontally. Available for multiple_choice types.

supersized

boolean

true if you want to use larger-sized images for answer choices. Otherwise, false. Available for picture_choice types.

show_labels

boolean

Default:

true to show text labels and images as answer choices. false to show only images as answer choices. Available for picture_choice types.

alphabetical_order

boolean

true if question should list dropdown answer choices in alphabetical order. false if question should list dropdown answer choices in the order they're listed in the "choices" array. Available for dropdown types.

hide_marks

boolean

true if you want to display quotation marks around the statement on the form. Otherwise, false. Available for statement types.

button_text

string

Default:Continue

Text to display in the button associated with the object. Available for group, payment, and statement types.

steps

number

Number of steps in the scale's range. Minimum is 5 and maximum is 11. Available for opinion_scale and rating types.

shape

string

Valid values:catcirclecloudcrowndogdropletflagheartlightbulbpencilskullstarthunderboltticktrophyupuser

Default:star

Shape to display on the scale's steps. Available for opinion_scale and rating types.

labels

object

Label to help respondents understand the scale's range. Available for opinion_scale and rating types.

left

string

Text of the left-aligned label for the scale.

right

string

Text of the right-aligned label for the scale.

center

string

Text of the center-aligned label for the scale.

start_at_one

boolean

true if range numbering should start at 1. false if range numbering should start at 0. Available for opinion_scale types.

structure

string

Valid values:MMDDYYYYDDMMYYYYYYYYMMDD

Default:DDMMYYYY

Format for month, date, and year in answer. Available for date types.

separator

string

Valid values:/-.

Default:/

Character to use between month, day, and year in answer. Available for date types.

currency

string

Valid values:AUDBRLCADCHFDKKEURGBPMXNNOKSEKUSD

Default:EUR

Currency of the payment. Available for payment types.

price

object

Price of the item. Available for payment fields.

type

string

Valid values:variable

value

string

Valid values:price

show_button

boolean

true to display a button. Otherwise, false. Available for group and payment types.

validations

object

required

boolean

true if respondents must provide an answer. Otherwise, false. Available for date, dropdown, email, file_upload, legal, long_text, multiple_choice, number, opinion_scale, payment, picture_choice, rating, short_text, website, phone_number, and yes_no types.

max_length

integer

Maximum number of characters allowed in the answer. Available for long_text, number, and short_text types.

min_value

integer

Minimum value allowed in the answer, must be a positive integer. Available for number types.

max_value

integer

Maximum value allowed in the answer, must be a positive integer. Available for number types.

attachment

object

Allows you to display images and videos. Available for welcome and thank you screens, as well as date, dropdown, email, group, long_text, multiple_choice, number, opinion_scale, payment, rating, short_text, statement, phone_number, and yes_no fields.

type

string

Valid values:imagevideo

Type of attachment.

href

string

URL for the image or video you want to display. Images must already exist in your account---use the image's Typeform URL, such as "https://images.typeform.com/images/kbn8tc98AHb". For videos, use the video's YouTube.com URL.

scale

number

Valid values:0.40.60.81

Optional parameter for responsively scaling videos. Available only for "video" type. Default value is 0.6

string, required

The unique ID for the question.

title

string, required

Title to use for the typeform.

settings

object

language

string

Valid values:enescafrderuitdaptchzhnlnoukjakohrfisvplelhutrcsetdi

is_public

boolean

Default:

true if your form is public. Otherwise, false (your form is private).

progress_bar

string

Valid values:percentageproportion

Default:proportion

Basis for the progress bar displayed on the screen. Choose "proportion" to show the number of questions answered so far. Choose "percentage" to show the percentage of questions answered so far.

show_progress_bar

boolean

Default:

true to display progress bar on the typeform. Otherwise, false.

show_typeform_branding

boolean

Default:

true to display Typeform brand on the typeform. false to hide Typeform branding on the typeform. Hiding Typeform branding is available for Premium accounts.

Example

{
  "title": "This is an example form",
  "settings": {
    "language": "en",
    "is_public": false,
    "progress_bar": "percentage",
    "show_progress_bar": true,
    "show_typeform_branding": false,
    "meta": {
      "allow_indexing": true,
      "description": "Cool meta description",
      "image": {
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    "redirect_after_submit_url": "https://www.redirecttohere.com",
    "google_analytics": "UA-1111-22",
    "facebook_pixel": "4347295725729872",
    "google_tag_manager": "gtm-43959999",
    "notifications": {
      "self": {
        "enabled": true,
        "recipients": [
          "email@example.org"
        ],
        "reply_to": "{{field:email_field_reference}}",
        "subject": "Typeform: new response for {{form:title}}",
        "message": "Your typeform {{form:title}} has a new response\n\n{{form:all_answers}}"
      },
      "respondent": {
        "enabled": false,
        "recipient": "{{field:email_field_reference}}",
        "reply_to": [
          "info@example.org"
        ],
        "subject": "Typeform: Thank you for completing {{form:title}}!",
        "message": "Hi {{field:name_field_reference}}!\n\nWe recieved your submission. Thank you, and have a nice day!\n\nSincerely,\nThe Team at My Company"
      }
    }
  },
  "theme": {
    "href": "https://api.typeform.com/themes/jL34ds"
  },
  "workspace": {
    "href": "https://api.typeform.com/workspaces/Aw33bz"
  },
  "hidden": [
    "var1",
    "var2",
    "var3"
  ],
  "variables": {
    "score": 0,
    "price": 10.59
  },
  "welcome_screens": [
    {
      "ref": "nice-readable-welcome-ref",
      "title": "Welcome Title",
      "properties": {
        "description": "Cool description for the welcome",
        "show_button": true,
        "button_text": "start"
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    }
  ],
  "thankyou_screens": [
    {
      "ref": "nice-readable-thank-you-ref",
      "title": "Thank you Title",
      "properties": {
        "show_button": true,
        "button_text": "start",
        "button_mode": "redirect",
        "redirect_url": "https://www.typeform.com",
        "share_icons": false
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    }
  ],
  "fields": [
    {
      "ref": "nice_readable_date_reference",
      "title": "Date Title",
      "type": "date",
      "properties": {
        "description": "Cool description for the date",
        "structure": "DDMMYYYY",
        "separator": "-"
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "video",
        "href": "https://www.youtube.com/watch?v=Uui3oT-XBxs",
        "scale": 0.8
      }
    },
    {
      "ref": "nice_readable_dropdown_reference",
      "title": "Dropdown Title",
      "type": "dropdown",
      "properties": {
        "description": "Cool description for the dropdown",
        "alphabetical_order": false,
        "randomize": false,
        "choices": [
          {
            "label": "Foo"
          },
          {
            "label": "Bar"
          }
        ]
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    {
      "ref": "nice_readable_email_reference",
      "title": "Email Title",
      "type": "email",
      "properties": {
        "description": "Cool description for the email"
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "video",
        "href": "https://www.youtube.com/watch?v=Uui3oT-XBxs",
        "scale": 0.8
      }
    },
    {
      "ref": "nice_readable_file_upload_reference",
      "title": "File Upload Title",
      "type": "file_upload",
      "properties": {
        "description": "Cool description for the file upload"
      },
      "validations": {
        "required": false
      }
    },
    {
      "ref": "nice_readable_legal_reference",
      "title": "Legal Title",
      "type": "legal",
      "properties": {
        "description": "Cool description for the legal"
      },
      "validations": {
        "required": false
      }
    },
    {
      "ref": "nice_readable_long_text_reference",
      "title": "Long Text Title",
      "type": "long_text",
      "properties": {
        "description": "Cool description for the long text"
      },
      "validations": {
        "required": false,
        "max_length": 20
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    {
      "ref": "nice_readable_multiple_choice_reference",
      "title": "Multiple Choice Title",
      "type": "multiple_choice",
      "properties": {
        "description": "Cool description for the multiple choice",
        "randomize": true,
        "allow_multiple_selection": false,
        "allow_other_choice": true,
        "vertical_alignment": false,
        "choices": [
          {
            "label": "Foo",
            "ref": "foo_choice_ref"
          },
          {
            "label": "Bar",
            "ref": "bar_choice_ref"
          }
        ]
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "video",
        "href": "https://www.youtube.com/watch?v=Uui3oT-XBxs",
        "scale": 0.8
      }
    },
    {
      "ref": "nice_readable_number_reference",
      "title": "Number Title",
      "type": "number",
      "properties": {
        "description": "Cool description for the number"
      },
      "validations": {
        "required": false,
        "min_value": 20,
        "max_value": 50
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    {
      "ref": "nice_readable_opinion_scale_reference",
      "title": "Opinion Scale Title",
      "type": "opinion_scale",
      "properties": {
        "description": "Cool description for the opinion scale field",
        "steps": 9,
        "start_at_one": true,
        "labels": {
          "left": "left label",
          "center": "center label",
          "right": "right label"
        }
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "video",
        "href": "https://www.youtube.com/watch?v=Uui3oT-XBxs",
        "scale": 0.8
      }
    },
    {
      "ref": "nice_readable_picture_choice_reference",
      "title": "Picture Choice Title",
      "type": "picture_choice",
      "properties": {
        "description": "Cool description for the picture choice",
        "randomize": true,
        "allow_multiple_selection": false,
        "allow_other_choice": true,
        "supersized": false,
        "show_labels": false,
        "choices": [
          {
            "ref": "foo_choice_ref1",
            "label": "Foo 1",
            "attachment": {
              "type": "image",
              "href": "https://images.typeform.com/images/4bcd3"
            }
          },
          {
            "ref": "foo_choice_ref2",
            "label": "Foo 2",
            "attachment": {
              "type": "image",
              "href": "https://images.typeform.com/images/4bcd3"
            }
          }
        ]
      },
      "validations": {
        "required": false
      }
    },
    {
      "ref": "nice_readable_rating_reference",
      "title": "Rating Title",
      "type": "rating",
      "properties": {
        "description": "Cool description for the rating",
        "steps": 10,
        "shape": "star"
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "video",
        "href": "https://www.youtube.com/watch?v=Uui3oT-XBxs",
        "scale": 0.8
      }
    },
    {
      "ref": "nice_readable_short_text_reference",
      "title": "Short Text Title",
      "type": "short_text",
      "properties": {
        "description": "Cool description for the short text"
      },
      "validations": {
        "required": false,
        "max_length": 20
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    {
      "ref": "nice_readable_statement_reference",
      "title": "Statement Title",
      "type": "statement",
      "properties": {
        "description": "Cool description for the statement",
        "button_text": "Statement button text",
        "hide_marks": true
      },
      "attachment": {
        "type": "video",
        "href": "https://www.youtube.com/watch?v=Uui3oT-XBxs",
        "scale": 0.8
      }
    },
    {
      "ref": "nice_readable_website_reference",
      "title": "Website Title",
      "type": "website",
      "properties": {
        "description": "Cool description for the website"
      },
      "validations": {
        "required": false
      }
    },
    {
      "ref": "nice_readable_yes_no_reference",
      "title": "yes or no",
      "type": "yes_no",
      "properties": {
        "description": "Cool description for the Yes/No question"
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    {
      "ref": "nice_readable_payment_reference",
      "title": "payment",
      "type": "payment",
      "properties": {
        "description": "Cool description for the payment group",
        "currency": "EUR",
        "price": {
          "type": "variable",
          "value": "price"
        },
        "show_button": true,
        "button_text": "next"
      },
      "validations": {
        "required": false
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    },
    {
      "ref": "a_group_field_ref",
      "title": "group field",
      "type": "group",
      "properties": {
        "description": "Question group description",
        "show_button": true,
        "button_text": "Some text",
        "fields": [
          {
            "ref": "nice_readable_website_reference",
            "title": "website",
            "type": "website",
            "properties": {
              "description": "Cool description for the website"
            }
          }
        ]
      },
      "attachment": {
        "type": "image",
        "href": "https://images.typeform.com/images/4bcd3"
      }
    }
  ],
  "logic": [
    {
      "type": "field",
      "ref": "triggering_field_reference",
      "actions": [
        {
          "action": "jump",
          "details": {
            "to": {
              "type": "field",
              "value": "jump_to_field_reference"
            }
          },
          "condition": {
            "op": "equal",
            "vars": [
              {
                "type": "field",
                "value": "jump_if_field reference"
              },
              {
                "type": "constant",
                "value": 5
              }
            ]
          }
        },
        {
          "action": "add",
          "details": {
            "target": {
              "type": "variable",
              "value": "score"
            },
            "value": {
              "type": "constant",
              "value": 5
            }
          },
          "condition": {
            "op": "is",
            "vars": [
              {
                "type": "field",
                "value": "triggering_field_reference"
              },
              {
                "type": "constant",
                "value": true
              }
            ]
          }
        }
      ]
    }
  ]
}