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.
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.
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.
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.
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.
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.
GEThttps://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:
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.
PUT https://api.typeform.com/forms request that adds the
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.
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.
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:
first_nameas the variable:
"hidden": [ "first_name" ],
POST https://api.typeform.com/forms request to create your new typeform.
Create your email message in your CRM or marketing tool, using the "first name" merge tag in your typeform's URL. For example,
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!