{"_id":"56d6cfe32417921500c46829","githubsync":"","sync_unique":"","user":"54f06f1ca17a1521003180f3","__v":2,"category":"56d6cfdf2417921500c4680e","slug":"getting-started-with-typeform-io","body":"Welcome to the documentation for the Typeform Build API. Here we will explain to you how to authenticate your API calls, what error codes we use, how we do versioning, and how you can use the Build API. We will also provide a detailed explanation of each field / question type you can use within the typeforms you create.\n\nWithout further ado, let's try creating your first typeform via Typeform I/O! Simply copy-and-paste the cURL command below into your terminal and run it.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -X POST https://api.typeform.io/v0.4/forms -H \\\"X-API-TOKEN: 61b315aead2aac9be58448727f21ccdc\\\" --data '{\\\"title\\\": \\\"My first form! It just got born.\\\", \\\"fields\\\": [{\\\"type\\\": \\\"yes_no\\\", \\\"question\\\": \\\"No way. Did I really just make a typeform?\\\"}]}' -s | python -mjson.tool\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nTake a look at the `\"_links\"` array in the JSON response, and try visiting the URL (`\"href\"`) in the object with `\"rel\": \"form_render\"`. You should be able to see your first typeform. Congratulations! \n[block:callout]\n{\n \"type\": \"info\",\n \"body\": \"If this is your first time using Typeform I/O, we recommend you read our [\\\"Getting Started\\\"-guide](doc:getting-started) to get a good overview of how to use the API and what you can do with it.\",\n \"title\": \"First time here?\"\n}\n[/block]\nWe are continuously working on and improving Typeform I/O, and we're heavily focused on making the API as simple as possible, but also feature-rich so you can make good use of it. We would be forever grateful if you can leave us feedback. We welcome all questions, and we'd love to talk to you about how you're using Typeform I/O, what you hope for from us in the future, or anything else!\n\nYou can contact us at [support@typeform.com](mailto:support@typeform.com).","order":0,"excerpt":"","hidden":false,"link_external":false,"link_url":"","title":"Getting Started with Typeform I/O","type":"basic","api":{"params":[],"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"","auth":"required"},"createdAt":"2015-02-27T13:21:30.843Z","updates":[],"project":"54f06f596210dd21004627ce","version":"56d6cfdf2417921500c4680d","isReference":false,"next":{"description":"","pages":[]},"childrenPages":[]}

Getting Started with Typeform I/O

Welcome to the documentation for the Typeform Build API. Here we will explain to you how to authenticate your API calls, what error codes we use, how we do versioning, and how you can use the Build API. We will also provide a detailed explanation of each field / question type you can use within the typeforms you create.
Without further ado, let's try creating your first typeform via Typeform I/O! Simply copy-and-paste the cURL command below into your terminal and run it.
[block:code]
{
"codes": [
{
"code": "curl -X POST https://api.typeform.io/v0.4/forms -H \"X-API-TOKEN: 61b315aead2aac9be58448727f21ccdc\" --data '{\"title\": \"My first form! It just got born.\", \"fields\": [{\"type\": \"yes_no\", \"question\": \"No way. Did I really just make a typeform?\"}]}' -s | python -mjson.tool",
"language": "curl"
}
]
}
[/block]
Take a look at the `"_links"` array in the JSON response, and try visiting the URL (`"href"`) in the object with `"rel": "form_render"`. You should be able to see your first typeform. Congratulations!
[block:callout]
{
"type": "info",
"body": "If this is your first time using Typeform I/O, we recommend you read our [\"Getting Started\"-guide](doc:getting-started) to get a good overview of how to use the API and what you can do with it.",
"title": "First time here?"
}
[/block]
We are continuously working on and improving Typeform I/O, and we're heavily focused on making the API as simple as possible, but also feature-rich so you can make good use of it. We would be forever grateful if you can leave us feedback. We welcome all questions, and we'd love to talk to you about how you're using Typeform I/O, what you hope for from us in the future, or anything else!
You can contact us at [support@typeform.com](mailto:support@typeform.com).

Welcome to the documentation for the Typeform Build API. Here we will explain to you how to authenticate your API calls, what error codes we use, how we do versioning, and how you can use the Build API. We will also provide a detailed explanation of each field / question type you can use within the typeforms you create.
Without further ado, let's try creating your first typeform via Typeform I/O! Simply copy-and-paste the cURL command below into your terminal and run it.
[block:code]
{
"codes": [
{
"code": "curl -X POST https://api.typeform.io/v0.4/forms -H \"X-API-TOKEN: 61b315aead2aac9be58448727f21ccdc\" --data '{\"title\": \"My first form! It just got born.\", \"fields\": [{\"type\": \"yes_no\", \"question\": \"No way. Did I really just make a typeform?\"}]}' -s | python -mjson.tool",
"language": "curl"
}
]
}
[/block]
Take a look at the `"_links"` array in the JSON response, and try visiting the URL (`"href"`) in the object with `"rel": "form_render"`. You should be able to see your first typeform. Congratulations!
[block:callout]
{
"type": "info",
"body": "If this is your first time using Typeform I/O, we recommend you read our [\"Getting Started\"-guide](doc:getting-started) to get a good overview of how to use the API and what you can do with it.",
"title": "First time here?"
}
[/block]
We are continuously working on and improving Typeform I/O, and we're heavily focused on making the API as simple as possible, but also feature-rich so you can make good use of it. We would be forever grateful if you can leave us feedback. We welcome all questions, and we'd love to talk to you about how you're using Typeform I/O, what you hope for from us in the future, or anything else!
You can contact us at [support@typeform.com](mailto:support@typeform.com).

{"_id":"56d6cfe32417921500c4682a","slug":"authentication","category":"56d6cfdf2417921500c4680e","project":"54f06f596210dd21004627ce","version":"56d6cfdf2417921500c4680d","link_url":"","sync_unique":"","api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","auth":"required","params":[],"url":""},"excerpt":"","__v":0,"updates":["56810c594047cf0d0041211a"],"link_external":false,"order":1,"user":"54f06f1ca17a1521003180f3","createdAt":"2015-03-15T21:21:58.289Z","githubsync":"","hidden":false,"body":"To be able to authenticate your API calls, you need to [sign up for an API-key](http://docs.typeform.io/page/signup). It's a painless step and this documentation will be here waiting for you when you come back.\n\nYou authenticate your API calls by adding a header to the requests you make. At this point in time, you will only be able to have a single API key per account. Be sure to keep your API key secret, since it will have access to perform actions on your behalf.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl \\\"https://api.typeform.io/v0.4/\\\" --header 'X-API-TOKEN: YOUR_TOKEN'\",\n \"language\": \"curl\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","type":"basic","title":"Authentication","childrenPages":[]}

Authentication

To be able to authenticate your API calls, you need to [sign up for an API-key](http://docs.typeform.io/page/signup). It's a painless step and this documentation will be here waiting for you when you come back.
You authenticate your API calls by adding a header to the requests you make. At this point in time, you will only be able to have a single API key per account. Be sure to keep your API key secret, since it will have access to perform actions on your behalf.
[block:code]
{
"codes": [
{
"code": "curl \"https://api.typeform.io/v0.4/\" --header 'X-API-TOKEN: YOUR_TOKEN'",
"language": "curl"
}
],
"sidebar": true
}
[/block]

To be able to authenticate your API calls, you need to [sign up for an API-key](http://docs.typeform.io/page/signup). It's a painless step and this documentation will be here waiting for you when you come back.
You authenticate your API calls by adding a header to the requests you make. At this point in time, you will only be able to have a single API key per account. Be sure to keep your API key secret, since it will have access to perform actions on your behalf.
[block:code]
{
"codes": [
{
"code": "curl \"https://api.typeform.io/v0.4/\" --header 'X-API-TOKEN: YOUR_TOKEN'",
"language": "curl"
}
],
"sidebar": true
}
[/block]

{"_id":"56d6cfe32417921500c4682c","createdAt":"2015-03-15T21:50:02.187Z","excerpt":"","hidden":false,"isReference":false,"order":3,"__v":1,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"status":400,"name":"","code":"{}","language":"json"}]},"settings":"","url":"","auth":"required","params":[]},"body":"Until the API has reached a stable state, we will at times, make some backwards-incompatible changes.\n\nWe are doing versioning via the URL, which means that with the current 0.4 version, you would access the API by making a request to `https://api.typeform.io/v0.4/`\n\nDuring development, you can also use the version `latest` to use the latest version available. The final URL would look like this: `https://api.typeform.io/latest/`\n\nIf you have signed up to Typeform I/O, you will be notified before any breaking changes happen.","title":"Versioning","updates":[],"githubsync":"","sync_unique":"","type":"basic","category":"56d6cfdf2417921500c4680e","link_url":"","project":"54f06f596210dd21004627ce","version":"56d6cfdf2417921500c4680d","link_external":false,"slug":"versioning","user":"54f06f1ca17a1521003180f3","childrenPages":[]}

Versioning

Until the API has reached a stable state, we will at times, make some backwards-incompatible changes.
We are doing versioning via the URL, which means that with the current 0.4 version, you would access the API by making a request to `https://api.typeform.io/v0.4/`
During development, you can also use the version `latest` to use the latest version available. The final URL would look like this: `https://api.typeform.io/latest/`
If you have signed up to Typeform I/O, you will be notified before any breaking changes happen.

Until the API has reached a stable state, we will at times, make some backwards-incompatible changes.
We are doing versioning via the URL, which means that with the current 0.4 version, you would access the API by making a request to `https://api.typeform.io/v0.4/`
During development, you can also use the version `latest` to use the latest version available. The final URL would look like this: `https://api.typeform.io/latest/`
If you have signed up to Typeform I/O, you will be notified before any breaking changes happen.

