When you’re starting a project, or adding functionality that requires collecting form data, Typeform can be a valuable tool. It has a beautiful, accessible, ergonomic design out of the box, and can enable you to get results quickly. As your project matures and you want to integrate that data with the rest of your app, you may be left wondering whether you need to rewrite the form yourself, or somehow integrate Typeform with your codebase. This post aims to help you with the latter, allowing you to keep leveraging Typeform, while keeping the data in a powerful transactional application database.

Here’s a [sample app](https://github.com/k8reindeer/typeform-in-convex) demonstrating how to integrate Typeform with Convex! You may want to remix different parts of it depending on what you’re trying to do with Typeform:

- **A.** Embed a Typeform form in your existing app.
- **B.** Import existing Typeform responses into Convex.
- **C.** Collect new Typeform responses into Convex in real-time.

With the approaches in this post, you can use Typeform as a seamless extension of your <QuickConvex/> app. For example:

- A user [logs in](https://docs.convex.dev/auth) to your Convex app.
- They fill out the form, which silently keeps track of their `user_id` in the `data-tf-hidden` attribute.
- Typeform receives the form response and immediately sends a webhook to your Convex app (in my testing, my Convex app heard about the response *faster* than Typeform’s own website!).
- Your Convex webhook handler saves the response data into the database based on the mapping you set up.
- Your reactive front end shows any UI updates as a result of the changed data, based on Convex’s built-in reactivity.

You could also build a UI that uses the `user_id` to show which of your Convex users was the one who filled out the Typeform, restrict users to only see their own responses, etc.

# A. Embed Typeform in your app

Typeform offers a powerful and easy-to-edit form builder product — and they also make it really easy to embed that into your own website, such as one you built with Convex. Typeform itself has great docs on this [here](https://www.typeform.com/help/a/embed-your-typeform-360029249212).

Here’s how it looks in my project:

![Typeform form in a Convex-backed website](https://cdn.sanity.io/images/ts10onj4/production/8889bc06a599e2ea8b464a6ab17e0d37cb6ae871-2880x1532.png?w=900 "Typeform form in a Convex-backed website")

```jsx
import Script from "next/script";
//...
	<button data-tf-slider="vX9noaqM" data-tf-position="right" data-tf-opacity="100" data-tf-iframe-props="title=Spotted a dog" data-tf-auto-close="500" data-tf-transitive-search-params="user_id" data-tf-medium="snippet" data-tf-hidden={`user_id=${userId}`} className="typeform-button">
	  Record a dog sighting
	</button>
	<Script src="//embed.typeform.com/next/embed.js"></Script>
```

This is *almost* what I copied from Typeform’s embed code, with a few notes:

- Typeform provided a bunch of styles for my button in a `style` property -- I just moved those to my existing CSS and customized them.
- I was using Next.js, and it was having issues loading the `<script>` element that Typeform suggested. I fixed this by using `import Script from "next/script";`.
- Finally, I added this attribute to my button, since my form has a `user_id` [hidden field](https://www.typeform.com/help/a/what-are-hidden-fields-360052676372/):

```jsx
data-tf-hidden={`user_id=${userId}`}
```

This keeps track of which Convex user is logged in when they fill out the form. When a user submits the form with this `data-tf-hidden` attribute, the `user_id` is sent to Typeform along with the rest of the data the user entered into the form. The data then ends up in Convex one of two ways: either by importing into Convex as a migration sometime later (section B below) or via a Typeform webhook in near-real-time (section C below). 

# B. Import existing Typeform responses into Convex.

What if you’ve had a Typeform running for a while, and you have form responses that you’d like to incorporate into your Convex app? Here’s how to get all the existing form responses into a table in Convex.

### Setup

First, grab these files from the [example project](https://github.com/k8reindeer/typeform-in-convex):

- `/scripts/setupTypeformMappings.js`
- `/scripts/importTypeform.js`

If you’re using a schema in your project, you can copy over the schema for the `typeform_metadata` table:

```jsx
typeform_metadata: defineTable({
    typeformFormId: v.string(),
    convexTableName: v.string(),
    typeformFieldId: v.string(),
    convexFieldName: v.string(),
  }).index("by_typeform_form_id", ["typeformFormId"]),
```

You’ll also need a Typeform API key ([get one here](https://www.typeform.com/developers/get-started/personal-access-token/)) and run in your terminal:

`export TYPEFORM_API_KEY=<your_api_key>`

Lastly, you’ll need the form ID of the form whose responses you want in Convex! You can find it in the URL of your Typeform — it’s an 8-character string.

### Map your form to database fields

Run 

`node scripts/setupTypeformMappings.js <your_form_id>`

This will create a file `typeformData/mappings_<your_form_id>.json` — open this file up.

Review and update the `convexTableName` and `convexFieldName` values in the json file — by default it just reformats the question text, so you probably want to give each of the fields a short, descriptive name. If you want to skip importing the responses to a question, just delete it at this step. 

### Move the data

Once you have your mappings the way you want them, run:

`node scripts/importTypeform.js <your_form_id>`

This will write a few more files in `typeformData` and print a few `npx convex import` statements, which will look something like 

```jsx
npx convex import typeform_metadata ./typeformData/typeform_metadata.jsonl
npx convex import dogs ./typeformData/dogs.jsonl
```

(My example table is named `dogs` — you’ll see whatever you chose to name your Convex table!) **Copy and paste each command** to import the data.

Now when you check in your [Convex dashboard](https://dashboard.convex.dev), you’ll see your new table with data populated for all the form responses you already have in Typeform, and the fields will be named as specified in your mappings json file. You can start using this to build your features around your new form response data!

# C. Collect new Typeform responses into Convex in real-time.

If you followed the steps in the previous section, you should have all your form responses *so far*… but what if more respondents fill out your form? This section explains how to set things up with a Typeform webhook so that as you get more Typeform responses, they automatically stay up to date in your Convex database. 

### Setup

For starters, you need to do *most* of the steps in item B to set up your Typeform mappings. Do all the setup and mapping steps there, up through 

```jsx
npx convex import typeform_metadata ./typeformData/typeform_metadata.jsonl
```

(you can skip the `npx convex import` for your new table if you don’t want those responses)

### Create webhook

Grab the file `scripts/setupWebhook.js` and run it:

```jsx
node scripts/setupWwebhook.js --form-id [your-typeform-id] --deployment-url https://[some-animal-123].convex.cloud
```

If you prefer, you can set it up manually following the steps [here](https://www.typeform.com/help/a/webhooks-360029573471/).

You can find the deployment url in `.env` (for prod) or `.env.local` (for dev) — this is set up for you when you set up your Convex project. It will look something like `some-animal-123`. 

This script will print out the value of a `TYPEFORM_SECRET_TOKEN` — add this as an [environment variable](https://docs.convex.dev/production/hosting/environment-variables) to your Convex deployment

### Convex functions to handle the webhook

Finally, you need the code! Copy these files into your project from [this repo](https://github.com/k8reindeer/typeform-in-convex):

- `convex/saveTypeformResponse.ts`
- `convex/authenticateTypeformWebhook.ts`
- `convex/http.ts` (if you already have a `http.ts` just combine the contents into your existing file) See [here](https://docs.convex.dev/functions/http-actions) for more info on serving HTTP requests from Convex.

Run `npx convex dev` to get your Convex functions ready!

### Test it out

You can test your webhook setup by submitting a response to your form! But if your form is too long and you want to test faster than that, there’s also a way to test your webhook, from the same page you set it up. Make sure the webhook is turned on on the Typeform side, then click “View Deliveries”, then “Send Test Request”

# Putting it all together

In this post, we walked through the steps for adapting this example Typeform integration to integrate your own Typeform into your own Convex project. Whether you want to embed a form on the front end, migrate response data to your back end, or hook things up to stay in sync going forward, hopefully this helps accelerate your project. Again, [the code is here](https://github.com/k8reindeer/typeform-in-convex). Let us know how you use it!

Leverage Typeform while keeping the data in a powerful transactional application database.

Get Typeform Data Into Convex

Is your project in Airtable ready for more code and less no-code? I’ve [published some code](https://github.com/k8reindeer/airtable2convex) to help you migrate your data from [Airtable](https://airtable.com/) into <QuickConvex/>.

# Doing the migration

There are 4 steps, with scripts to help you:

1. Map your Airtable schema to Convex.
    
    This gives you the opportunity to rename or skip any tables/fields.
    
2. Move the data.
    
    Download the data using Airtable’s API, and import it to Convex using `npx convex import`
    
3. Re-link documents’ foreign references.
    
    Both Airtable and Convex support referencing other documents by ID — this step is to make your Convex documents refer to each other by Convex ID, not their old Airtable ID.
    
4. Store Airtable attachments in Convex
    
    Airtable only provides expiring links to your attached files. Before the links expire (2 hours), this step moves them to Convex [File Storage](https://docs.convex.dev/file-storage).
    

Check out the [README](https://github.com/k8reindeer/airtable2convex/blob/main/README.md) for more details!

# Keep in mind

As with any data migration, you should be aware that:

- Future data added to Airtable won’t be automatically migrated. To have data sync, you could set up [Convex with Airbyte](https://docs.convex.dev/database/import-export/airbyte). (Despite the names, Airbyte and Airtable are 2 completely different tools!)
- If you re-import all the data, it will have different convex IDs for each document.
- In re-importing Airtable data, you can only append or replace tables, and due to the new IDs, existing references may break.
- To export from Convex, you can use [snapshot export](https://docs.convex.dev/database/import-export/export).

# Summary

In this post we shared a repo with scripts to help you migrate from Airtable. The code is [here](https://github.com/k8reindeer/airtable2convex). Let us know how it goes in [our Discord](https://convex.dev/community)!

Is your project in Airtable ready for more code and less no-code? I’ve published some code to help you migrate your data into Convex.

Moving From Airtable -> Convex

Implementing an "upvote" feature 4 ways with Convex.

Kate Rudolph

All posts by Kate