# Quick start

Go from an empty workspace to a submission that lands in the right inbox. It takes about ten minutes.

**On this page you will learn**

- Sign in and create your workspace
- Create a form with AI or from a template
- Connect your website to the form
- Build, test and turn on a first flow
- Send a first submission with HTML, JavaScript or cURL
- Fix the most common reasons a submission is refused

## Before you begin

- An email address you can open right now. Formpik signs you in with a link or a code, there is no password.
- A website where you can edit a form, or a terminal with cURL. You can also test everything from the form builder without a website at all.
- The email address or chat channel where submissions should go. Email works with no setup.
- Nothing to pay. Everything below works on the free Starter plan, see [Plans and limits](https://formpik.com/docs/plans).

## Step by step

1. **Sign in and name your workspace**

   Open [Sign in](https://formpik.com/login) and enter your email. Formpik sends an email with a sign-in button and a 6-digit code. Click the button, or type the code on the sign-in page. Both work once and for 15 minutes.

   The first time, you land on a welcome page. Enter your name and a workspace name, such as your company or client name. The workspace is where your forms, flows, submissions and team live. You arrive on the overview, which shows a short "Get your first submission flowing" checklist.
2. **Create a form**

   Go to **Forms** and choose **New form**. You have two ways to start:

   - **Describe it with AI**: write a sentence such as "a quote request with name, email, the service they need, a budget and a brief upload". AI drafts the fields, and nothing is saved until you create the form.
   - **Start from a template**: pick one of 8 ready-made forms, such as contact, lead or support, or start blank.

   The form opens in the builder with a live preview. Click any field to change its label, its key, its type or whether it is required. The **key** is the name your website sends, such as `email`, so keep it short and lowercase.
3. **Connect your website**

   Open the form's **Connect** tab and choose **Add source**. Pick the platform your site runs on, give the source a name (it shows in every submission so you know where it came from) and, optionally, the website address.

   You get an endpoint address and a setup guide with a ready-made snippet for that platform. Point your form at the address and make sure each input's `name` matches a field key. The source shows `Waiting for first submission` until something arrives. See [Connect a website](https://formpik.com/docs/sources) for each platform.
4. **Build a flow**

   Go to **Flows** and create one for your form. Start from a template: **Notify the team** emails every submission, **Notify and confirm** also thanks the sender, and **Route by answer** sends each option of a dropdown somewhere else.

   A good first flow is Validate, then Ask AI to summarize the message, then Route by answer, with a Send email or Post to Slack step on each path. Click a step to set it up in the panel on the right. Put answers into a message with variables such as `{{full_name}}`, see [Variables and templates](https://formpik.com/docs/templates).
5. **Test it and go live**

   Choose **Test run** in the editor. The panel fills in sample answers for your form; change any of them and choose **Run test** to see the path the submission takes and what each step would do. Nothing is sent during a test, so change an answer and run it again to try every branch.

   When you are happy, choose **Go live**. If a step is not set up yet, for example an email with no recipient, Formpik says what to fix and points at the step instead. A live flow shows `Live` and runs for every new submission of its form.
6. **Send a real submission**

   Fill in the form on your website once, or use one of the examples below. Your website gets an answer right away, and the flow runs straight after.

   Open **Submissions**. The new submission appears within 30 seconds, with its answers and a timeline of every step the flow took. When every flow finished, it shows `Delivered`, and the source changes to `Receiving`.

> **No website yet?**
>
> In the form builder, fill in the live preview (or choose **Fill sample answers**) and submit it. It is saved as a test submission with a test badge, your live flows run as a test, and nothing is sent.

## Send a first submission

Every source has its own endpoint: `POST https://formpik.com/api/in/{key}`. Replace `YOUR_SOURCE_KEY` with the key from your source, and the field names with the keys of your form. The examples use a quote form with `full_name`, `email`, `service` and `message`.

*HTML form*

```html
<form action="https://formpik.com/api/in/YOUR_SOURCE_KEY" method="POST">
  <label for="full_name">Your name</label>
  <input id="full_name" name="full_name" type="text" required>

  <label for="email">Email</label>
  <input id="email" name="email" type="email" required>

  <label for="service">What do you need?</label>
  <select id="service" name="service" required>
    <option value="website">A new website</option>
    <option value="branding">Branding</option>
    <option value="seo">SEO</option>
  </select>

  <label for="message">Tell us about the project</label>
  <textarea id="message" name="message" rows="4"></textarea>

  <!-- Optional: where to send the visitor afterwards -->
  <input type="hidden" name="_redirect" value="https://example.com/thanks">

  <!-- Spam trap: keep it hidden and empty -->
  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">

  <button type="submit">Send</button>
</form>
```

*JavaScript*

```js
const response = await fetch('https://formpik.com/api/in/YOUR_SOURCE_KEY', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        full_name: 'Jane Cooper',
        email: 'jane@example.com',
        service: 'website',
        message: 'We would like a quote for a new website.'
    })
})

const result = await response.json()

if (response.ok) {
    // result.message is the success message of your form
    showThanks(result.message)
}
else {
    // result.message says what went wrong, in plain words
    showError(result.message)
}
```

*cURL*

```bash
curl -X POST "https://formpik.com/api/in/YOUR_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name": "Jane Cooper", "email": "jane@example.com", "service": "website", "message": "We would like a quote for a new website."}'
```

- **HTML form**: a classic form post. Formpik stores it and sends the visitor on with a redirect: to `_redirect` when you send one, otherwise to the redirect address in the form's settings, otherwise back to the page they came from with `?submitted=1` added. With none of these, the visitor sees a simple thank you page with your success message.
- **JavaScript** and **cURL**: JSON in, JSON out. You get the result below and show your own message.
- Uploading files? Use `enctype="multipart/form-data"` on the HTML form, or send a `FormData` body with fetch. See [Send a submission](https://formpik.com/docs/api/submit) for every format and limit.

### What the answer looks like

A stored submission answers with status 200, its id and the success message of the form:

*Response*

```json
{
  "ok": true,
  "id": "sub_k3x9q2mfa7wp",
  "message": "Thanks, we've received your submission."
}
```

If the same answers arrive again from the same source within 10 seconds, for example after a double click, you get the first submission's id with `"duplicate": true` and nothing new is stored. A refused submission answers with an error status and a message you can show as it is:

*Response 403*

```json
{
  "ok": false,
  "message": "This form is paused, so it is not taking submissions right now."
}
```

> **Check an address in your browser**
>
> Open the endpoint address in a browser tab. A working key answers with the name of its form: `This is the Formpik endpoint for "Quote request". Send submissions with POST.` A wrong key answers 404.

## Troubleshooting

When a submission is refused, nothing is stored, and the answer says why. These are the ones you are most likely to meet:

| Status | What it means | What to do |
| --- | --- | --- |
| 404 | The key in the address does not belong to any source. | Copy the address again from the Connect tab. A deleted source or form stops working at once. |
| 403 | "Submissions from <website> are not allowed for this form." The form has a list of allowed websites, and the page that sent it is not on it. | Add the website under **Allowed websites** in the form's Settings tab. Subdomains of a listed website are allowed too. |
| 403 | The source is paused, or the form is paused. | Turn the source back on, or switch **Accept submissions** back on in the form's settings. |
| 401 | The request carries an API key that does not belong to this workspace. | Use a key from the API keys page of the same workspace, or leave the Authorization header out. |
| 400 | The submission is empty, or the body is not valid JSON. | Send at least one answer, as one JSON object or as form fields. |
| 415 | The body is in a format the endpoint does not read. | Send `application/json`, a regular form post or `multipart/form-data`. |
| 429 | Too many submissions: more than 120 a minute from one address, more than the form's hourly limit per visitor, or the workspace reached its monthly submissions. | Wait and try again. Raise **Limit per visitor** in the form's settings if real people hit it, or change plan when the month is full. |

> **Stored, but nothing arrived?**
>
> Then the submission was accepted and a flow did not deliver it. Open it in Submissions: the timeline shows each step and the reason for any failure. If it says no live flow used the form, go live with a flow and choose **Run flows again**.

## Questions

### Do I have to rename the inputs on my existing form?

Not necessarily. With **Learn new fields automatically** on (the default), answers under names the form does not know yet are added as new fields. Renaming a field's key in the builder later updates every flow that uses it, but your website has to send the new name too.

### Does a test submission count toward my monthly limit?

No. Only real submissions that arrive through a source count toward the plan's monthly submissions.

### Can one form take submissions from several websites?

Yes. Add one source per website. Each gets its own key, so you can pause or remove one without touching the others, and every submission shows which source it came from.

### Why did my submission land under Spam?

The hidden `_gotcha` field was filled in, or the form's bot check failed. Make sure the spam trap input stays hidden and empty. Open the submission to see the exact reason, and choose **Not spam** to release it.

## Next steps

- [How Formpik works](https://formpik.com/docs/concepts): The building blocks and the life of one submission.
- [Flows](https://formpik.com/docs/flows): Every step you can add, and how branches work.
- [Connect a website](https://formpik.com/docs/sources): Setup guides for each website platform.
- [Send a submission](https://formpik.com/docs/api/submit): Every format, option and answer of the endpoint.

---

Source: https://formpik.com/docs/quick-start
