# Send a submission

Every source has an endpoint that takes submissions as JSON, as a regular form post, or as a multipart upload with files. It stores the submission, answers right away, and then runs the live flows of the form.

**On this page you will learn**

- The endpoint, its headers and its body
- Examples in cURL, JavaScript, Python and HTML
- How to upload files
- What it answers, for JSON and for classic form posts, including where the visitor goes next
- How duplicates and Idempotency-Key work
- CORS and the order of every check

`POST https://formpik.com/api/in/{key}`

Stores the submission, answers right away, and then runs the live flows of the form.

`OPTIONS https://formpik.com/api/in/{key}`

Answers browser preflights: 204 for an allowed website, 403 otherwise.

`GET https://formpik.com/api/in/{key}`

Says which form the endpoint belongs to. Handy to check an address, it stores nothing.

`POST https://formpik.com/api/in/{key}/validate`

Checks answers against the field rules and stores nothing, for websites that show what to fix before sending.

`GET https://formpik.com/api/in/{key}/rules`

Lists the fields of the form with their types, options and rules.

## Path

- `key` (string, required): The source key: 6 to 64 lowercase letters and digits. It is part of the source's `endpoint_url`, shown in the form's Connect tab, on the Sources page and by [GET /api/v1/sources](https://formpik.com/docs/api/sources#list). A key in capitals is read in lowercase.

## Headers

- `Content-Type` (string, required): `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`. `text/plain` with a JSON body works too. Anything else gets a `415`.
- `Authorization` (string): `Bearer <API key>`. Optional. With any key of the form's workspace, whatever its access, the allowed websites check and the bot check are skipped. A wrong key gets a `401` instead of being ignored.
- `Idempotency-Key` (string): Any text up to 200 characters, such as order-1042. Sending the same key to the same source again within 24 hours returns the first submission instead of storing a new one.
- `Accept` (string): A request that asks for `text/html` without sending JSON is treated as a classic form post and gets a redirect or a page. Everything else gets JSON.
- `X-Requested-With` (string): Any value. Forces a JSON answer, also for a form post or an upload.

## Body

Send each answer under the key of its field. Read the keys from the Connect tab or from the `fields` of [GET /api/v1/forms/{id}](https://formpik.com/docs/api/forms#one).

- Text is stored as it is. Numbers and true or false are stored as text, so `5` becomes `"5"`.
- Lists are stored as lists, for fields that take several values. In a form post, repeat a name or end it with `[]`: `interests[]=speed&interests[]=support`. The `[]` is dropped from the stored key.
- In JSON, the answers can also sit inside a `data` object: `{"data": {"email": "jane@example.com"}}`.
- Nested objects are stored as JSON text. `null` values are left out.
- Answers with names the form does not know are still stored. With Learn new fields automatically on, they are added to the form as fields, up to 50 per submission.
- The endpoint does not check required fields or option values. A Validate step in a flow does, and can send incomplete submissions down another path.

**Special fields**

- `_redirect` (string): Where to send the visitor afterwards, as a full `https://` or `http://` address. See [Where the visitor goes next](https://formpik.com/docs/api/submit#after).
- `_gotcha` (string): The spam trap. Leave it empty. When the form has its spam trap on and this has a value, the submission is stored as spam and no flows run.
- `cf-turnstile-response` (string): The Cloudflare Turnstile token, when the form uses Turnstile as its bot check.
- `g-recaptcha-response` (string): The Google reCAPTCHA token, when the form uses reCAPTCHA as its bot check.

These fields, and `h-captcha-response`, are read by the endpoint and never stored with the answers.

### Limits

| What | Limit | Above it |
| --- | --- | --- |
| Whole request | 25 MB | 413 |
| Answers without files | 64 KB in total | 413 |
| Fields | 200 per submission | Further names are dropped |
| One value | 10,000 characters | Cut to the limit |
| One list | 100 values | Cut to the limit |
| Field name | 100 characters | Cut to the limit |
| Files | 10 per submission, 10 MB each | 413 |

## Examples

*cURL*

```bash
curl -X POST "https://formpik.com/api/in/YOUR_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{"full_name": "Jane Cooper", "email": "jane@example.com", "topic": "sales", "interests": ["speed", "support"]}'
```

*JavaScript*

```js
// In the browser, from one of the form's allowed websites
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",
    topic: "sales",
    interests: ["speed", "support"]
  })
})

const result = await response.json()

if (!result.ok) {
  showError(result.message) // written for people, safe to show
} else if (result.redirect) {
  showThanks(result.message)
  setTimeout(() => window.location.assign(result.redirect), result.redirectDelay * 1000)
} else {
  showThanks(result.message)
}
```

*JavaScript*

```js
// On your server, with an API key: skips allowed websites and the bot check
const response = await fetch("https://formpik.com/api/in/YOUR_SOURCE_KEY", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.FORMPIK_API_KEY}`,
    "Idempotency-Key": `signup-${user.id}`
  },
  body: JSON.stringify({ full_name: user.name, email: user.email, plan: user.plan })
})

