Create API walkthroughs

The Create API lets you send requests to create, retrieve, update, and delete (CRUD) forms, images, and themes. You can combine these requests to create new typeforms and customize them with images, videos, and themes. Let's walk through some common uses.

NOTE: These walkthroughs assume that you already have your Typeform access token and know how to pass it in the Authorization header of your request. If you need an access token or don't know how to pass it in the Authorization header, go to the Get started section first.

You want to create a new form quickly, without using the Typeform admin panel.

1. You want to include images with your form, but you need to check which images are already in your account. Send a GET https://api.typeform.com/images request to retrieve a list of all the images in your account. And note the id for each image you want to use in your new form.

2. An image that you want to use isn't in your Typeform account yet, so you'll have to add it. All images you want to use in a typeform must be uploaded to your account before you can create a form that uses them. Send a POST https://api.typeform.com/images request to add the new image.

NOTE: Send images in base64 format, which encodes the image data as ASCII text. You can use a tool like this Base64 Image Encoder to get the base64 code for the image you want to add. Base64 encoders may add descriptors to the code (such as data:image/png;base64,). Do not include these descriptors in your image string — include only the base64 code.

3. You want to use a theme for your new typeform. Check which themes are available in your account by sending a GET https://api.typeform.com/themes request.

4. You don't see the theme you want to use. Add it using POST https://api.typeform.com/themes. Note the new theme's theme_id in the response so you can include it when you create your form.

5. Now you're ready to create and send your POST https://api.typeform.com/forms request.

NOTE: Take a moment to copy the form_id for your new typeform, which is listed in the response to your POST request. You'll need the form_id later if you need to update or delete the typeform.

6. If you want to confirm that your new form was successfully added to your typeform account, send a GET https://api.typeform.com/forms request. Forms are listed in descending order based on when they were last updated, so your new form should be the first one in the response.

You already have a form, but your company updated its website and your typeform's theme needs to match. You also want to add a field so respondents can provide an email address for follow-up. Plus, you want to make the background image a little brighter and remove the "Submit" button transparency. Oh, and you need to make these changes without losing any of the submissions you've already received. Here's the walkthrough:

1. To update the theme, send a PUT https://api.typeform.com/themes request. You can take care of changing the theme to match your company's website, brightening the background image, and removing the "Submit" button transparency with this request.

2. Send a PUT https://api.typeform.com/forms request that adds the email field to your form. Your request body must include all the existing form fields, in addition to the new email field.

NOTE: Your PUT request will overwrite the previously stored form with the given form_id. Any new fields in your request will be added to the form. Likewise, any fields you don't include in your request will be deleted from the form. Make sure your PUT request includes every field you want to include in your updated form.

Suppose you have a feedback form that you used throughout 2017. You want to use the same form form for 2018, with a couple small changes. In this case, you can duplicate your 2017 form, then follow the instructions for updating a form to customize it for 2018. Here's how:

1. Retrieve your 2017 form by sending a GET https://api.typeform.com/forms/{form_id} request. If you don't know the form_id for your 2017 form, send a GET https://api.typeform.com/forms request to retrieve a list of JSON descriptions for all forms in your Typeform account.

2. Copy the entire 2017 form from the response.

3. Prepare a new POST https://api.typeform.com/forms request and paste the 2017 form in the request body. Before you send the request, delete every id field in the form. The id fields are in the form, field, and choices objects. Also, make the changes you want for your 2018 form in the request body before you send the request.

4. Send the POST https://api.typeform.com/forms request.

5. To confirm that your 2018 form was successfully added to your typeform account, send a GET https://api.typeform.com/forms request. Forms are listed in descending order based on when they were last updated, so your new form should be the first one in the response.

You're planning to email your typeform to all of your newsletter subscribers. Since your database of subscribers includes their names, you can use Hidden Fields to personalize each typeform link. When a subscriber clicks your emailed link, they'll see a greeting that includes their first name.

Customizing typeforms requires Hidden Fields, which is a PRO account feature. Check out this Help Center article if you're not familiar with Typeform's Hidden Fields.

For details about how Hidden Fields work in the Create API, see this section.

NOTE: You are responsible for any information you share with Hidden Fields. Recording and transmitting identifying information, like email addresses, is prohibited by some services (like Google Analytics). Make sure the way you use Hidden Fields stays within the laws of your country and the terms and conditions of any service you are using with Typeform.

Hidden Fields work by adding name-and-value pairs like first_name=Joe to the end of your typeform’s URL. In this case, you'll replace Joe in your typeform URL with the "first name" merge tag that your customer relationship management (CRM) tool uses. So you'll need a CRM or marketing automation tool to send your emails, including the database with your subscribers' names. Here's the walkthrough:

1. Build the request for your new typeform. The body of your request will include the hidden element, with first_name as the variable:

"hidden": [
  "first_name"
  ],

2. Send the POST https://api.typeform.com/forms request to create your new typeform.

3. Create your email message in your CRM or marketing tool, using the "first name" merge tag in your typeform's URL. For example, https://example.typeform.com/to/vxE08L?first_name=<first name>.

4. Send your email with the personalized link.

You can use Hidden Fields to customize your typeforms and collect information about your audience in interesting ways. For example, if you create a form to share through your social media channels, you can use a source hidden field to learn where each respondent found and clicked your link.

When you build your form, include a hidden element with source as a variable. Then, just specify the source in your links: https://example.typeform.com/to/vxE08L?source=Facebook> for a link to share on Facebook, https://example.typeform.com/to/vxE08L?source=Twitter> for a link to share on Twitter, and so on. Your typeform will automatically collect the traffic source for each respondent and report it in your results!

NOTE: It is not possible to inject third-party content into a typeform using the Create API.

Suppose that when you created your form, you used random characters for the ref values for each field. Now, you would prefer to use readable names for the ref values to make it easier to match answers in your responses with questions in the form, but remember they must be less than 255 characters and in valid regular expression format ^[a-zA-Z0-9_-]+$.

You can update all of your ref values in a single step:

1. Send a PUT https://api.typeform.com/forms request that specifies a value for the ref field for each field in your form. Your request body must include all the existing form fields, in addition to the ref field.

One exception: you cannot modify the default thank you screen reference value. You can change the reference value for any other question type.

NOTE: Your PUT request will overwrite the previously stored form with the given form_id. Any new fields in your request will be added to the form, and any fields you don't include in your request will be deleted from the form. Make sure your PUT request includes every field you want to include in your updated form.

Use the ref builder in your Typeform.com admin panel

For a different approach to updating the ref values in your typeform, try the ref builder feature in the admin panel:

1. Log in to your Typeform account.
2. Open one of your typeforms in your workspace.
3. Click the Question settings icon for the question whose ref value you want to change.
4. In the Question Settings panel, under Question reference, click Edit.
5. Enter your desired ref value in the field and click Apply.
6. In the confirmation pop-up window, click Yes, edit it.

Note that you cannot modify the default thank you screen reference value. Thank you screens are the only exception---you can change the reference value for any other question type.

Here's a quick example of how it works:

NOTE: And remember, if you change a question's reference, you might break any integration you connected to the typeform that includes the question. Make sure you want to change the reference before you click Yes, edit it.

Great! If you need your access token, check out Get started. You can also take a look at the Create API reference for information about endpoints.