> ## Documentation Index
> Fetch the complete documentation index at: https://thehyperstack.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fillout Integration

> Issue a credential to everyone who submits a Fillout form, or only to those who pass your quiz.

The Fillout integration connects your Fillout organization to your Hyperstack organization. With it you can:

* Map each Fillout form to a credential group.
* Pick which questions give the name and the email on the credential. Any question works, hidden fields too.
* Add a rule, so only some submissions issue a credential. For example: **Score (quiz) is at least 8**.
* See every submission on the **Logs** tab, with the credential it issued or the reason it issued nothing.

You paste your Fillout API key once. Hyperstack adds the webhooks to your forms for you: you don't copy a URL, and you don't need Zapier.

![The Fillout extension page in Hyperstack Studio with the Connect button](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-overview.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=597b385f1cc58e0f71419e034ac53e88)

## Before you start

* **Hyperstack:** any plan. You must be an administrator of the organization.
* **Fillout:** a Fillout account in which you are an admin of the organization. The API works on every Fillout plan, the free plan included. EU organizations work too.
* At least one [credential group](https://thehyperstack.com/docs/tutorials/credential-setup/creating-credential-group.md) with its design, or let **Sync forms** create them for you.

One Fillout organization connects to one Hyperstack organization. Hyperstack sees every form of that Fillout organization.

> [!NOTE]
>
> Fillout is made by Zite. In Fillout's settings, the API page is called **Zite REST API**. It is the same API key.

## Step 1: Copy your API key in Fillout

**1. Open the Developer settings**

Sign in to Fillout. Click your organization's name at the top left, then **Settings**, then **Developer** ([open it directly](https://build.fillout.com/home/settings/developer)).

**2. Turn on the API and copy the key**

On the **API key** tab, click **Enable API** if there is no key yet. Copy the API key.

![Fillout's Developer settings, API key tab, with the Enable API button](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-api-key.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=b747d46bdbb43fdd5aef8d89883c99a0)

## Step 2: Connect Fillout

**1. Open the Fillout extension**

In the Studio, click **Add integration**, then **Fillout**, then **Connect**. The **Connect Fillout** page opens in a new tab.

**2. Paste the key**

Paste the key into **Fillout API key** and click **Connect Fillout**. Hyperstack checks the key with Fillout before it saves anything. It never shows the key again.

![The Connect Fillout page with the Fillout API key field and the Connect Fillout button](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-setup.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=8ad0883cad016d49ecca045148f63d82)

**3. Open your forms**

The page says **Fillout is connected**, with the date. Click **Map forms**. The **Fillout forms** page lists every form of your Fillout organization.

![Fillout is connected, with the Map forms button](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-connected.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=5c31d5f7e97d720907b4bfaa0e527bf7)

## Step 3: Map your forms to credential groups

* To map one form, click **Choose group** on its row, type to search, and pick a credential group.
* To map many forms at once, click **Sync forms**. Hyperstack creates a credential group for each form that is not mapped yet, named after the form, with the design you pick.

![The group picker open on a Fillout form row](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-map-form.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=836bd571818cab12fb68966479c6578d)

## Step 4: Pick the name, the email and an optional rule

Each mapped form has a **Name and email** column. It says **Matched by label** until you pick. Then Hyperstack reads the form's **Email** question and its question named **Name** or **Full name** (or questions named **First name** and **Last name**).

To pick the questions yourself, click the button in the **Name and email** column.

![The Name, email and rule dialog with Full name for the name, Email for the email, and the rule Score (quiz) is at least 8](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-name-email-rule.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=78155054a99d3ef627168e7b6c13dead)

* **Name:** the question whose answer is the name on the credential.
* **Add to the name (optional):** a second question added after the first one. Use it for a form that asks for the first name and the last name in two questions.
* **Email:** the question whose answer is the email address. Hyperstack sends the credential there. A hidden field works too, so you can put the email in the form's link.
* **Only issue when (optional):** pick a question, a comparison and a value. On a form in quiz mode, you can pick **Score (quiz)**. A calculation shows with its name and "(variable)".

| Comparison | Issues when the answer… |
| - | - |
| **is** | is the value (capital letters don't matter) |
| **is not** | is not the value |
| **contains** | has the value anywhere in it |
| **is at least** | is a number equal to or higher than the value |
| **is at most** | is a number equal to or lower than the value |

For a multiple-choice or dropdown question, Hyperstack compares the text of the option. For a question with more than one answer, such as check boxes, the answers are joined with commas.

Click **Save**. The column shows what you picked, for example **Full name · Email** and **Only if Score is at least 8**.

> [!TIP]
>
> A quiz with a pass mark: turn on quiz mode for the form in Fillout and give the right answers their points. Fillout sends the score with each submission. Then set the rule **Score (quiz) is at least** your pass mark.

## Step 5: Turn on auto-issue

Click **Turn on** under **Auto-issue on form submission**. Hyperstack adds one webhook to each mapped form in Fillout.

![Auto-issue on form submission is On, with three mapped forms](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-auto-issue.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=2e58354a184094b1238aff0dcf0abcff)

Fillout doesn't show webhooks made through its API in the form's integrations, so you won't see Hyperstack's webhook there. Your own webhooks and integrations on the form stay as they are.

Now, when someone submits a mapped form, they get that group's credential. Hyperstack issues and publishes it at once, and sends the email if the group sends one.

## Check what happened: the Logs tab

The **Logs** tab lists every submission that Fillout sends, for 90 days.

![The Logs tab with issued and skipped submissions](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-logs.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=9222bcde58f129529c6b230331901a4b)

* **Issued:** a credential was created. Its ID shows in the **Credentials** column.
* **Skipped:** nothing was issued, and the line says why. For example: the rule wasn't met, the email answer isn't an email address, or the person already has a credential in that group.
* **Failed:** the call was refused, for example because it came to an old webhook address.

Click a row to see the full submission that Fillout sent. Hyperstack adds the form's ID at the top, from the webhook address.

![One log entry: a skipped submission, with the submission that Fillout sent](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-log-entry.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=69c1fe4771dc9bbe4180ff1e7a15bb2a)

## Good to know

* **One credential per email per group.** If a person submits the form again, nothing new is issued.
* **What Hyperstack keeps:** your Fillout API key. A credential keeps only the form ID, the submission ID and when it was sent. Hyperstack doesn't copy the form answers into the credential.
* **Security:** Fillout doesn't sign its webhooks, so each webhook address has a secret of its own. When you disconnect, the secret is deleted, and Hyperstack refuses calls to the old address.
* **API limits:** Fillout's free plan allows 1,000 submissions a month. Hyperstack uses no API call for a submission, only when you open the forms page or map a form.
* **Turn off auto-issue** to stop issuing but keep your mappings. Hyperstack removes the webhooks from your forms.

## Disconnect Fillout

Click the **⋯** button at the top right of the Fillout page, then **Disconnect Fillout**. Hyperstack removes its webhooks from your forms in Fillout and deletes your mappings. Credentials you already issued stay as they are.

![The Disconnect Fillout dialog](https://mintcdn.com/hyperstack/8rTs2ToGyW0SKUm5/images/fillout-disconnect.webp?fit=max\&auto=format\&n=8rTs2ToGyW0SKUm5\&q=85\&s=b0ef211a1385844c1033892039f237f0)

## Troubleshooting

| What you see | What to do |
| - | - |
| **Fillout didn't accept this API key** | Copy the key again from **Settings → Developer** in Fillout. If someone clicked **Regenerate** in Fillout, the old key stops working: disconnect Fillout and connect again with the new key. |
| **Fillout is already connected** | Disconnect Fillout first to use another key. |
| **The mapping is saved, but Fillout didn't accept the form's webhook** | Turn auto-issue off and on again. |
| A submission is **Skipped**: "no Email question" or "no name answer" | Pick the questions in the **Name and email** column. |
| A submission is **Skipped**: "is not an email address" | The question picked for the email got another answer. Pick the right question. |
| A submission is **Skipped**: "The rule wasn't met" | The answer didn't pass the rule. Check the rule in the **Name and email** column. |
| A submission is **Skipped**: "Auto-issue is off" | Turn on auto-issue. |

Questions or problems: [support@thehyperstack.com](mailto:support@thehyperstack.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.