const { ok, id, duplicate, message, reason } = await response.json()

if (!ok) console.error(response.status, reason)
```

*Python*

```python
import os
import requests

response = requests.post(
    "https://formpik.com/api/in/YOUR_SOURCE_KEY",
    headers={
        "Authorization": f"Bearer {os.environ['FORMPIK_API_KEY']}",
        "Idempotency-Key": "order-1042",
    },
    json={
        "full_name": "Jane Cooper",
        "email": "jane@example.com",
        "topic": "sales",
        "interests": ["speed", "support"],
    },
    timeout=30,
)

result = response.json()
print(response.status_code, result["ok"], result.get("id"), result["message"])
```

*HTML*

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

  <label><input type="checkbox" name="interests[]" value="speed"> Speed</label>
  <label><input type="checkbox" name="interests[]" value="support"> Support</label>

  <input type="hidden" name="_redirect" value="https://yourcompany.com/thanks">
  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">

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

On a website you do not have to write the fetch yourself: the Formpik site script catches the form, posts it and shows the message or goes on to the next page. See [After submitting](https://formpik.com/docs/sources#after).

## Files

Send files as a `multipart/form-data` upload. Each file goes under the key of its file field, with `[]` when the field takes several.

*cURL*

```bash
curl -X POST "https://formpik.com/api/in/YOUR_SOURCE_KEY" \
  -F "email=jane@example.com" \
  -F "brief=@brief.pdf" \
  -F "photos[]=@roof-front.jpg" \
  -F "photos[]=@roof-back.jpg"
```

*JavaScript*

```js
const body = new FormData()
body.append("email", "jane@example.com")
body.append("brief", fileInput.files[0])

for (const photo of photosInput.files) body.append("photos[]", photo)

// Leave Content-Type out: the browser adds it with the upload boundary.
// X-Requested-With asks for a JSON answer instead of a redirect.
const response = await fetch("https://formpik.com/api/in/YOUR_SOURCE_KEY", {
  method: "POST",
  headers: { "X-Requested-With": "fetch" },
  body
})
const result = await response.json()
```

*Python*

```python
import requests

with open("brief.pdf", "rb") as brief, open("roof-front.jpg", "rb") as photo:
    response = requests.post(
        "https://formpik.com/api/in/YOUR_SOURCE_KEY",
        data={"email": "jane@example.com"},
        files=[
            ("brief", ("brief.pdf", brief, "application/pdf")),
            ("photos[]", ("roof-front.jpg", photo, "image/jpeg")),
        ],
        timeout=60,
    )

