Developers

Forms

Retrieve form

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

Retrieves a form by the given form_id. Includes any theme and images attached to the form as references.

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

Request

Path Parameters

form_id
, 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.

Response

Status

200 OK

Schema

Form resource as retrieved by a client editing the form.

id
string
title
string
language
string
Default:en
fields
array of object
hidden
array of string
Default:
variables Path 3
object
score
integer
Valid values:0
price
number
welcome_screens Path 3
array of object
ref
string

Readable name you can use to reference the welcome screen.

title
string, required

Title for the welcome screen.

properties Path 3
object
description
string

Description of the welcome screen.

show_button
boolean

true to display a 'Start' button on the welcome screen. Otherwise, false.

button_text
string

Text to display on the 'Start' button on the welcome screen.

attachment Path 3
object

Allows you to display images and videos. Available for welcome and thank you screens, as well as all 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 URL of the supported platforms, Vimeo, YouTube or Pexels.

scale
number
Valid values:0.40.60.81

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

properties Path 3
object
description
string

Optional description of the attachment. In the case of images this is used as an alt text that describes your image for people with visual impairments.

layout Path 3
object

Allows you to position attachment. Available in all fields, Welcome and Thank you screens.

type
string
Valid values:splitwallpaperfloatstack

Type of layout.

placement
string
Valid values:leftright

Position of media for split and float layouts

attachment Path 3
object

Allows you to display images and videos. Available for welcome and thank you screens, as well as all 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 URL of the supported platforms, Vimeo, YouTube or Pexels.

scale
number
Valid values:0.40.60.81

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

properties Path 3
object
description
string

Optional description of the attachment. In the case of images this is used as an alt text that describes your image for people with visual impairments.

viewport_overrides Path 3
object

Allows you to add layout-specific overrides per viewport (small / large). Available in all fields, Welcome and Thank you screens.

small Path 3
object

Allows you to add layout-specific overrides for small viewports.

type
string
Valid values:splitwallpaperfloatstack

Type of layout.

placement
string
Valid values:leftright

Position of media for split and float layouts.

large Path 3
object

Allows you to add layout-specific overrides for large viewports.

type
string
Valid values:splitwallpaperfloatstack

Type of layout.

placement
string
Valid values:leftright

Position of media for split and float layouts.

thankyou_screens Path 3
array of object
ref
string

Readable name you can use to reference the thank you screen.

title
string, required

Title for the thank you screen.

type
string
Valid values:thankyou_screenurl_redirect

The type of thank you screen.

properties Path 3
object
show_button
boolean

true to display a button on the thank you screen. Otherwise, false.

button_text
string

Text to display on the button on the thank you screen.

button_mode
string
Valid values:reloaddefault_redirectredirect

Specify whether the form should show the default redirect or redirect to custom URL when respondents click the button. Premium feature.

redirect_url
string

URL where the typeform should redirect after submission, if you specified redirect for button_mode or are using the url_redirect type.

share_icons
boolean

true to display social media sharing icons on the thank you screen so respondents can post your typeform's link on Facebook, Twitter, LinkedIn, and Google+. Otherwise, false.

attachment Path 3
object

Allows you to display images and videos. Available for welcome and thank you screens, as well as all 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 URL of the supported platforms, Vimeo, YouTube or Pexels.

scale
number
Valid values:0.40.60.81

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

properties Path 3
object
description
string

Optional description of the attachment. In the case of images this is used as an alt text that describes your image for people with visual impairments.

layout Path 3
object

Allows you to position attachment. Available in all fields, Welcome and Thank you screens.

type
string
Valid values:splitwallpaperfloatstack

Type of layout.

placement
string
Valid values:leftright

Position of media for split and float layouts

attachment Path 3
object

Allows you to display images and videos. Available for welcome and thank you screens, as well as all 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 URL of the supported platforms, Vimeo, YouTube or Pexels.

scale
number
Valid values:0.40.60.81

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

properties Path 3
object
description
string

Optional description of the attachment. In the case of images this is used as an alt text that describes your image for people with visual impairments.

viewport_overrides Path 3
object

Allows you to add layout-specific overrides per viewport (small / large). Available in all fields, Welcome and Thank you screens.

small Path 3
object

Allows you to add layout-specific overrides for small viewports.

type
string
Valid values:splitwallpaperfloatstack

Type of layout.

placement
string
Valid values:leftright

Position of media for split and float layouts.

large Path 3
object

Allows you to add layout-specific overrides for large viewports.

type
string
Valid values:splitwallpaperfloatstack

Type of layout.

placement
string
Valid values:leftright

Position of media for split and float layouts.

logic Path 3
array of object
type
string, required
Valid values:fieldhidden

Specifies whether the Logic Jump is based on a question field or Hidden Field.

ref
string