{"_id":"56d6cfe32417921500c4682d","body":"[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"\",\n \"body\": \"Typeform I/O is for programmers and people who want to generate a lot of typeforms.\\n\\nTypeform.com is the version which lets you create a typeform via a friendly interface.\\n\\nIf you just have one form you want to send to a lot of users, you are better off using Typeform.com.\\n\\nIf you have one form per user, and a lot of users, Typeform I/O is more suitable.\\n\\nYou can contact us at [support@typeform.io](mailto:support@typeform.io).\"\n}\n[/block]\nHere's a list of features from Typeform that Typeform I/O hasn't implemented yet. We aim to implement *most* of Typeform's functionality over time.\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"Fields\",\n \"2-0\": \"Configure panel\",\n \"h-0\": \"Category\",\n \"h-1\": \"Missing features\",\n \"0-1\": \"Date field\\nPayment field \\nFile upload field \\nQuestion group \\nFull field customization _\\\\*1_\",\n \"2-1\": \"Self notifications \\nUser notifications \\nProgress widget customization \\nPrivate forms \\nLanguage settings \\nBranding settings \\nIntegrations _\\\\*2_ \\nCustom messages\",\n \"1-0\": \"Build panel\",\n \"1-1\": \"Logic jumps \\nPiping \\nCalculator (score and price) \\nHidden fields\",\n \"3-0\": \"Analyze panel\",\n \"3-1\": \"Results storage _\\\\*3_ \\nMetrics \\nGoogle Analytics \\nReports\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\n__\\*1__: Except for question, description, required, and choices (on fields where applicable) \n__\\*2__: You could implement them manually through webhooks; see \"Results\" \n__\\*3__: We will send the results to your server directly through webhooks; see \"Results\"","excerpt":"","githubsync":"","hidden":false,"isReference":false,"title":"Already using Typeform?","updates":["56d4cfafde84300b002e4cac"],"__v":2,"project":"54f06f596210dd21004627ce","type":"basic","user":"54f47632a510f81900ac1a0d","version":"56d6cfdf2417921500c4680d","link_url":"","api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]}},"category":"56d6cfdf2417921500c4680e","createdAt":"2015-04-02T10:36:24.688Z","link_external":false,"order":4,"slug":"already-use-typeform","sync_unique":"","childrenPages":[]}

Already using Typeform?

[block:callout]
{
"type": "info",
"title": "",
"body": "Typeform I/O is for programmers and people who want to generate a lot of typeforms.\n\nTypeform.com is the version which lets you create a typeform via a friendly interface.\n\nIf you just have one form you want to send to a lot of users, you are better off using Typeform.com.\n\nIf you have one form per user, and a lot of users, Typeform I/O is more suitable.\n\nYou can contact us at [support@typeform.io](mailto:support@typeform.io)."
}
[/block]
Here's a list of features from Typeform that Typeform I/O hasn't implemented yet. We aim to implement *most* of Typeform's functionality over time.
[block:parameters]
{
"data": {
"0-0": "Fields",
"2-0": "Configure panel",
"h-0": "Category",
"h-1": "Missing features",
"0-1": "Date field\nPayment field \nFile upload field \nQuestion group \nFull field customization _\\*1_",
"2-1": "Self notifications \nUser notifications \nProgress widget customization \nPrivate forms \nLanguage settings \nBranding settings \nIntegrations _\\*2_ \nCustom messages",
"1-0": "Build panel",
"1-1": "Logic jumps \nPiping \nCalculator (score and price) \nHidden fields",
"3-0": "Analyze panel",
"3-1": "Results storage _\\*3_ \nMetrics \nGoogle Analytics \nReports"
},
"cols": 2,
"rows": 4
}
[/block]
__\*1__: Except for question, description, required, and choices (on fields where applicable)
__\*2__: You could implement them manually through webhooks; see "Results"
__\*3__: We will send the results to your server directly through webhooks; see "Results"

[block:callout]
{
"type": "info",
"title": "",
"body": "Typeform I/O is for programmers and people who want to generate a lot of typeforms.\n\nTypeform.com is the version which lets you create a typeform via a friendly interface.\n\nIf you just have one form you want to send to a lot of users, you are better off using Typeform.com.\n\nIf you have one form per user, and a lot of users, Typeform I/O is more suitable.\n\nYou can contact us at [support@typeform.io](mailto:support@typeform.io)."
}
[/block]
Here's a list of features from Typeform that Typeform I/O hasn't implemented yet. We aim to implement *most* of Typeform's functionality over time.
[block:parameters]
{
"data": {
"0-0": "Fields",
"2-0": "Configure panel",
"h-0": "Category",
"h-1": "Missing features",
"0-1": "Date field\nPayment field \nFile upload field \nQuestion group \nFull field customization _\\*1_",
"2-1": "Self notifications \nUser notifications \nProgress widget customization \nPrivate forms \nLanguage settings \nBranding settings \nIntegrations _\\*2_ \nCustom messages",
"1-0": "Build panel",
"1-1": "Logic jumps \nPiping \nCalculator (score and price) \nHidden fields",
"3-0": "Analyze panel",
"3-1": "Results storage _\\*3_ \nMetrics \nGoogle Analytics \nReports"
},
"cols": 2,
"rows": 4
}
[/block]
__\*1__: Except for question, description, required, and choices (on fields where applicable)
__\*2__: You could implement them manually through webhooks; see "Results"
__\*3__: We will send the results to your server directly through webhooks; see "Results"

{"_id":"56d6cfe52417921500c4683a","createdAt":"2015-03-18T12:56:15.528Z","link_url":"","sync_unique":"","slug":"getting-started","__v":0,"project":"54f06f596210dd21004627ce","version":"56d6cfdf2417921500c4680d","hidden":false,"order":5,"body":"This introduction will teach you what Typeform I/O is, how you would use it and what you can build with it. We will go through everything from signup to successfully creating typeforms dynamically.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"What is Typeform I/O?\"\n}\n[/block]\nTypeform I/O is a form creation and rendering service. Imagine, you have a couple of questions you want to ask to your users and those questions are different, depending on the user. Instead of creating every typeform manually or building an automated service, you can use Typeform I/O to manage this for you. You will get beautiful forms that are easy to create and that your users will love to fill out!\n\nBelow you'll find a short animation that describes the typical flow of creating a typeform, sending it to the user and waiting for the user to submit the typeform so you can get a hold of the data.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/dz6uLLGmSxKvxBqQAwDp_typeform_io_beginning.gif\",\n \"typeform_io_beginning.gif\",\n \"1024\",\n \"1024\",\n \"#a8755c\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nIf you would like to include images in your typeform (for example, by using Picture Choice Field), the flow would be slightly different. Please read about the [Design endpoint](http://docs.typeform.io/v0.4/docs/images).\n\nFor the sake of this tutorial, we will be doing the examples with the Chrome extension [Postman](https://www.getpostman.com/) but you can use whatever client/GUI as you like.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Signup\"\n}\n[/block]\nThe first thing you will need to use the API is an API-key. Make sure you keep your API-key secret. Visit our [\"signup page\"](http://docs.typeform.io/page/signup) page to register for an API-key. As soon as you have the API-key, you can start using Typeform I/O.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"If you forget your API-key or your API-key has been compromised\",\n \"body\": \"We are all human beings and sometimes we make mistakes. Sometimes we even forget things! Sometimes, other people are evil and steal things from you. If these things happens to your API-key, you will have to reset your API-key.\\n\\nIn the future, you will be able to manage this by yourself, but for the time being, you will have to email support@typeform.io so we can reset your key for you.\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Authentication\"\n}\n[/block]\nWe use a simple way of doing authentication. Basically, you would use add a `X-API-TOKEN` header to your request, with the value being your API-key. \n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Test & Metadata Information\"\n}\n[/block]\nIf you want to make sure your authentication and connection to Typeform I/O works, make a `GET` request to `https://api.typeform.io/latest/`. The `/latest/` part is the version you're gonna use of the API.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -X GET https://api.typeform.io/latest/ -H \\\"X-API-TOKEN: your_api_token\\\"\",\n \"language\": \"shell\",\n \"name\": \"cURL\"\n }\n ]\n}\n[/block]\nIf your authentication is working, you should receive something similar to the metadata below. Otherwise you'll receive a 403 Forbidden.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"name\\\": \\\"Typeform I/O Build API\\\",\\n \\\"description\\\": \\\"Build API for creating forms awesomely\\\",\\n \\\"version\\\": \\\"v0.4\\\",\\n \\\"documentation\\\": \\\"https://docs.typeform.io/\\\",\\n \\\"support\\\": \\\"support@typeform.io\\\",\\n \\\"time\\\": \\\"2015-05-26 17:55:23 +0000\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Creating your first typeform\"\n}\n[/block]\nNow we get to the fun stuff, let's create a typeform that you can send to your users!\n\nThe endpoint you will use for creating forms is `https://api.typeform.io/latest/forms`. Forms is the resource you are creating. You can read more about the endpoint in our [/forms reference](http://docs.typeform.io/v0.4/docs/forms)\n\nYou make a `POST` request with the JSON example below to create a new typeform.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Parameters\",\n \"body\": \"The typeform has to have at least one title and one field in the JSON\"\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n\\t\\\"title\\\": \\\"My first typeform\\\",\\n \\\"fields\\\": [\\n {\\n \\t\\\"type\\\": \\\"short_text\\\",\\n \\\"question\\\": \\\"What is your name?\\\"\\n }\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nWe recommend using our [Sandbox application](http://docs.typeform.io/page/sandbox) or Postman for Chrome to make test requests.\n\nThe response you get from making a request containing the data above, will look something like this:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"id\\\": \\\"keEwsGeuC\\\",\\n \\\"title\\\": \\\"My first typeform\\\",\\n \\\"fields\\\": [\\n {\\n \\\"type\\\": \\\"short_text\\\",\\n \\\"question\\\": \\\"What is your name?\\\"\\n }\\n ],\\n\\t\\\"_links\\\": [\\n \\t{\\n \\t\\\"rel\\\": \\\"self\\\",\\n \\t\\\"href\\\": \\\"https://api.typeform.io/latest/forms/keEwsGeuC\\\"\\n \\t},\\n \\t{\\n \\t \\\"rel\\\": \\\"form_render\\\",\\n \\t \\\"href\\\": \\\"https://forms.typeform.io/to/keEwsGeuC\\\"\\n }\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nYou can see that two things have been added to your typeform, if you compare the request with the response.\n\n**id**\n\nThe first is an ID, it is the internal ID for your typeform. You would use in the future if you want to evaluate the typeform structure again. The ID is a SecureRandom generated string that also indicates where your users can access the typeform by going to `https://forms.typeform.io/to/ID` but instead or constructing the URL manually, try make use of the links `form_render` object that gives you the full URL for free.\n\n**_links**\n\nLinks is an array of objects that contains relevant links (also known as Hypermedia) to different resources associated to your typeform and also a link you can send your respondents to. `form_render` is the link that you will use to show the typeform for your users. You can embed the form in an iframe ([read about typeform embedding](http://docs.typeform.io/v0.4/docs/embedding-typeforms)), ask the user to navigate to the typeform or simply redirect the user.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Rendering the typeform for your users\"\n}\n[/block]\nThere are different ways of showing the typeform to your users. Depending on the context, different ways makes sense.\n\nIf you only have an email address for your user, sending the email with a link to the typeform makes most sense.\n\nIf you have a user is logged into your application, it might make more sense to display the typeform directly inside your webpage by using an `<iframe>` or using a Modal window ([read about typeform embedding](http://docs.typeform.io/docs/embedding-introduction)).","excerpt":"This is a quick introduction to Typeform I/O, how to use it and what you can do with the API","link_external":false,"githubsync":"","category":"56d6cfdf2417921500c4680f","api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"status":400,"name":"","code":"{}","language":"json"}]},"settings":"","auth":"required","params":[],"url":""},"type":"basic","title":"Getting Started","user":"54f06f1ca17a1521003180f3","updates":["559e979dc713ef0d000282bf","55b274ba88093a21008beef4","561e7399efcf8217003adfdf","56266793d0f87e190014c59e"],"childrenPages":[]}

Getting Started

This is a quick introduction to Typeform I/O, how to use it and what you can do with the API

This introduction will teach you what Typeform I/O is, how you would use it and what you can build with it. We will go through everything from signup to successfully creating typeforms dynamically.
[block:api-header]
{
"type": "basic",
"title": "What is Typeform I/O?"
}
[/block]
Typeform I/O is a form creation and rendering service. Imagine, you have a couple of questions you want to ask to your users and those questions are different, depending on the user. Instead of creating every typeform manually or building an automated service, you can use Typeform I/O to manage this for you. You will get beautiful forms that are easy to create and that your users will love to fill out!
Below you'll find a short animation that describes the typical flow of creating a typeform, sending it to the user and waiting for the user to submit the typeform so you can get a hold of the data.
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/dz6uLLGmSxKvxBqQAwDp_typeform_io_beginning.gif",
"typeform_io_beginning.gif",
"1024",
"1024",
"#a8755c",
""
]
}
]
}
[/block]
If you would like to include images in your typeform (for example, by using Picture Choice Field), the flow would be slightly different. Please read about the [Design endpoint](http://docs.typeform.io/v0.4/docs/images).
For the sake of this tutorial, we will be doing the examples with the Chrome extension [Postman](https://www.getpostman.com/) but you can use whatever client/GUI as you like.
[block:api-header]
{
"type": "basic",
"title": "Signup"
}
[/block]
The first thing you will need to use the API is an API-key. Make sure you keep your API-key secret. Visit our ["signup page"](http://docs.typeform.io/page/signup) page to register for an API-key. As soon as you have the API-key, you can start using Typeform I/O.
[block:callout]
{
"type": "warning",
"title": "If you forget your API-key or your API-key has been compromised",
"body": "We are all human beings and sometimes we make mistakes. Sometimes we even forget things! Sometimes, other people are evil and steal things from you. If these things happens to your API-key, you will have to reset your API-key.\n\nIn the future, you will be able to manage this by yourself, but for the time being, you will have to email support@typeform.io so we can reset your key for you."
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Authentication"
}
[/block]
We use a simple way of doing authentication. Basically, you would use add a `X-API-TOKEN` header to your request, with the value being your API-key.
[block:api-header]
{
"type": "basic",
"title": "Test & Metadata Information"
}
[/block]
If you want to make sure your authentication and connection to Typeform I/O works, make a `GET` request to `https://api.typeform.io/latest/`. The `/latest/` part is the version you're gonna use of the API.
[block:code]
{
"codes": [
{
"code": "curl -X GET https://api.typeform.io/latest/ -H \"X-API-TOKEN: your_api_token\"",
"language": "shell",
"name": "cURL"
}
]
}
[/block]
If your authentication is working, you should receive something similar to the metadata below. Otherwise you'll receive a 403 Forbidden.
[block:code]
{
"codes": [
{
"code": "{\n \"name\": \"Typeform I/O Build API\",\n \"description\": \"Build API for creating forms awesomely\",\n \"version\": \"v0.4\",\n \"documentation\": \"https://docs.typeform.io/\",\n \"support\": \"support@typeform.io\",\n \"time\": \"2015-05-26 17:55:23 +0000\"\n}",
"language": "json"
}
]
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Creating your first typeform"
}
[/block]
Now we get to the fun stuff, let's create a typeform that you can send to your users!
The endpoint you will use for creating forms is `https://api.typeform.io/latest/forms`. Forms is the resource you are creating. You can read more about the endpoint in our [/forms reference](http://docs.typeform.io/v0.4/docs/forms)
You make a `POST` request with the JSON example below to create a new typeform.
[block:callout]
{
"type": "warning",
"title": "Parameters",
"body": "The typeform has to have at least one title and one field in the JSON"
}
[/block]
[block:code]
{
"codes": [
{
"code": "{\n\t\"title\": \"My first typeform\",\n \"fields\": [\n {\n \t\"type\": \"short_text\",\n \"question\": \"What is your name?\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
We recommend using our [Sandbox application](http://docs.typeform.io/page/sandbox) or Postman for Chrome to make test requests.
The response you get from making a request containing the data above, will look something like this:
[block:code]
{
"codes": [
{
"code": "{\n \"id\": \"keEwsGeuC\",\n \"title\": \"My first typeform\",\n \"fields\": [\n {\n \"type\": \"short_text\",\n \"question\": \"What is your name?\"\n }\n ],\n\t\"_links\": [\n \t{\n \t\"rel\": \"self\",\n \t\"href\": \"https://api.typeform.io/latest/forms/keEwsGeuC\"\n \t},\n \t{\n \t \"rel\": \"form_render\",\n \t \"href\": \"https://forms.typeform.io/to/keEwsGeuC\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
You can see that two things have been added to your typeform, if you compare the request with the response.
**id**
The first is an ID, it is the internal ID for your typeform. You would use in the future if you want to evaluate the typeform structure again. The ID is a SecureRandom generated string that also indicates where your users can access the typeform by going to `https://forms.typeform.io/to/ID` but instead or constructing the URL manually, try make use of the links `form_render` object that gives you the full URL for free.
**_links**
Links is an array of objects that contains relevant links (also known as Hypermedia) to different resources associated to your typeform and also a link you can send your respondents to. `form_render` is the link that you will use to show the typeform for your users. You can embed the form in an iframe ([read about typeform embedding](http://docs.typeform.io/v0.4/docs/embedding-typeforms)), ask the user to navigate to the typeform or simply redirect the user.
[block:api-header]
{
"type": "basic",
"title": "Rendering the typeform for your users"
}
[/block]
There are different ways of showing the typeform to your users. Depending on the context, different ways makes sense.
If you only have an email address for your user, sending the email with a link to the typeform makes most sense.
If you have a user is logged into your application, it might make more sense to display the typeform directly inside your webpage by using an `<iframe>` or using a Modal window ([read about typeform embedding](http://docs.typeform.io/docs/embedding-introduction)).

This introduction will teach you what Typeform I/O is, how you would use it and what you can build with it. We will go through everything from signup to successfully creating typeforms dynamically.
[block:api-header]
{
"type": "basic",
"title": "What is Typeform I/O?"
}
[/block]
Typeform I/O is a form creation and rendering service. Imagine, you have a couple of questions you want to ask to your users and those questions are different, depending on the user. Instead of creating every typeform manually or building an automated service, you can use Typeform I/O to manage this for you. You will get beautiful forms that are easy to create and that your users will love to fill out!
Below you'll find a short animation that describes the typical flow of creating a typeform, sending it to the user and waiting for the user to submit the typeform so you can get a hold of the data.
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/dz6uLLGmSxKvxBqQAwDp_typeform_io_beginning.gif",
"typeform_io_beginning.gif",
"1024",
"1024",
"#a8755c",
""
]
}
]
}
[/block]
If you would like to include images in your typeform (for example, by using Picture Choice Field), the flow would be slightly different. Please read about the [Design endpoint](http://docs.typeform.io/v0.4/docs/images).
For the sake of this tutorial, we will be doing the examples with the Chrome extension [Postman](https://www.getpostman.com/) but you can use whatever client/GUI as you like.
[block:api-header]
{
"type": "basic",
"title": "Signup"
}
[/block]
The first thing you will need to use the API is an API-key. Make sure you keep your API-key secret. Visit our ["signup page"](http://docs.typeform.io/page/signup) page to register for an API-key. As soon as you have the API-key, you can start using Typeform I/O.
[block:callout]
{
"type": "warning",
"title": "If you forget your API-key or your API-key has been compromised",
"body": "We are all human beings and sometimes we make mistakes. Sometimes we even forget things! Sometimes, other people are evil and steal things from you. If these things happens to your API-key, you will have to reset your API-key.\n\nIn the future, you will be able to manage this by yourself, but for the time being, you will have to email support@typeform.io so we can reset your key for you."
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Authentication"
}
[/block]
We use a simple way of doing authentication. Basically, you would use add a `X-API-TOKEN` header to your request, with the value being your API-key.
[block:api-header]
{
"type": "basic",
"title": "Test & Metadata Information"
}
[/block]
If you want to make sure your authentication and connection to Typeform I/O works, make a `GET` request to `https://api.typeform.io/latest/`. The `/latest/` part is the version you're gonna use of the API.
[block:code]
{
"codes": [
{
"code": "curl -X GET https://api.typeform.io/latest/ -H \"X-API-TOKEN: your_api_token\"",
"language": "shell",
"name": "cURL"
}
]
}
[/block]
If your authentication is working, you should receive something similar to the metadata below. Otherwise you'll receive a 403 Forbidden.
[block:code]
{
"codes": [
{
"code": "{\n \"name\": \"Typeform I/O Build API\",\n \"description\": \"Build API for creating forms awesomely\",\n \"version\": \"v0.4\",\n \"documentation\": \"https://docs.typeform.io/\",\n \"support\": \"support@typeform.io\",\n \"time\": \"2015-05-26 17:55:23 +0000\"\n}",
"language": "json"
}
]
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Creating your first typeform"
}
[/block]
Now we get to the fun stuff, let's create a typeform that you can send to your users!
The endpoint you will use for creating forms is `https://api.typeform.io/latest/forms`. Forms is the resource you are creating. You can read more about the endpoint in our [/forms reference](http://docs.typeform.io/v0.4/docs/forms)
You make a `POST` request with the JSON example below to create a new typeform.
[block:callout]
{
"type": "warning",
"title": "Parameters",
"body": "The typeform has to have at least one title and one field in the JSON"
}
[/block]
[block:code]
{
"codes": [
{
"code": "{\n\t\"title\": \"My first typeform\",\n \"fields\": [\n {\n \t\"type\": \"short_text\",\n \"question\": \"What is your name?\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
We recommend using our [Sandbox application](http://docs.typeform.io/page/sandbox) or Postman for Chrome to make test requests.
The response you get from making a request containing the data above, will look something like this:
[block:code]
{
"codes": [
{
"code": "{\n \"id\": \"keEwsGeuC\",\n \"title\": \"My first typeform\",\n \"fields\": [\n {\n \"type\": \"short_text\",\n \"question\": \"What is your name?\"\n }\n ],\n\t\"_links\": [\n \t{\n \t\"rel\": \"self\",\n \t\"href\": \"https://api.typeform.io/latest/forms/keEwsGeuC\"\n \t},\n \t{\n \t \"rel\": \"form_render\",\n \t \"href\": \"https://forms.typeform.io/to/keEwsGeuC\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
You can see that two things have been added to your typeform, if you compare the request with the response.
**id**
The first is an ID, it is the internal ID for your typeform. You would use in the future if you want to evaluate the typeform structure again. The ID is a SecureRandom generated string that also indicates where your users can access the typeform by going to `https://forms.typeform.io/to/ID` but instead or constructing the URL manually, try make use of the links `form_render` object that gives you the full URL for free.
**_links**
Links is an array of objects that contains relevant links (also known as Hypermedia) to different resources associated to your typeform and also a link you can send your respondents to. `form_render` is the link that you will use to show the typeform for your users. You can embed the form in an iframe ([read about typeform embedding](http://docs.typeform.io/v0.4/docs/embedding-typeforms)), ask the user to navigate to the typeform or simply redirect the user.
[block:api-header]
{
"type": "basic",
"title": "Rendering the typeform for your users"
}
[/block]
There are different ways of showing the typeform to your users. Depending on the context, different ways makes sense.
If you only have an email address for your user, sending the email with a link to the typeform makes most sense.
If you have a user is logged into your application, it might make more sense to display the typeform directly inside your webpage by using an `<iframe>` or using a Modal window ([read about typeform embedding](http://docs.typeform.io/docs/embedding-introduction)).

{"_id":"56d6cfe32417921500c4682e","githubsync":"","hidden":false,"project":"54f06f596210dd21004627ce","slug":"base","sync_unique":"","api":{"results":{"codes":[{"name":"","code":"{\n\t\"name\": \"Typeform I/O Build API\",\n \"description\": \"Build API for creating forms awesomely\",\n \"version\": \"v0.4\",\n \"documentation\": \"typeform.io/docs\",\n \"support\": \"support@typeform.io\",\n \"time: \"2014-03-18 12:07:10\"\n}","language":"json","status":200}]},"settings":"","url":"/","auth":"never","examples":{"codes":[{"code":"","language":"text"}]},"method":"get","params":[]},"excerpt":"","version":"56d6cfdf2417921500c4680d","category":"56d6cfdf2417921500c46810","link_external":false,"order":7,"body":"The base endpoint response contains information about the API. It is useful for testing or making sure you have access. \n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Authentication\",\n \"body\": \"Just like every endpoint in the API, the base endpoint requires you to authenticate. If you haven't, read our [documentation on how to authenticate your API requests](doc:authentication).\"\n}\n[/block]","link_url":"","type":"get","updates":["56bb8c4eb234da21004195af"],"user":"54f06f1ca17a1521003180f3","__v":0,"createdAt":"2015-03-18T11:12:23.317Z","title":"base","childrenPages":[]}

getbase

The base endpoint response contains information about the API. It is useful for testing or making sure you have access.
[block:callout]
{
"type": "info",
"title": "Authentication",
"body": "Just like every endpoint in the API, the base endpoint requires you to authenticate. If you haven't, read our [documentation on how to authenticate your API requests](doc:authentication)."
}
[/block]

Definition

{{ api_url }}{{ page_api_url }}

Result Format

The base endpoint response contains information about the API. It is useful for testing or making sure you have access.
[block:callout]
{
"type": "info",
"title": "Authentication",
"body": "Just like every endpoint in the API, the base endpoint requires you to authenticate. If you haven't, read our [documentation on how to authenticate your API requests](doc:authentication)."
}
[/block]

{"_id":"56d6cfe32417921500c4682f","category":"56d6cfdf2417921500c46810","createdAt":"2015-03-15T21:50:32.630Z","editedParams":true,"githubsync":"","link_external":false,"order":8,"sync_unique":"","api":{"auth":"required","examples":{"codes":[{"code":"{\n \"title\": \"My new Typeform\",\n \"tags\": [\"first-forms\"],\n \"webhook_submit_url\": \"http://example.com/webhook\",\n \"fields\": [\n {\n \"type\": \"short_text\",\n \"question\": \"How is the weather down in Barcelona today?\"\n }\n ]\n}","name":"","language":"json"}]},"method":"post","params":[{"desc":"The title of the typeform","default":"NULL","type":"string","name":"title","in":"body","_id":"55095ab51c38c50d006118ed","required":true},{"type":"array_mixed","name":"fields","in":"body","_id":"55095ab51c38c50d006118ec","required":true,"desc":"An array of Field objects","default":"[]"},{"_id":"55e042636bad670d0081f212","required":false,"desc":"An array of Tags","default":"[]","type":"array_string","name":"tags","in":"body"},{"_id":"5547991d6807510d00b46969","required":false,"desc":"The ID of the Design object you want to use","default":"NULL","type":"string","name":"design_id","in":"body"},{"_id":"5511ea7bc1b13537009f5cee","required":false,"desc":"Where you want the responses to go to when a respondent submits the typeform","default":"","type":"string","name":"webhook_submit_url","in":"body"},{"in":"body","_id":"565f226e413e06170093de79","required":false,"desc":"The IDs of the URLs you want your form to be displayed at","default":"A randomly generated URL","type":"array_string","name":"url_ids"},{"default":"true","type":"boolean","name":"branding","in":"body","_id":"56d6d0c536dd840b00cef013","required":false,"desc":"Enables or disables the Typeform branding for the form"}],"results":{"codes":[{"status":201,"language":"json","code":"{\n \"id\": \"BRSgoNH6vdLBZw\",\n \"title\": \"My new Typeform\",\n \"tags\": [\"first-forms\"],\n \"webhook_submit_url\": \"http://example.com/webhook\",\n \"fields\": [\n {\n \"id\": 3439,\n \"type\": \"short_text\",\n \"question\": \"How is the weather down in Barcelona today?\"\n }\n ],\n \"urls\": [\n {\n \"id\": \"hJ4tEqGWXF0qzr\",\n \"form_id\": \"BRSgoNH6vdLBZw\",\n \"version\": \"v0.4\"\n }\n ],\n \"_links\": [\n {\n \"rel\": \"self\",\n \"href\": \"https://api.typeform.io/latest/forms/BRSgoNH6vdLBZw\"\n },\n {\n \"rel\": \"url\",\n \"href\": \"https://api.typeform.io/latest/urls/hJ4tEqGWXF0qzr\"\n },\n {\n \"rel\": \"form_render\",\n \"href\": \"https://forms.typeform.io/to/hJ4tEqGWXF0qzr\"\n }\n ],\n \"version\": \"v0.4\"\n}","name":""}]},"settings":"","url":"/forms"},"user":"54f06f1ca17a1521003180f3","link_url":"","project":"54f06f596210dd21004627ce","slug":"forms","body":"The form endpoint is the main endpoint that you will be dealing with. It is the endpoint you use to create new typeforms. You have parameters to set the title, webhook URL and of course, the fields. The form endpoint will also return you a hash of URLs that you can use to distribute your typeform or delete it.","excerpt":"","title":"forms","updates":["570be4c19ca0ae1700fdb5b2"],"version":"56d6cfdf2417921500c4680d","editedParams2":true,"hidden":false,"isReference":false,"type":"post","__v":2,"childrenPages":[]}

postforms

Body Params

title:

required

stringNULL

The title of the typeform

fields:

required

array of mixed[]

An array of Field objects

tags:

array of strings[]

An array of Tags

design_id:

stringNULL

The ID of the Design object you want to use

webhook_submit_url:

string

Where you want the responses to go to when a respondent submits the typeform

url_ids:

array of stringsA randomly generated URL

The IDs of the URLs you want your form to be displayed at

branding:

booleantrue

Enables or disables the Typeform branding for the form

The form endpoint is the main endpoint that you will be dealing with. It is the endpoint you use to create new typeforms. You have parameters to set the title, webhook URL and of course, the fields. The form endpoint will also return you a hash of URLs that you can use to distribute your typeform or delete it.

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format

The form endpoint is the main endpoint that you will be dealing with. It is the endpoint you use to create new typeforms. You have parameters to set the title, webhook URL and of course, the fields. The form endpoint will also return you a hash of URLs that you can use to distribute your typeform or delete it.

getforms/:form_id

Definition

{{ api_url }}{{ page_api_url }}

Result Format

This is the endpoint you would use to get the structure back of a typeform.

{"_id":"56d6cfe32417921500c46831","isReference":false,"__v":0,"createdAt":"2015-03-15T21:51:14.516Z","githubsync":"","hidden":false,"updates":[],"version":"56d6cfdf2417921500c4680d","editedParams2":true,"link_external":false,"link_url":"","project":"54f06f596210dd21004627ce","type":"post","api":{"examples":{"codes":[{"name":"","language":"json","code":"{\n\t\"url\": \"http://example.com/original_img.png\"\n}"}]},"method":"post","params":[{"name":"url","ref":"","required":true,"type":"string","in":"body","_id":"551bccdf944d6b2f00479d89","default":"","desc":"The url of the string"}],"results":{"codes":[{"status":200,"name":"","code":"{\n \"id\": \"RmjsH92Zps4VvW\", \n \"original_url\": \"http://example.com/original_img.png\", \n \"type\": \"choice\",\n \"version\": \"v0.4\"\n}\n","language":"json"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","url":"/images","auth":"required"},"body":"Due to existing constraints, we cannot process all images on the fly when creating typeforms containing the 'Picture Choice' question type. Therefore, we provide an endpoint for creating images for Picture Choices before creating your typeform.\n\nTypeforms can also have a background image and fields can have images below the question text. This will require you to follow the same process as with Picture Choices and then reuse the images when creating the form. \n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Background and Field images\",\n \"body\": \"We are still working on this feature. We would love to get any feedback about how you see it fit your needs. You can contact us at [support@typeform.io](mailto:support@typeform.io).\"\n}\n[/block]","editedParams":true,"order":10,"sync_unique":"","category":"56d6cfdf2417921500c46810","excerpt":"","slug":"images","title":"images","user":"54f06f1ca17a1521003180f3","childrenPages":[]}

postimages

Body Params

url:

required

string

The url of the string

Due to existing constraints, we cannot process all images on the fly when creating typeforms containing the 'Picture Choice' question type. Therefore, we provide an endpoint for creating images for Picture Choices before creating your typeform.
Typeforms can also have a background image and fields can have images below the question text. This will require you to follow the same process as with Picture Choices and then reuse the images when creating the form.
[block:callout]
{
"type": "warning",
"title": "Background and Field images",
"body": "We are still working on this feature. We would love to get any feedback about how you see it fit your needs. You can contact us at [support@typeform.io](mailto:support@typeform.io)."
}
[/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format

Due to existing constraints, we cannot process all images on the fly when creating typeforms containing the 'Picture Choice' question type. Therefore, we provide an endpoint for creating images for Picture Choices before creating your typeform.
Typeforms can also have a background image and fields can have images below the question text. This will require you to follow the same process as with Picture Choices and then reuse the images when creating the form.
[block:callout]
{
"type": "warning",
"title": "Background and Field images",
"body": "We are still working on this feature. We would love to get any feedback about how you see it fit your needs. You can contact us at [support@typeform.io](mailto:support@typeform.io)."
}
[/block]

{"_id":"56d6cfe32417921500c46832","api":{"method":"get","params":[],"results":{"codes":[{"code":"{\n \"filename\": \"choice-d3Pr766Q2ZjyVyS9QnnM7WUfS9F6QsAv-default\", \n \"height\": 230, \n \"id\": \"BdWe856bUv\", \n \"type\": \"choice\", \n \"url\": \"http://foobar\", \n \"version\": \"v0.4\", \n \"width\": 230\n}","language":"json","status":200,"name":""}]},"settings":"","url":"/images/:image_id","auth":"required","examples":{"codes":[{"language":"text","code":""}]}},"createdAt":"2015-12-14T10:18:15.211Z","link_url":"","title":"images/:image_id","user":"54f47632a510f81900ac1a0d","version":"56d6cfdf2417921500c4680d","__v":0,"category":"56d6cfdf2417921500c46810","githubsync":"","order":11,"body":"This is the endpoint you would use to get the structure back of an image.","hidden":false,"link_external":false,"type":"get","updates":[],"excerpt":"","project":"54f06f596210dd21004627ce","slug":"imagesimage_id","sync_unique":"","childrenPages":[]}

getimages/:image_id

This is the endpoint you would use to get the structure back of an image.

{"_id":"56d6cfe32417921500c46834","excerpt":"","hidden":false,"type":"get","user":"566e9498e61c1917005aa118","slug":"designsdesign_id","title":"designs/:design_id","version":"56d6cfdf2417921500c4680d","__v":0,"body":"This is the endpoint you would use to get the definition back of a design.","createdAt":"2015-12-14T10:19:53.968Z","link_external":false,"order":13,"category":"56d6cfdf2417921500c46810","updates":[],"api":{"auth":"required","examples":{"codes":[{"language":"text","code":""}]},"method":"get","params":[],"results":{"codes":[{"status":200,"name":"","code":"{\n \"id\": \"9EcTEjpH3g\",\n \"colors\": {\n \"answer\": \"#001122\",\n \"background\": \"#aabbcc\",\n \"button\": \"#000000\",\n \"question\": \"#ffffff\"\n },\n \"font\": \"Source Sans Pro\",\n \"version\": \"v0.4\"\n}","language":"json"}]},"settings":"","url":"/designs/:design_id"},"githubsync":"","link_url":"","project":"54f06f596210dd21004627ce","sync_unique":"","childrenPages":[]}

getdesigns/:design_id

This is the endpoint you would use to get the definition back of a design.

puturls/:url_id

Body Params

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format

This url endpoint changes an existing URL to link to a different typeform.

{"_id":"572a2895d10a200e00b1cb11","title":"urls/:url_id","updates":[],"user":"54f47632a510f81900ac1a0d","githubsync":"","hidden":false,"link_url":"","project":"54f06f596210dd21004627ce","api":{"method":"delete","params":[],"results":{"codes":[{"name":"","code":"","language":"json","status":204}]},"settings":"","url":"/urls/:url_id","auth":"required","examples":{"codes":[{"code":"","language":"text"}]}},"category":"56d6cfdf2417921500c46810","createdAt":"2016-05-04T16:51:33.610Z","isReference":false,"order":999,"type":"delete","__v":0,"body":"This is the endpoint you would use to delete a URL that links to a typeform.","slug":"urlsurl_id-2","sync_unique":"","version":"56d6cfdf2417921500c4680d","excerpt":"","link_external":false,"childrenPages":[]}

deleteurls/:url_id

This is the endpoint you would use to delete a URL that links to a typeform.

{"_id":"56d6cfe42417921500c46838","githubsync":"","isReference":false,"link_external":false,"slug":"results-introduction","type":"basic","user":"54f06f1ca17a1521003180f3","__v":2,"body":"Typeform I/O does not store results. Instead, when a respondent completes your typeform, we send the results directly to you (i.e. your server) via **webhooks**.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Still in development\",\n \"body\": \"We are exploring other options for results handling *as well as* webhooks, and it is likely we will implement storage in the future. We would love to get your feedback or suggestions on what would fit your needs best! \\n\\nYou can contact us at [support@typeform.io](mailto:support@typeform.io).\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Using the Webhook\"\n}\n[/block]\nWhen you create a typeform, you must specify a `webhook_submit_url` in the JSON payload of your request.\n\nWhenever someone completes your typeform and presses the submit button, the webhook fires and we make an HTTP POST request to the URL you specified, containing your results.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"What if the Webhook Fails?\"\n}\n[/block]\nIf the webhook request fails for any reason, we will retry the request to your endpoint URL at 30 minute intervals for at least 1 full day (60 retries).\n\nWhen we hit your endpoint, we make sure the request is successful by looking at the status code in the response. If you reply a non-2XX status code, we will continue retrying. And if no successful requests have been made after 1 full day (60 retries), we will drop the response and **you will lose your data**.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"This configuration is not final\",\n \"body\": \"We are exploring options for handling webhook failure scenarios (e.g. an exponential backoff instead, results storage etc.). If you have any thoughts or suggestions on this topic, please let us know!\\n\\nYou can contact us at [support@typeform.io](mailto:support@typeform.io).\"\n}\n[/block]\nPlease note: We might hit your endpoint more than once (but at least once) and your endpoint should support this. You can use the `token` attribute of each response to check for uniqueness, and dismiss any duplicate responses.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Example Result\",\n \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"\",\n \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"AbCdEfGhIj\\\",\\n \\\"token\\\": \\\"440d47cd38ed9234a45cd160649f2203\\\",\\n \\\"answers\\\": [\\n {\\n \\\"field_id\\\": 1,\\n \\\"type\\\": \\\"number\\\",\\n \\\"value\\\": {\\n \\\"amount\\\": 3\\n }\\n },\\n {\\n \\\"field_id\\\": 2,\\n \\\"type\\\": \\\"text\\\",\\n \\\"value\\\": \\\"Hi there!\\\"\\n },\\n {\\n \\\"field_id\\\": 3,\\n \\\"type\\\": \\\"rating\\\",\\n \\\"value\\\": {\\n \\\"amount\\\": 3,\\n \\\"from\\\": 1,\\n \\\"to\\\": 5\\n }\\n },\\n {\\n \\\"field_id\\\": 4,\\n \\\"type\\\": \\\"choice\\\",\\n \\\"value\\\": {\\n \\\"label\\\": \\\"Selected option\\\",\\n }\\n }\\n ]\\n}\\n\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","createdAt":"2015-03-31T11:03:12.775Z","link_url":"","order":31,"project":"54f06f596210dd21004627ce","updates":["551abc7132be7721001aef3f"],"api":{"auth":"required","params":[],"results":{"codes":[{"code":"{}","language":"json","status":200,"name":""},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","url":""},"category":"56d6cfdf2417921500c46812","excerpt":"","sync_unique":"","title":"Results - Introduction","version":"56d6cfdf2417921500c4680d","hidden":false,"childrenPages":[]}

Results - Introduction

Typeform I/O does not store results. Instead, when a respondent completes your typeform, we send the results directly to you (i.e. your server) via **webhooks**.
[block:callout]
{
"type": "info",
"title": "Still in development",
"body": "We are exploring other options for results handling *as well as* webhooks, and it is likely we will implement storage in the future. We would love to get your feedback or suggestions on what would fit your needs best! \n\nYou can contact us at [support@typeform.io](mailto:support@typeform.io)."
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Using the Webhook"
}
[/block]
When you create a typeform, you must specify a `webhook_submit_url` in the JSON payload of your request.
Whenever someone completes your typeform and presses the submit button, the webhook fires and we make an HTTP POST request to the URL you specified, containing your results.
[block:api-header]
{
"type": "basic",
"title": "What if the Webhook Fails?"
}
[/block]
If the webhook request fails for any reason, we will retry the request to your endpoint URL at 30 minute intervals for at least 1 full day (60 retries).
When we hit your endpoint, we make sure the request is successful by looking at the status code in the response. If you reply a non-2XX status code, we will continue retrying. And if no successful requests have been made after 1 full day (60 retries), we will drop the response and **you will lose your data**.
[block:callout]
{
"type": "info",
"title": "This configuration is not final",
"body": "We are exploring options for handling webhook failure scenarios (e.g. an exponential backoff instead, results storage etc.). If you have any thoughts or suggestions on this topic, please let us know!\n\nYou can contact us at [support@typeform.io](mailto:support@typeform.io)."
}
[/block]
Please note: We might hit your endpoint more than once (but at least once) and your endpoint should support this. You can use the `token` attribute of each response to check for uniqueness, and dismiss any duplicate responses.
[block:api-header]
{
"type": "basic",
"title": "Example Result",
"sidebar": true
}
[/block]
[block:textarea]
{
"text": "",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "{\n \"uid\": \"AbCdEfGhIj\",\n \"token\": \"440d47cd38ed9234a45cd160649f2203\",\n \"answers\": [\n {\n \"field_id\": 1,\n \"type\": \"number\",\n \"value\": {\n \"amount\": 3\n }\n },\n {\n \"field_id\": 2,\n \"type\": \"text\",\n \"value\": \"Hi there!\"\n },\n {\n \"field_id\": 3,\n \"type\": \"rating\",\n \"value\": {\n \"amount\": 3,\n \"from\": 1,\n \"to\": 5\n }\n },\n {\n \"field_id\": 4,\n \"type\": \"choice\",\n \"value\": {\n \"label\": \"Selected option\",\n }\n }\n ]\n}\n",
"language": "json"
}
],
"sidebar": true
}
[/block]

{"_id":"56d6cfe22417921500c46828","category":"56d6cfdf2417921500c46813","createdAt":"2015-08-28T10:55:15.750Z","link_external":false,"sync_unique":"","slug":"tagging-introduction","title":"Tagging - Introduction","project":"54f06f596210dd21004627ce","updates":["562006b718d75b1700b2529f"],"link_url":"","githubsync":"","order":33,"body":"Tagging enables you to attach identifiers to your forms and fields, which will then be sent back to you in the results / webhook request. This gives you a simple way to add any extra information you want, in order to group forms or questions together by context, for example, or to keep track of connections between similar questions across many separate typeforms.\n\nHere's an example of a JSON payload for a form which uses tagging:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"title\\\": \\\"Form with tagging\\\",\\n \\\"tags\\\": [\\\"much-form\\\", \\\"so-tags\\\"],\\n \\\"fields\\\": [\\n {\\n \\\"type\\\": \\\"yes_no\\\",\\n \\\"question\\\": \\\"This is the best 1-question form ever, right?\\\",\\n \\\"tags\\\": [\\\"leading-questions\\\", \\\"forgone-conclusions\\\"]\\n }\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nOnce this form has been created, and a respondent presses the submit button, the webhook request would look like this:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"id\\\": \\\"aBc123\\\",\\n \\\"tags\\\": [\\\"much-form\\\", \\\"so-tags\\\"],\\n \\\"token\\\": \\\"5b5d6bc20b40138d72476f1301b4c716\\\",\\n \\\"answers\\\": [\\n {\\n \\\"field_id\\\": \\\"123456789\\\",\\n \\\"type\\\": \\\"boolean\\\",\\n \\\"value\\\": true,\\n \\\"tags\\\": [\\\"leading-questions\\\", \\\"forgone-conclusions\\\"]\\n }\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Tag Validation\",\n \"body\": \"The tag itself has to pass the following Regex `\\\"^[a-zA-Z0-9\\\\\\\\-_:]+$\\\"`, which basically says it has to be an alphanumeric string, including no other special characters than `-` (dash), `_` (underscore) or `:` (colon).\"\n}\n[/block]","__v":0,"user":"54f06f1ca17a1521003180f3","version":"56d6cfdf2417921500c4680d","hidden":false,"api":{"results":{"codes":[{"code":"{}","language":"json","status":200,"name":""},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"type":"basic","excerpt":"","childrenPages":[]}

Tagging - Introduction

Tagging enables you to attach identifiers to your forms and fields, which will then be sent back to you in the results / webhook request. This gives you a simple way to add any extra information you want, in order to group forms or questions together by context, for example, or to keep track of connections between similar questions across many separate typeforms.
Here's an example of a JSON payload for a form which uses tagging:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"Form with tagging\",\n \"tags\": [\"much-form\", \"so-tags\"],\n \"fields\": [\n {\n \"type\": \"yes_no\",\n \"question\": \"This is the best 1-question form ever, right?\",\n \"tags\": [\"leading-questions\", \"forgone-conclusions\"]\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
Once this form has been created, and a respondent presses the submit button, the webhook request would look like this:
[block:code]
{
"codes": [
{
"code": "{\n \"id\": \"aBc123\",\n \"tags\": [\"much-form\", \"so-tags\"],\n \"token\": \"5b5d6bc20b40138d72476f1301b4c716\",\n \"answers\": [\n {\n \"field_id\": \"123456789\",\n \"type\": \"boolean\",\n \"value\": true,\n \"tags\": [\"leading-questions\", \"forgone-conclusions\"]\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Tag Validation",
"body": "The tag itself has to pass the following Regex `\"^[a-zA-Z0-9\\\\-_:]+$\"`, which basically says it has to be an alphanumeric string, including no other special characters than `-` (dash), `_` (underscore) or `:` (colon)."
}
[/block]

Tagging enables you to attach identifiers to your forms and fields, which will then be sent back to you in the results / webhook request. This gives you a simple way to add any extra information you want, in order to group forms or questions together by context, for example, or to keep track of connections between similar questions across many separate typeforms.
Here's an example of a JSON payload for a form which uses tagging:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"Form with tagging\",\n \"tags\": [\"much-form\", \"so-tags\"],\n \"fields\": [\n {\n \"type\": \"yes_no\",\n \"question\": \"This is the best 1-question form ever, right?\",\n \"tags\": [\"leading-questions\", \"forgone-conclusions\"]\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
Once this form has been created, and a respondent presses the submit button, the webhook request would look like this:
[block:code]
{
"codes": [
{
"code": "{\n \"id\": \"aBc123\",\n \"tags\": [\"much-form\", \"so-tags\"],\n \"token\": \"5b5d6bc20b40138d72476f1301b4c716\",\n \"answers\": [\n {\n \"field_id\": \"123456789\",\n \"type\": \"boolean\",\n \"value\": true,\n \"tags\": [\"leading-questions\", \"forgone-conclusions\"]\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Tag Validation",
"body": "The tag itself has to pass the following Regex `\"^[a-zA-Z0-9\\\\-_:]+$\"`, which basically says it has to be an alphanumeric string, including no other special characters than `-` (dash), `_` (underscore) or `:` (colon)."
}
[/block]

{"_id":"56d6cfe12417921500c46827","link_external":false,"sync_unique":"","title":"Logic Jumps - Introduction","githubsync":"","order":34,"body":"[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"What is a Logic Jump?\"\n}\n[/block]\nA Logic Jump is a way to control the flow of a typeform based on the answers your respondent gives to specific questions. In other words, depending on their answer(s), you can *jump* to a specific location in the form, skipping out various questions or statements.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Using Logic Jumps\"\n}\n[/block]\nWhen you create a Logic Jump, you specify:\n\n1. The field which the form will jump *from* (the origin field).\n2. The field which the form will jump *to* (the destination field).\n3. The condition (on the origin field) which will trigger this jump.\n\nWhen the respondent gives their answer to the origin field, the next field is decided based on the condition(s).\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Current Limitations\",\n \"body\": \"**For now, the origin field must be a** `yes_no` **field, and the logic condition on it must be a boolean.** This is a very early (MVP) implementation of logic jumps: more complex conditions will be possible in the future, based on more field types!\",\n \"sidebar\": true\n}\n[/block]\nIn order to use Logic Jumps, the fields you jump from and to must be given a unique reference `\"ref\": \"something-unique\"`. Note: you can have several jumps point to, or from, the same reference.\n\nLogic Jumps can go forwards (skipping over fields) or backwards (rewinding to a previous field). When jumping forwards, the fields which are skipped are effectively **removed from the form's flow**. When jumping backwards, the skipped fields remain in place and the form will simply scroll upwards to the destination field.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Some backwards jumps are invalid\",\n \"body\": \"Please note: you cannot jump backwards to a field which has been skipped (and removed from the form's flow). If you send us a JSON payload for a form which attempts to do this, you will receive an error.\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Properties\"\n}\n[/block]\n**All properties are required**.\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Property\",\n \"h-1\": \"Description\",\n \"h-2\": \"Type\",\n \"0-0\": \"from\",\n \"0-1\": \"The reference (`ref`) of the origin field (to jump from). **For now, this must be a `yes_no` field**.\",\n \"1-0\": \"to\",\n \"1-1\": \"The reference (`ref`) of the destination field (to jump to).\",\n \"2-0\": \"if\",\n \"2-1\": \"The answer condition (on the origin field) which should trigger this jump.\",\n \"0-2\": \"string\",\n \"1-2\": \"string\",\n \"2-2\": \"boolean\"\n },\n \"cols\": 3,\n \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Example\"\n}\n[/block]\nHere's a sample JSON payload of a form with Logic Jumps:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"title\\\": \\\"Form with Logic Jumps\\\",\\n \\\"fields\\\": [\\n {\\n \\\"type\\\": \\\"yes_no\\\",\\n \\\"question\\\": \\\"Do you want to skip directly to the cool field?\\\",\\n \\\"ref\\\": \\\"yesno-skip-to-cool-field\\\"\\n },\\n {\\n \\\"type\\\": \\\"statement\\\",\\n \\\"question\\\": \\\"The uncool field appreciates that you didn't skip over it.\\\"\\n },\\n {\\n \\\"type\\\": \\\"statement\\\",\\n \\\"question\\\": \\\"This field is cool.\\\",\\n \\\"ref\\\": \\\"cool-field\\\"\\n }\\n ],\\n \\\"logic_jumps\\\": [\\n {\\n \\\"from\\\": \\\"yesno-skip-to-cool-field\\\",\\n \\\"to\\\": \\\"cool-field\\\",\\n \\\"if\\\": true\\n }\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"success\",\n \"body\": \"The fields reference name (`\\\"ref\\\"`) has to match the regular expression `^[a-zA-Z0-9\\\\-_:]+$`, which means it has to be an alphanumeric string, not including special characters other than `-` (dash), `_` (underscore) or `:` (colon).\",\n \"title\": \"Reference validation\"\n}\n[/block]","type":"basic","user":"54f47632a510f81900ac1a0d","createdAt":"2015-09-16T17:31:46.767Z","link_url":"","__v":0,"slug":"logic-jumps","category":"56d6cfdf2417921500c46814","version":"56d6cfdf2417921500c4680d","api":{"auth":"required","params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"excerpt":"","project":"54f06f596210dd21004627ce","updates":["5620ea397c515c0d008eee38"],"hidden":false,"childrenPages":[]}

Logic Jumps - Introduction

[block:api-header]
{
"type": "basic",
"title": "What is a Logic Jump?"
}
[/block]
A Logic Jump is a way to control the flow of a typeform based on the answers your respondent gives to specific questions. In other words, depending on their answer(s), you can *jump* to a specific location in the form, skipping out various questions or statements.
[block:api-header]
{
"type": "basic",
"title": "Using Logic Jumps"
}
[/block]
When you create a Logic Jump, you specify:
1. The field which the form will jump *from* (the origin field).
2. The field which the form will jump *to* (the destination field).
3. The condition (on the origin field) which will trigger this jump.
When the respondent gives their answer to the origin field, the next field is decided based on the condition(s).
[block:callout]
{
"type": "warning",
"title": "Current Limitations",
"body": "**For now, the origin field must be a** `yes_no` **field, and the logic condition on it must be a boolean.** This is a very early (MVP) implementation of logic jumps: more complex conditions will be possible in the future, based on more field types!",
"sidebar": true
}
[/block]
In order to use Logic Jumps, the fields you jump from and to must be given a unique reference `"ref": "something-unique"`. Note: you can have several jumps point to, or from, the same reference.
Logic Jumps can go forwards (skipping over fields) or backwards (rewinding to a previous field). When jumping forwards, the fields which are skipped are effectively **removed from the form's flow**. When jumping backwards, the skipped fields remain in place and the form will simply scroll upwards to the destination field.
[block:callout]
{
"type": "warning",
"title": "Some backwards jumps are invalid",
"body": "Please note: you cannot jump backwards to a field which has been skipped (and removed from the form's flow). If you send us a JSON payload for a form which attempts to do this, you will receive an error."
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Properties"
}
[/block]
**All properties are required**.
[block:parameters]
{
"data": {
"h-0": "Property",
"h-1": "Description",
"h-2": "Type",
"0-0": "from",
"0-1": "The reference (`ref`) of the origin field (to jump from). **For now, this must be a `yes_no` field**.",
"1-0": "to",
"1-1": "The reference (`ref`) of the destination field (to jump to).",
"2-0": "if",
"2-1": "The answer condition (on the origin field) which should trigger this jump.",
"0-2": "string",
"1-2": "string",
"2-2": "boolean"
},
"cols": 3,
"rows": 3
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Example"
}
[/block]
Here's a sample JSON payload of a form with Logic Jumps:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"Form with Logic Jumps\",\n \"fields\": [\n {\n \"type\": \"yes_no\",\n \"question\": \"Do you want to skip directly to the cool field?\",\n \"ref\": \"yesno-skip-to-cool-field\"\n },\n {\n \"type\": \"statement\",\n \"question\": \"The uncool field appreciates that you didn't skip over it.\"\n },\n {\n \"type\": \"statement\",\n \"question\": \"This field is cool.\",\n \"ref\": \"cool-field\"\n }\n ],\n \"logic_jumps\": [\n {\n \"from\": \"yesno-skip-to-cool-field\",\n \"to\": \"cool-field\",\n \"if\": true\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
[block:callout]
{
"type": "success",
"body": "The fields reference name (`\"ref\"`) has to match the regular expression `^[a-zA-Z0-9\\-_:]+$`, which means it has to be an alphanumeric string, not including special characters other than `-` (dash), `_` (underscore) or `:` (colon).",
"title": "Reference validation"
}
[/block]

[block:api-header]
{
"type": "basic",
"title": "What is a Logic Jump?"
}
[/block]
A Logic Jump is a way to control the flow of a typeform based on the answers your respondent gives to specific questions. In other words, depending on their answer(s), you can *jump* to a specific location in the form, skipping out various questions or statements.
[block:api-header]
{
"type": "basic",
"title": "Using Logic Jumps"
}
[/block]
When you create a Logic Jump, you specify:
1. The field which the form will jump *from* (the origin field).
2. The field which the form will jump *to* (the destination field).
3. The condition (on the origin field) which will trigger this jump.
When the respondent gives their answer to the origin field, the next field is decided based on the condition(s).
[block:callout]
{
"type": "warning",
"title": "Current Limitations",
"body": "**For now, the origin field must be a** `yes_no` **field, and the logic condition on it must be a boolean.** This is a very early (MVP) implementation of logic jumps: more complex conditions will be possible in the future, based on more field types!",
"sidebar": true
}
[/block]
In order to use Logic Jumps, the fields you jump from and to must be given a unique reference `"ref": "something-unique"`. Note: you can have several jumps point to, or from, the same reference.
Logic Jumps can go forwards (skipping over fields) or backwards (rewinding to a previous field). When jumping forwards, the fields which are skipped are effectively **removed from the form's flow**. When jumping backwards, the skipped fields remain in place and the form will simply scroll upwards to the destination field.
[block:callout]
{
"type": "warning",
"title": "Some backwards jumps are invalid",
"body": "Please note: you cannot jump backwards to a field which has been skipped (and removed from the form's flow). If you send us a JSON payload for a form which attempts to do this, you will receive an error."
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Properties"
}
[/block]
**All properties are required**.
[block:parameters]
{
"data": {
"h-0": "Property",
"h-1": "Description",
"h-2": "Type",
"0-0": "from",
"0-1": "The reference (`ref`) of the origin field (to jump from). **For now, this must be a `yes_no` field**.",
"1-0": "to",
"1-1": "The reference (`ref`) of the destination field (to jump to).",
"2-0": "if",
"2-1": "The answer condition (on the origin field) which should trigger this jump.",
"0-2": "string",
"1-2": "string",
"2-2": "boolean"
},
"cols": 3,
"rows": 3
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Example"
}
[/block]
Here's a sample JSON payload of a form with Logic Jumps:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"Form with Logic Jumps\",\n \"fields\": [\n {\n \"type\": \"yes_no\",\n \"question\": \"Do you want to skip directly to the cool field?\",\n \"ref\": \"yesno-skip-to-cool-field\"\n },\n {\n \"type\": \"statement\",\n \"question\": \"The uncool field appreciates that you didn't skip over it.\"\n },\n {\n \"type\": \"statement\",\n \"question\": \"This field is cool.\",\n \"ref\": \"cool-field\"\n }\n ],\n \"logic_jumps\": [\n {\n \"from\": \"yesno-skip-to-cool-field\",\n \"to\": \"cool-field\",\n \"if\": true\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
[block:callout]
{
"type": "success",
"body": "The fields reference name (`\"ref\"`) has to match the regular expression `^[a-zA-Z0-9\\-_:]+$`, which means it has to be an alphanumeric string, not including special characters other than `-` (dash), `_` (underscore) or `:` (colon).",
"title": "Reference validation"
}
[/block]

{"_id":"56d6cfe02417921500c46816","githubsync":"","sync_unique":"","order":35,"slug":"embedding-introduction","user":"54f441c270dd030d00c6b1ce","version":"56d6cfdf2417921500c4680d","createdAt":"2015-03-31T11:12:06.864Z","link_url":"","hidden":false,"body":"Once your typeform has been created, the next thing you'll need to do is to include it in your webpage/application somehow.\n\nYou *can* simply send users to the typeform's URL (which you can find in the `_links` object), but it's also possible to embed the typeform in your own page, on your own domain.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"We strongly recommend you use our embed codes\",\n \"body\": \"To guarantee that your typeform embed will work well across all devices, please make sure you use the embed codes which we provide here.\"\n}\n[/block]\nThere are two main ways of embedding typeforms in your webpage.\n\n1. Launch the typeform in a modal window. \n2. Embed the typeform as a widget, directly in your webpage/application.\n\nPlease read the [Embedding Modes documentation](doc:embedding-modes) to see exactly how to use them.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Using your own embed code\",\n \"body\": \"★ If you really don't want to use our embed code, please make sure you follow these [guidelines for custom embedding](http://helpcenter.typeform.com/hc/en-us/articles/200069248-Custom-embedding).\"\n}\n[/block]\nAdditional information: when a typeform is embedded, we automatically resize its text to adapt accordingly to smaller spaces.","category":"56d6cfdf2417921500c46815","link_external":false,"excerpt":"","type":"basic","title":"Embedding - Introduction","__v":0,"updates":["552116cd430bc60d0019eea5"],"api":{"results":{"codes":[{"code":"{}","language":"json","status":200,"name":""},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"project":"54f06f596210dd21004627ce","childrenPages":[]}

Embedding - Introduction

Once your typeform has been created, the next thing you'll need to do is to include it in your webpage/application somehow.
You *can* simply send users to the typeform's URL (which you can find in the `_links` object), but it's also possible to embed the typeform in your own page, on your own domain.
[block:callout]
{
"type": "warning",
"title": "We strongly recommend you use our embed codes",
"body": "To guarantee that your typeform embed will work well across all devices, please make sure you use the embed codes which we provide here."
}
[/block]
There are two main ways of embedding typeforms in your webpage.
1. Launch the typeform in a modal window.
2. Embed the typeform as a widget, directly in your webpage/application.
Please read the [Embedding Modes documentation](doc:embedding-modes) to see exactly how to use them.
[block:callout]
{
"type": "warning",
"title": "Using your own embed code",
"body": "★ If you really don't want to use our embed code, please make sure you follow these [guidelines for custom embedding](http://helpcenter.typeform.com/hc/en-us/articles/200069248-Custom-embedding)."
}
[/block]
Additional information: when a typeform is embedded, we automatically resize its text to adapt accordingly to smaller spaces.

Once your typeform has been created, the next thing you'll need to do is to include it in your webpage/application somehow.
You *can* simply send users to the typeform's URL (which you can find in the `_links` object), but it's also possible to embed the typeform in your own page, on your own domain.
[block:callout]
{
"type": "warning",
"title": "We strongly recommend you use our embed codes",
"body": "To guarantee that your typeform embed will work well across all devices, please make sure you use the embed codes which we provide here."
}
[/block]
There are two main ways of embedding typeforms in your webpage.
1. Launch the typeform in a modal window.
2. Embed the typeform as a widget, directly in your webpage/application.
Please read the [Embedding Modes documentation](doc:embedding-modes) to see exactly how to use them.
[block:callout]
{
"type": "warning",
"title": "Using your own embed code",
"body": "★ If you really don't want to use our embed code, please make sure you follow these [guidelines for custom embedding](http://helpcenter.typeform.com/hc/en-us/articles/200069248-Custom-embedding)."
}
[/block]
Additional information: when a typeform is embedded, we automatically resize its text to adapt accordingly to smaller spaces.

{"_id":"56d6cfe02417921500c46818","user":"54f06f1ca17a1521003180f3","updates":[],"githubsync":"","sync_unique":"","body":"There is currently one `form-submit` event that is sent to the parent frame (if there is one) when the respondent finishes your typeform and presses the \"Submit\" button. The event is only sent if it's a successful submit. It's not sent when the user have validation errors in the form or the network connection dies while filling out the form.\n\nWhen you have a typeform embedded on your webpage, it will send the `form-submit` to your `window` object when a form is submitted. Take a look at the `.originalEvent.data` property of the event, where the type of the event is declared.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$(document).ready(function() {\\n $(window).on('message', function(ev) {\\n if(ev.originalEvent.data === \\\"form-submit\\\") {\\n console.log('Form was submitted now!');\\n }\\n });\\n});\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\nTo see a demo of how this can help you build you application, please take a look at the following application: http://typeformio.github.io/form-submit-demo/\n\nThe source to this demo can be found here: https://github.com/TypeformIO/form-submit-demo","slug":"events","version":"56d6cfdf2417921500c4680d","createdAt":"2015-08-31T08:37:53.021Z","link_external":false,"hidden":false,"excerpt":"","category":"56d6cfdf2417921500c46815","type":"basic","title":"Embedding - Events","project":"54f06f596210dd21004627ce","link_url":"","api":{"params":[],"url":"","results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required"},"order":37,"__v":0,"childrenPages":[]}

Embedding - Events

There is currently one `form-submit` event that is sent to the parent frame (if there is one) when the respondent finishes your typeform and presses the "Submit" button. The event is only sent if it's a successful submit. It's not sent when the user have validation errors in the form or the network connection dies while filling out the form.
When you have a typeform embedded on your webpage, it will send the `form-submit` to your `window` object when a form is submitted. Take a look at the `.originalEvent.data` property of the event, where the type of the event is declared.
[block:code]
{
"codes": [
{
"code": "$(document).ready(function() {\n $(window).on('message', function(ev) {\n if(ev.originalEvent.data === \"form-submit\") {\n console.log('Form was submitted now!');\n }\n });\n});",
"language": "javascript"
}
]
}
[/block]
To see a demo of how this can help you build you application, please take a look at the following application: http://typeformio.github.io/form-submit-demo/
The source to this demo can be found here: https://github.com/TypeformIO/form-submit-demo

There is currently one `form-submit` event that is sent to the parent frame (if there is one) when the respondent finishes your typeform and presses the "Submit" button. The event is only sent if it's a successful submit. It's not sent when the user have validation errors in the form or the network connection dies while filling out the form.
When you have a typeform embedded on your webpage, it will send the `form-submit` to your `window` object when a form is submitted. Take a look at the `.originalEvent.data` property of the event, where the type of the event is declared.
[block:code]
{
"codes": [
{
"code": "$(document).ready(function() {\n $(window).on('message', function(ev) {\n if(ev.originalEvent.data === \"form-submit\") {\n console.log('Form was submitted now!');\n }\n });\n});",
"language": "javascript"
}
]
}
[/block]
To see a demo of how this can help you build you application, please take a look at the following application: http://typeformio.github.io/form-submit-demo/
The source to this demo can be found here: https://github.com/TypeformIO/form-submit-demo

{"_id":"56d6d00d04712c0b0061978f","__v":1,"category":"56d6d0002417921500c4683c","createdAt":"2016-03-02T11:35:41.651Z","githubsync":"","link_url":"","sync_unique":"","type":"basic","hidden":false,"project":"54f06f596210dd21004627ce","title":"Piping - Introduction","updates":[],"version":"56d6cfdf2417921500c4680d","api":{"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","auth":"required"},"body":"Piping is a feature that makes it easy to take your respondent's answers and include them in the text of other questions.\n\nYou can use piping to:\n\n - Personalise your typeform as a respondent answers\n - Ask respondents to confirm information before submitting\n - Merge answers from multiple questions into a statement\n\nHere's an example of a JSON payload for a form which uses piping:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"title\\\": \\\"Form with piping\\\",\\n \\\"fields\\\": [\\n {\\n \\\"type\\\": \\\"short_text\\\",\\n \\\"question\\\": \\\"What is your favorite pipes store?\\\",\\n \\\"ref\\\": \\\"to_pipe\\\"\\n },\\n {\\n \\\"type\\\": \\\"short_text\\\",\\n \\\"question\\\": \\\"So {{to_pipe}} is your favorite store, why?\\\"\\n }\\n ]\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nOnce this form has been created, and a respondent fills the referenced question, its answer will appear in the place where the pipe is:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/h4DrRiyT3mGa4h8IzreE_Captura%20de%20pantalla%202016-01-26%20a%20las%2010.26.10.png\",\n \"Captura de pantalla 2016-01-26 a las 10.26.10.png\",\n \"510\",\n \"391\",\n \"#71aead\",\n \"\"\n ]\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Pipes Validation\",\n \"body\": \"When using Piping in a question, we automatically hide that question until an answer is provided to the pipe emitter question. The emitter question can not be a statement type field and must be answered in order for the typeform to materialize the question where piping is used, otherwise the typeform will end prematurely. Please make sure the piping emitter question will be answered by:\\n\\n- making it a Required question,\\n- not asking your respondents to skip it,\\n- and not offering a possibility for it to be skipped when creating your Logic Jumps.\"\n}\n[/block]","excerpt":"","link_external":false,"order":999,"slug":"piping-introduction","user":"566e9498e61c1917005aa118","childrenPages":[]}

Piping - Introduction

Piping is a feature that makes it easy to take your respondent's answers and include them in the text of other questions.
You can use piping to:
- Personalise your typeform as a respondent answers
- Ask respondents to confirm information before submitting
- Merge answers from multiple questions into a statement
Here's an example of a JSON payload for a form which uses piping:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"Form with piping\",\n \"fields\": [\n {\n \"type\": \"short_text\",\n \"question\": \"What is your favorite pipes store?\",\n \"ref\": \"to_pipe\"\n },\n {\n \"type\": \"short_text\",\n \"question\": \"So {{to_pipe}} is your favorite store, why?\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
Once this form has been created, and a respondent fills the referenced question, its answer will appear in the place where the pipe is:
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/h4DrRiyT3mGa4h8IzreE_Captura%20de%20pantalla%202016-01-26%20a%20las%2010.26.10.png",
"Captura de pantalla 2016-01-26 a las 10.26.10.png",
"510",
"391",
"#71aead",
""
]
}
]
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Pipes Validation",
"body": "When using Piping in a question, we automatically hide that question until an answer is provided to the pipe emitter question. The emitter question can not be a statement type field and must be answered in order for the typeform to materialize the question where piping is used, otherwise the typeform will end prematurely. Please make sure the piping emitter question will be answered by:\n\n- making it a Required question,\n- not asking your respondents to skip it,\n- and not offering a possibility for it to be skipped when creating your Logic Jumps."
}
[/block]

Piping is a feature that makes it easy to take your respondent's answers and include them in the text of other questions.
You can use piping to:
- Personalise your typeform as a respondent answers
- Ask respondents to confirm information before submitting
- Merge answers from multiple questions into a statement
Here's an example of a JSON payload for a form which uses piping:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"Form with piping\",\n \"fields\": [\n {\n \"type\": \"short_text\",\n \"question\": \"What is your favorite pipes store?\",\n \"ref\": \"to_pipe\"\n },\n {\n \"type\": \"short_text\",\n \"question\": \"So {{to_pipe}} is your favorite store, why?\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
Once this form has been created, and a respondent fills the referenced question, its answer will appear in the place where the pipe is:
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/h4DrRiyT3mGa4h8IzreE_Captura%20de%20pantalla%202016-01-26%20a%20las%2010.26.10.png",
"Captura de pantalla 2016-01-26 a las 10.26.10.png",
"510",
"391",
"#71aead",
""
]
}
]
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Pipes Validation",
"body": "When using Piping in a question, we automatically hide that question until an answer is provided to the pipe emitter question. The emitter question can not be a statement type field and must be answered in order for the typeform to materialize the question where piping is used, otherwise the typeform will end prematurely. Please make sure the piping emitter question will be answered by:\n\n- making it a Required question,\n- not asking your respondents to skip it,\n- and not offering a possibility for it to be skipped when creating your Logic Jumps."
}
[/block]