print(response.json())
```

- Up to 10 files, 10 MB each, within the 25 MB request limit. An 11th file or a larger file refuses the whole submission with a 413 that names the file.
- Empty file inputs are ignored.
- The answer of a file field is its file name, or a list of names. File names are kept up to 120 characters.
- Files are stored privately. The API lists them under `files` of [one submission](https://formpik.com/docs/api/submissions#one), and [GET .../files/{fileId}](https://formpik.com/docs/api/submissions#files) answers with a link that works for 15 minutes.

## Answer

### JSON requests

A stored submission answers `200` with its id and the form's success message:

*200 OK*

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

- `ok` (boolean, required): `true` when the submission was stored, or was a repeat of one that was.
- `id` (string): The submission id. Read it with [GET /api/v1/submissions/{id}](https://formpik.com/docs/api/submissions#one).
- `duplicate` (boolean): Only present, and `true`, when this request was a repeat. `id` is then the first submission.
- `message` (string, required): The form's success message, or on an error what went wrong. Written for people, so you can show it as it is.
- `redirect` (string): Only present when this submission should go on to a page. See [Where the visitor goes next](https://formpik.com/docs/api/submit#after).
- `redirectDelay` (number): With `redirect`: the seconds to show `message` before going on, `0`, `3` or `5`.
- `redirectRule` (boolean): With `redirect`: `true` when a Pages by answer rule picked the page. Such a page should win over a redirect the website sets itself.

*200 OK, with a page to go to*

```json
{
  "ok": true,
  "id": "sub_7k2m9x4q1w3e",
  "message": "Thanks, we've received your submission.",
  "redirect": "https://yourcompany.com/thanks?name=Jane",
  "redirectDelay": 3,
  "redirectRule": false
}
```

Errors carry `"ok": false`, a `message` and a `reason`:

*403 Forbidden*

```json
{
  "ok": false,
  "message": "Sorry, something went wrong. Please email us at hello@yourcompany.com.",
  "reason": "Submissions from example.org are not allowed for this form. Add the website under the form's allowed websites."
}
```

`reason` always says exactly what went wrong, so log it. `message` is the form's own **Error message** when it has one, and the same text as `reason` otherwise, so you can show it to visitors as it is.

### Answers that break a field rule

When the form has **Refuse answers that break the field rules** on, a submission that breaks one is refused with a `422` and nothing is stored. `errors` holds one message per field, keyed by the field key, written for visitors:

*422 Unprocessable Content*

```json
{
  "ok": false,
  "message": "Please check the highlighted answers and try again.",
  "reason": "Email: Use your work email address. Country: Choose one of the listed countries",
  "errors": {
    "email": "Use your work email address",
    "country": "Choose one of the listed countries"
  }
}
```

With the setting off, the submission is stored anyway and its broken rules are kept as `meta.rule_errors`, where a Validate step or your own code can act on them. See [Field rules](https://formpik.com/docs/field-types#rules) for every rule.

A `200` means the submission is stored, not that it was delivered: the flows run after the answer. Read the submission later, or use a webhook, to see the result. Spam is also answered with `200`, so bots learn nothing.

### Classic form posts

A form post from a browser that asks for HTML gets a page or a redirect instead of JSON:

1. When there is a page to go to and the form shows its message first, a `200` Thank you page with the success message that goes on after `redirectDelay` seconds.
2. When there is a page to go to right away, a `303` redirect there, so a reload never posts twice.
3. Otherwise a `303` back to the page the form was on (the `Referer`) with `?submitted=1` added.
4. When there is no such page either, a `200` Thank you page with the success message.

Refused classic posts get a short Not sent page with the message and the error status.

## Where the visitor goes next

The page in `redirect` is the first of these that gives a valid address:

1. The first **Pages by answer** rule of the form that matches the answers. `redirectRule` is then `true`.
2. The `_redirect` field sent with the submission.
3. The form's own page, when its settings say **Go to a page** after submitting.

- Addresses set in the form can carry answers, such as `https://yourcompany.com/thanks?name={{full_name}}`. Each answer is URL encoded and can only come after the website address, so a visitor can change what the page shows but never which website they go to. `{{submission.id}}` and `{{form.name}}` work too.
- Placeholders in `_redirect` are removed, since the page itself sent it.
- With none of the three, there is no `redirect` and the visitor stays on the page with the message.