Reference to the field that triggers the the Logic Jump.

actions Path 3
array of object, required

Array of objects that define the Logic Jump's behavior.

action
string, required
Valid values:jumpaddsubtractmultiplydivideset

Behavior the Logic Jump will take.

details Path 3
object, required

Properties that further specify how the Logic Jump will behave.

to Path 3
object

Specifies where the Logic Jump leads---to another field ("field"), a thank you screen ("thankyou") or an outcome ("outcome").

type
string, required
Valid values:fieldthankyououtcome

Logic Jump "to" option you are using.

value
string, required

The "ref" value for the field, Hidden Field, or thank you screen the Logic Jump leads to.

target Path 3
object

Keeps a running total for variables.

type
string, required
Valid values:variable

Specifies that the value is a variable.

value
string, required

Variable name to use in the calculation.

value Path 3
object

Specifies the value to use in the calculation for the variables.

type
string, required
Valid values:constantvariableevaluation

Specifies which type of value is used.---It can be a numeric value, a variable name or an evaluation to determine an outcome.

value
, required

Value used in the variable calculation.

condition Path 3
object, required

Conditions for executing the Logic Jump. Conditions answer the question, "Under what circumstances?" The condition object is the IF statement in your Logic Jump.

op
string, required
Valid values:begins_withends_withcontainsnot_containslower_thanlower_equal_thangreater_thangreater_equal_thanisis_notequalnot_equalalwaysonnot_onearlier_thanearlier_than_or_onlater_thanlater_than_or_on

Operator for the condition.

vars Path 3
array of object, required

Object that defines the field type and value to evaluate with the operator.

type
string, required
Valid values:fieldhiddenvariableconstantchoice

Type of value the condition object refers to.

value
object, required

Value to check for in the "type" field to evaluate with the operator.

theme Path 3
object
href
string
workspace Path 3
object
href
string
_links Path 3
object
display
string
settings Path 3
object
language
string
Valid values:enescafrderuitdaptchzhnlnoukjakohrfisvplelhutrcsetdi
is_public
boolean
Default:true

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

autosave_progress
boolean
Default:true

true to enable saving partial form responses on the client side. Otherwise, false.

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

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

show_typeform_branding
boolean
Default:true

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

show_time_to_complete
boolean
Default:true

true to display estimated time to complete a typeform on Welcome screens, false to hide it. Mutually exclusive with show_number_of_submissions

show_number_of_submissions
boolean

true to display number of submissions on Welcome screens, false to hide it. Mutually exclusive with show_time_to_complete

show_cookie_consent
boolean

true to request cookie consent to respondents through a banner, false to do not request it.

show_question_number
boolean
Default:true

true to display the question number on each block, false to hide it.

show_key_hint_on_choices
boolean
Default:true

true to display the key hint letters on Multiple Choice, Picture Choice, Legal and Yes/No blocks, false to hide them.

hide_navigation
boolean

false to display the navigation arrows in the bottom-right corner of the form, true to hide them

meta Path 3
object
title
string

Title that represents how the typeform is named in the workspace.

allow_indexing
boolean
Default:true

true to allow search engines to index your typeform. Otherwise, false.

description
string

Description for search engines to display for your typeform.

image Path 3
object
href
string

URL of image for search engines to display for your typeform.

redirect_after_submit_url
string

URL where the typeform should redirect upon submission.

google_analytics
string

Google Analytics tracking ID to use for the form.

facebook_pixel
string

Facebook Pixel tracking ID to use for the form.

google_tag_manager
string

Google Tag Manager ID to use for the form.

milestones Path 3
array of object

An array with block references, indicating where each partial submit point is located. Currently, only one partial submit point per form is allowed. If more than one item is sent within the array, the form definition will be rejected. If the status is inactive, there's also a reason.

field_ref
string

Block reference after which "submit and continue" would be shown in the renderer.

status
string
Valid values:activeinactive

Informative, can't be set through API.

reason
string
Valid values:wrong_positionincompatible_feature

Informative, can't be set through API.

cui_settings Path 3
object
avatar
string

URL for the image to use as conversation avatar. Images must already exist in your account---use the image's Typeform URL, such as "https://images.typeform.com/images/kbn8tc98AHb".

is_typing_emulation_disabled
boolean

Specifies whether to disable the conversation's typing emulation (i.e. the delay between messages, the aim of which is to give the impression there's an actual person on the other side of the conversation). Typing emulation is enabled by default.

typing_emulation_speed
string
Valid values:slowmediumfast

The pace at which messages appear in a conversation (as long as typing emulation is enabled).

Example

