> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://typeform.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://typeform.ferndocs.com/_mcp/server.

# Create API Walkthroughs

> Learn how to create, update, and customize typeforms using the Create API with practical walkthroughs for common scenarios.

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.

> **Info**
>
> 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.

## Create a new form

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.

> **Warning**
>
> Send images in base64 format, which encodes the image data as ASCII text. You
> can use a tool like the 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.

> **Info**
>
> 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.

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.

## Update an existing form

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.**

> **Warning**
>
> 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.**

## Duplicate an existing form

Suppose you have a feedback form that you used throughout 2017. You want to use the same 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:

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.

Copy the entire 2017 form from the response.

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.

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

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.

## Customize your typeform's welcome page to greet users by their first name

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 the Help Center article if you're not familiar with Typeform's Hidden Fields.

> **Warning**
>
> 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:

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

```json
"hidden": [
  "first_name"
]
```

Send the `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, `https://example.typeform.com/to/vxE08L?first_name=<first name>`.

Send your email with the personalized link.

### Using Hidden Fields to track traffic sources

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

Your typeform will automatically collect the traffic source for each respondent and report it in your results!

> **Info**
>
> It is not possible to inject third-party content into a typeform using the
> Create API.

## Change the ref values for fields in an existing form

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.**

> **Warning**
>
> You cannot modify the default thank you screen reference value. You **can**
> change the reference value for any other question type.

> **Warning**
>
> 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:

## ![Ref in builder](https://public-assets.typeform.com/public/devportal-apps/refinbuilder.gif)

> **Warning**
>
> 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**.

## Ready to do more?

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