The settings behind this are `after_submit`, `redirect_url`, `redirect_rules`, `redirect_delay`, `success_message` and `error_message`, which you can change with [PATCH /api/v1/forms/{id}](https://formpik.com/docs/api/forms#settings).

## Check answers without storing

`POST /api/in/{key}/validate` takes the same bodies, headers and allowed websites as the endpoint, runs the same field rules, and stores nothing. It answers `200` whether the answers pass or not, so a website can check one field as the visitor leaves it, or a whole step of a multi-step form.

*200 OK*

```json
{
  "ok": true,
  "valid": false,
  "errors": {
    "email": "Use your work email address"
  },
  "message": "Please check the highlighted answers and try again.",
  "reason": "Email: Use your work email address"
}
```

- `valid` (boolean, required): `true` when every answer passes. Fields you did not send count as empty, so required ones show up in `errors`: read only the ones you checked.
- `errors` (object, required): One message per field key. Empty when everything passes.
- `message, reason` (string): Only when something fails, the same as in the `422` of the endpoint.

It allows 300 checks a minute per address. **One per answer** and **Blocked words** stay on the server: one per answer is checked only on a real send, so this address never reveals who already signed up, and blocked words are checked but never listed.

`GET /api/in/{key}/rules` answers the fields that collect answers, each with `key`, `label`, `type`, `required`, `multiple`, `options` for choice fields (a Country field lists only the countries its rule keeps), `accept` for files, and `rules` in the same snake_case names as the API. It is cached for a minute and needs no key.

## Duplicates and retries

- **Same answers within 10 seconds.** When the same source gets exactly the same answers again within 10 seconds, nothing new is stored. This catches double clicks and impatient retries.
- **Idempotency-Key.** When you send a key, a repeat with the same key to the same source within 24 hours answers with the first submission, even if the answers changed. Use one key per thing you send, such as `order-1042`.
- A repeat answers like the original, with the first id and `"duplicate": true` in JSON, or the same kind of redirect for a classic post. It runs no flows and does not count toward your monthly submissions.
- Both checks are kept in the memory of the endpoint server, so treat them as protection against quick retries. After a restart a repeat can be stored again, so key your own records on the submission id when it matters.
- On a `500` or a network error, it is safe to send again with the same `Idempotency-Key`.

*200 OK, a repeat*

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

## Browsers and CORS

- The endpoint answers `OPTIONS` preflights with `204` for allowed websites and lets the browser keep that answer for a day.
- Browsers may post from any of the form's allowed websites or their subdomains, or from anywhere when the form has none.
- A preflight from another website gets a `403` without CORS headers, so the browser stops a JSON request there. A plain form post needs no preflight: it gets the `403` answer with CORS headers, so the page can read why and show it.
- Allowed request headers: `Content-Type`, `Authorization`, `Idempotency-Key` and `X-Requested-With`.
- Requests without an `Origin` or `Referer`, such as server calls, are never blocked by allowed websites.

## Order of checks

The endpoint checks every request in this order and stops at the first problem, so the error you get is the first one that applies:

1. **Key and access**: Source key (404), method (405), API key (401), allowed website (403), paused source or form (403).
2. **Rate and body**: 120 a minute per address (429), body type (415), size (413), empty or broken body (400).
3. **Repeats, rules and limits**: Repeats answer the first id. Then the field rules when the form refuses broken answers (422), monthly submissions and the hourly limit per visitor (429).
4. **Store and run**: Spam checks, store with files, answer, then run the live flows.

## Common questions

### Do I need the API key in a web page?

No, and never put it there. Browsers post without a key, protected by allowed websites, the spam trap and the bot check. Use a key only from your own server.

### Which API key should my server use to send?

A read only key is enough. Sending to the endpoint is not a change under /api/v1, so any key of the workspace skips the allowed websites check and the bot check.

### Why do I get 200 but the submission shows Needs attention?

The answer only says the submission was stored. A flow step failed afterwards, for example a webhook that answered with an error. The run history in the inbox, or the runs of the submission in the API, show the reason.

### Can I send booleans and numbers?

Yes. They are stored as text, so `true` becomes `"true"` and `5` becomes `"5"`. For yes or no fields, send `yes` or `no`.

### How do I check an endpoint address without sending anything?

Open it in a browser. A GET answers with the name of the form it belongs to, or a 404 when the key does not exist.

- [Submissions](https://formpik.com/docs/api/submissions): Read what was sent and its runs.
- [Sources](https://formpik.com/docs/api/sources): Endpoint addresses and their keys.
- [Errors and limits](https://formpik.com/docs/api/errors): Every refusal and how to fix it.

---

Source: https://formpik.com/docs/api/submit