{
  "id": "id",
  "title": "title",
  "language": "en",
  "fields": [
    {}
  ],
  "hidden": [
    "string"
  ],
  "variables": {
    "score": 0,
    "price": 0
  },
  "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": {
          "image": {
            "value": "https://images.typeform.com/images/4bcd3"
          },
          "Pexels": {
            "value": "https://www.pexels.com/video/people-traveling-in-the-desert-1739011"
          },
          "Vimeo": {
            "value": "https://vimeo.com/245714980"
          },
          "YouTube": {
            "value": "https://www.youtube.com/watch?v=cGk3tZIIpXE"
          }
        },
        "scale": 0,
        "properties": {
          "description": "description"
        }
      },
      "layout": {
        "type": "float",
        "placement": "left",
        "attachment": {
          "type": "image",
          "href": {
            "image": {
              "value": "https://images.typeform.com/images/4bcd3"
            },
            "Pexels": {
              "value": "https://www.pexels.com/video/people-traveling-in-the-desert-1739011"
            },
            "Vimeo": {
              "value": "https://vimeo.com/245714980"
            },
            "YouTube": {
              "value": "https://www.youtube.com/watch?v=cGk3tZIIpXE"
            }
          },
          "scale": 0,
          "properties": {
            "description": "description"
          }
        },
        "viewport_overrides": {
          "small": {
            "type": "float",
            "placement": "left"
          },
          "large": {
            "type": "split",
            "placement": "right"
          }
        }
      }
    }
  ],
  "thankyou_screens": [
    {
      "ref": "nice-readable-thank-you-ref",
      "title": "Thank you Title",
      "type": "type",
      "properties": {
        "show_button": true,
        "button_text": "start",
        "button_mode": "redirect",
        "redirect_url": "https://www.typeform.com",
        "share_icons": true
      },
      "attachment": {
        "type": "image",
        "href": {
          "image": {
            "value": "https://images.typeform.com/images/4bcd3"
          },
          "Pexels": {
            "value": "https://www.pexels.com/video/people-traveling-in-the-desert-1739011"
          },
          "Vimeo": {
            "value": "https://vimeo.com/245714980"
          },
          "YouTube": {
            "value": "https://www.youtube.com/watch?v=cGk3tZIIpXE"
          }
        },
        "scale": 0,
        "properties": {
          "description": "description"
        }
      },
      "layout": {
        "type": "float",
        "placement": "left",
        "attachment": {
          "type": "image",
          "href": {
            "image": {
              "value": "https://images.typeform.com/images/4bcd3"
            },
            "Pexels": {
              "value": "https://www.pexels.com/video/people-traveling-in-the-desert-1739011"
            },
            "Vimeo": {
              "value": "https://vimeo.com/245714980"
            },
            "YouTube": {
              "value": "https://www.youtube.com/watch?v=cGk3tZIIpXE"
            }
          },
          "scale": 0,
          "properties": {
            "description": "description"
          }
        },
        "viewport_overrides": {
          "small": {
            "type": "float",
            "placement": "left"
          },
          "large": {
            "type": "split",
            "placement": "right"
          }
        }
      }
    }
  ],
  "logic": [
    {
      "type": "type",
      "ref": "ref",
      "actions": [
        {
          "action": "action",
          "details": {
            "to": {
              "type": "type",
              "value": "value"
            },
            "target": {
              "type": "type",
              "value": "value"
            },
            "value": {
              "type": "type"
            }
          },
          "condition": {
            "op": "op",
            "vars": [
              {
                "type": "type",
                "value": {}
              }
            ]
          }
        }
      ]
    }
  ],
  "theme": {
    "href": "https://api.typeform.com/themes/Fs24as"
  },
  "workspace": {
    "href": "https://api.typeform.com/workspaces/Aw33bz"
  },
  "_links": {
    "display": "https://subdomain.typeform.com/to/abc123"
  },
  "settings": {
    "language": "language",
    "is_public": true,
    "autosave_progress": true,
    "progress_bar": "proportion",
    "show_progress_bar": true,
    "show_typeform_branding": true,
    "show_time_to_complete": true,
    "show_number_of_submissions": true,
    "show_cookie_consent": true,
    "show_question_number": true,
    "show_key_hint_on_choices": true,
    "hide_navigation": true,
    "meta": {
      "title": "title",
      "allow_indexing": true,
      "description": "description",
      "image": {
        "href": "href"
      }
    },
    "redirect_after_submit_url": "redirect_after_submit_url",
    "google_analytics": "google_analytics",
    "facebook_pixel": "facebook_pixel",
    "google_tag_manager": "google_tag_manager",
    "milestones": [
      {
        "field_ref": "field_ref",
        "status": "status",
        "reason": "reason"
      }
    ]
  },
  "cui_settings": {
    "avatar": "https://images.typeform.com/images/4bcd3",
    "is_typing_emulation_disabled": true,
    "typing_emulation_speed": "fast"
  }
}